pvshow-sdk v0.1.0

SDK & CLI Developer Documentation

Integrate SD2-Agent text-to-image, text-to-video, and image-to-video capabilities into your applications via SDK, CLI, or REST API.

bash

pip install pvshow-sdk

Quick Start

Ensure the SD2-Agent adapter is running, then install the SDK to start generating.

Prerequisites

bash

# Docker Compose
docker compose up -d seedance-adapter

# Or run locally
cd services/seedance-adapter
pip install -r requirements.txt
uvicorn app.main:app --port 8002

30-Second Example

bash

# Text to Video
pvshow text2video -p "一只金毛犬在海边奔跑，阳光明媚"

# Check service health
pvshow health

CLI Reference

After installation, use the pvshow command. Also supports python -m pvshow_sdk.

Global Options

Option	Env Variable	Default	Description
--base-url, -u	PVSHOW_BASE_URL	http://localhost:8002	SD2-Agent adapter address
--model, -m	PVSHOW_MODEL	sd2-agent	Model name

pvshow text2image

Generate images from text prompts.

Option	Default	Description
--prompt, -p	—	Generation prompt (required)
--ratio, -r	1:1	Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
--resolution	2k	Resolution (1k, 2k)
--no-wait	—	Return immediately without waiting

bash

pvshow text2image -p "赛博朋克风格的城市夜景，霓虹灯闪烁"
pvshow text2image -p "山水画意境" -r 16:9 --no-wait

pvshow text2video

Generate videos from text prompts.

Option	Default	Description
--prompt, -p	—	Generation prompt (required)
--duration, -d	5	Duration in seconds
--ratio, -r	16:9	Aspect ratio
--resolution	720p	Resolution (720p, 1080p)
--no-wait	—	Return immediately without waiting

bash

pvshow text2video -p "日落时分，海浪拍打沙滩，金色余晖映照水面"
pvshow text2video -p "烟花在夜空绽放" -d 10 --resolution 1080p

pvshow image2video

Animate a first-frame image with a prompt.

Option	Default	Description
--prompt, -p	—	Generation prompt (required)
--image, -i	—	First frame image URL (required)
--duration, -d	5	Duration in seconds
--no-wait	—	Return immediately without waiting

bash

pvshow image2video \
  -p "让画面中的人物缓缓转头微笑" \
  -i "https://cdn.example.com/portrait.jpg" \
  -d 5

pvshow status / cancel / health

Task management and health check commands.

bash

pvshow status <TASK_ID>    # Query task status
pvshow cancel <TASK_ID>    # Cancel a task
pvshow health              # Health check

Python SDK

Use PVShowClient (sync) or AsyncPVShowClient (async) for programmatic access.

pythonText to Image

from pvshow_sdk import PVShowClient

client = PVShowClient(
    base_url="http://localhost:8002",
    model="sd2-agent",
)

task = client.text2image(
    "一幅莫奈风格的睡莲油画",
    ratio="1:1",
    resolution="2k",
)
result = client.wait(task.id)
print(result.result_url)

pythonText to Video

task = client.text2video(
    "无人机航拍雪山日出，云海翻涌",
    duration=5,
    ratio="16:9",
    resolution="720p",
)
result = client.wait(task.id, poll_interval=5.0, timeout=300.0)
print(result.result_url)

pythonImage to Video

task = client.image2video(
    "让花朵慢慢绽放",
    image_url="https://cdn.example.com/flower.jpg",
    duration=5,
)
result = client.wait(task.id)
print(result.result_url)

pythonTask Management

# Query status
task = client.get_task("your-task-id")
print(task.status)   # processing / completed / failed

# Cancel task
client.cancel("your-task-id")

# Health check
health = client.health()
print(health.status)  # "ok"

# Context manager — auto-close connection
with PVShowClient() as client:
    task = client.text2video("prompt")
    result = client.wait(task.id)

Low-Level submit()

The submit() method provides maximum flexibility — pass any custom parameters.

python

task = client.submit(
    task_type="text_to_video",
    prompt="自定义提示词",
    model="sd2-agent",
    params={
        "duration": 10,
        "ratio": "9:16",
        "video_resolution": "1080p",
        "model_version": "seedance2.0",
    },
)

REST API

The SDK wraps these HTTP endpoints. Non-Python languages can call them directly.

Base URL: http://<host>:8002/api/v1

Method	Path	Description
POST	/api/v1/tasks/	Create generation task (returns 202)
GET	/api/v1/tasks/{task_id}	Query task status
POST	/api/v1/tasks/{task_id}/cancel	Cancel a task
GET	/api/v1/health/	Service health check

POST /api/v1/tasks/ — Request Body

Field	Type	Required	Description
task_id	string	✓	Unique task ID (UUID recommended)
type	string	✓	text_to_image / text_to_video / image_to_video
model	string	✓	Model name (sd2-agent for Dreamina path)
prompt	string	✓	Generation prompt
image_url	string	—	First frame image URL (required for image_to_video)
params	object	—	Generation parameters (see below)

params

Parameter	Scope	Default	Description
ratio	All	1:1 / 16:9	Aspect ratio
resolution_type	Image	2k	Image resolution
duration	Video	5	Video duration (seconds)
video_resolution	Video	720p	Video resolution
model_version	All	seedance2.0	Model version

Response Example

json

{
  "id": "uuid-string",
  "status": "processing",
  "result_url": null,
  "error_message": null,
  "created_at": "2026-04-02T10:30:00+00:00",
  "updated_at": "2026-04-02T10:30:00+00:00"
}

Data Models

TaskResponse

Field	Type	Description
id	string	Task ID
status	string	Task status
result_url	string \| null	Result download URL (available after completion)
error_message	string \| null	Error message (on failure)
created_at	string	Created time (ISO 8601)
updated_at	string	Updated time (ISO 8601)

TaskStatus

Value	Description
queued	Queued
pending	Pending
processing	Generating
completed	Completed
failed	Failed
cancelled	Cancelled

TaskType

Value	Description
text_to_image	Text to Image
text_to_video	Text to Video
image_to_video	Image to Video

Configuration

Client Environment Variables

Env Variable	Option	Default
PVSHOW_BASE_URL	--base-url	http://localhost:8002
PVSHOW_MODEL	--model	sd2-agent

Adapter Service Environment Variables

Env Variable	Default	Description
JIMENG_ACCESS_KEY	—	Jimeng API Access Key
JIMENG_SECRET_KEY	—	Jimeng API Secret Key
JIMENG_API_BASE_URL	https://api.jimeng.jianying.com	Jimeng API base URL
DREAMINA_POLL_TIMEOUT	120	Dreamina CLI poll timeout (seconds)
CALLBACK_BASE_URL	http://localhost:8000	Task callback URL
POLL_INTERVAL_SECONDS	10	Internal poll interval (seconds)
POLL_MAX_ATTEMPTS	120	Max poll attempts

Architecture

┌─────────────┐    HTTP     ┌──────────────────────┐
│  pvshow CLI │───────────→│  SD2-Agent Adapter    │
│  / SDK      │            │  (FastAPI :8002)      │
└─────────────┘            │                       │
                           │  ┌─ SD2-Agent ──────┐ │     ┌──────────────┐
                           │  │  Dreamina CLI     │─┼────→│ Dreamina API │
                           │  └──────────────────┘ │     └──────────────┘
                           │                       │
                           │  ┌─ Jimeng ─────────┐ │     ┌──────────────┐
                           │  │  SeedanceClient   │─┼────→│ Jimeng API   │
                           │  │  (HMAC Signing)   │ │     └──────────────┘
                           │  └──────────────────┘ │
                           └───────────┬───────────┘
                                       │ callback
                                       ▼
                           ┌──────────────────────┐
                           │  PVShow Backend       │
                           │  (FastAPI :8000)      │
                           └──────────────────────┘

Model Routing

Model Name Contains	Engine	Supported Types
sd2-agent	Dreamina CLI	Text to Image / Text to Video / Image to Video
Other	Jimeng HTTP API (Seedance 2.0)	Text to Video / Image to Video

Task Lifecycle

submit ──→ processing ──→ completed
                     ├──→ failed
                     └──→ cancelled