API Docs

Authentication

Base URL: https://api.vivareel.com/api/developer/v1. All open API endpoints use an API Key: Authorization: Bearer sk_live_xxx or sk_test_xxx.

Response & billing

Open API responses include code, message, and data; code 200 means success. Calls are charged against account points—check pricing via GET /models. Poll GET /tasks/task_id every 3–5s for async tasks.

Wan 3.0 capabilities

Wan 3.0 is an all-in-one reference video model. The same model covers text-to-video, first-frame and first-last-frame image-to-video, and mixed image / video / audio reference generation. Pass the model name from GET /models (for example wan-3.0). You do not need a separate endpoint.

Official mode and material-combination rules: Wan3.0 Video Generation API Reference. This platform wraps them as POST /api/developer/v1/videos/generations. Field names differ from DashScope input.media[]; use the parameters on this page.

Field scope

Common: model, motion_instruction (conditionally required), aspect_ratio, duration_seconds, capability, image_url (mode-specific), last_frame_url (mode-specific; not supported by HappyHorse), and reference_urls (reference mode).
Multi-model: reference_video_urls (Seedance / Wan3 semantics / Wan2.7 R2V / VivaReel2.0); reference_audio_urls (Seedance / Wan3 semantics / Wan2.7 R2V / minimax-H3).
Wan3 semantics: resolution, audio, seed, prompt_extend, and smart_duration. These apply to models that use Wan 3 field semantics.
dashscope-wan3.0-video only: watermark, enable_thinking, document_url, and web_url.

Generation modes

Text-to-video: send motion_instruction only and omit capability or set it to null.
First-frame video: send image_url, with capability first_frame.
First-last-frame video: send both image_url and last_frame_url, with capability flf2v.
All-modal reference: combine reference_urls, reference_video_urls, and reference_audio_urls. Use capability image_reference. motion_instruction is required.
Video editing / extension: send reference_video_urls and describe the edit or extension in motion_instruction, for example “turn this into clay style” or “extend Video 1 forward”.

Mutual-exclusion rules

Do not send image_url / last_frame_url together with reference_urls, reference_video_urls, or reference_audio_urls.
First-frame and first-last-frame modes do not accept driving audio. For audio-driven generation, use all-modal reference (reference images + reference audio).
Provide motion_instruction, or a valid material set for the current mode.

Material and output limits

Up to 10 reference images; JPEG / JPG / PNG / BMP / WEBP, 240–8000 px per side, 20MB each. The live limit is max_reference_images from GET /models.
Up to 5 reference clips, 1–15 seconds each, 15 seconds total; mp4 / mov, 100MB each. The live limit is max_reference_videos.
Up to 5 reference clips, 1–15 seconds each, 15 seconds total; wav / mp3, 15MB each. The live limit is max_reference_audios.
Without reference video, output duration is typically 2–30 seconds. With reference video, input duration + output duration must not exceed 30 seconds. Always check duration_range / max_duration_seconds.
Output is MP4 at 30 fps and can include dialogue, BGM, and sound effects by default.

Referencing materials in the prompt

Count each type separately: the first reference image is Image 1, the first reference video is Video 1, and the first reference audio is Audio 1. You can write Image 1, Video 1, or @Image 1 / @Video 1 / @Audio 1.

Generate image

POST/api/developer/v1/images/generations

Submit a standalone image generation task (text-to-image or reference-image composition). Returns task_id; poll GET /api/developer/v1/tasks/task_id for results.

Parameters

name	in	type	required	desc
model	body	string	✓	Image model name; list available models via GET /models
prompt	body	string	✓	Text description of the image to generate
aspect_ratio	body	string	—	Aspect ratio: 16:9, 9:16, 4:3, or 3:4
image_resolution	body	string	—	Output resolution: 1K, 2K, or 4K
reference_urls	body	string[]	—	Reference image URLs (0–5); non-empty enables reference composition mode

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/images/generations" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "dashscope-wan2.1-t2i-turbo",
  "prompt": "一只可爱的猫咪在草地上奔跑",
  "aspect_ratio": "16:9",
  "image_resolution": "2K",
  "reference_urls": [
    "https://example.com/ref1.jpg"
  ]
}'

Request Body Example

{
  "model": "dashscope-wan2.1-t2i-turbo",
  "prompt": "一只可爱的猫咪在草地上奔跑",
  "aspect_ratio": "16:9",
  "image_resolution": "2K",
  "reference_urls": [
    "https://example.com/ref1.jpg"
  ]
}

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Generate video

POST/api/developer/v1/videos/generations

Submit a standalone video generation task. All-in-one models such as Wan 3.0 support text-to-video, first frame, first/last frame, and mixed image / video / audio reference. Returns task_id; poll GET /api/developer/v1/tasks/task_id for results.

Parameters

name	in	type	required	desc
model	body	string	✓	[Common] Video model name from GET /models; typically wan-3.0 or dashscope-wan3.0-video
motion_instruction	body	string \| null	—	[Common / conditionally required] Prompt / motion instruction. Required for text-to-video, all-modal reference, editing, and extension. You can mention Image 1 / Video 1 / Audio 1
aspect_ratio	body	16:9 \| 9:16 \| 4:3 \| 3:4 \| null	—	[Common] Aspect ratio: 16:9, 9:16, 4:3, or 3:4
duration_seconds	body	integer \| null	—	[Common] Output duration in seconds. See duration_range / max_duration_seconds from GET /models
capability	body	first_frame \| flf2v \| image_reference \| null	—	[Common] first_frame, flf2v, or image_reference; omit or null to infer from fields (motion_instruction only = text-to-video)
image_url	body	string \| null	—	[Common / mode-specific] First-frame image URL for first_frame / flf2v. Do not send with reference_* fields
last_frame_url	body	string \| null	—	[Common / mode-specific] Last-frame image URL for flf2v. Must be used with image_url and must not be the same image. Not supported by HappyHorse
reference_urls	body	string[]	—	[Common / reference mode] Reference image URLs for image_reference
reference_video_urls	body	string[]	—	[Multi-model] Seedance / Wan3 semantics / Wan2.7 R2V / VivaReel2.0. Reference video URLs
reference_audio_urls	body	string[]	—	[Multi-model] Seedance / Wan3 semantics / Wan2.7 R2V / minimax-H3. Reference audio URLs
resolution	body	480P \| 720P \| 1080P \| null	—	[Wan3 semantics] Output resolution: 480P, 720P, or 1080P
audio	body	boolean \| null	—	[Wan3 semantics] Whether to generate audio
seed	body	integer \| null	—	[Wan3 semantics] Random seed for reproducible results
watermark	body	boolean \| null	—	[dashscope-wan3.0-video only] Whether to add a watermark
prompt_extend	body	boolean \| null	—	[Wan3 semantics] Whether to expand the prompt
smart_duration	body	boolean	—	[Wan3 semantics] Smart duration; default false
enable_thinking	body	boolean \| null	—	[dashscope-wan3.0-video only] Whether to enable thinking
document_url	body	string \| null	—	[dashscope-wan3.0-video only] Document reference URL
web_url	body	string \| null	—	[dashscope-wan3.0-video only] Web page reference URL

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/videos/generations" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan-3.0",
  "motion_instruction": "Video 1 sits on the chair in Image 2 and sings. Image 1 walks over, places Image 3 on the table, and says: the sunshine is so nice today.",
  "aspect_ratio": "9:16",
  "duration_seconds": 8,
  "capability": "image_reference",
  "reference_urls": [
    "https://example.com/character.jpg",
    "https://example.com/chair.jpg",
    "https://example.com/prop.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/performance.mp4"
  ],
  "resolution": "720P",
  "audio": true,
  "prompt_extend": true,
  "smart_duration": false
}'

Request Body Example

{
  "model": "wan-3.0",
  "motion_instruction": "Video 1 sits on the chair in Image 2 and sings. Image 1 walks over, places Image 3 on the table, and says: the sunshine is so nice today.",
  "aspect_ratio": "9:16",
  "duration_seconds": 8,
  "capability": "image_reference",
  "reference_urls": [
    "https://example.com/character.jpg",
    "https://example.com/chair.jpg",
    "https://example.com/prop.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/performance.mp4"
  ],
  "resolution": "720P",
  "audio": true,
  "prompt_extend": true,
  "smart_duration": false
}

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Replace character in video

POST/api/developer/v1/videos/replace-character

Submit a character-replacement task with 1–3 source videos and 1–9 reference images. Returns task_id; poll GET /api/developer/v1/tasks/task_id for result_url.

Parameters

name	in	type	required	desc
video_urls	body	string[]	✓	Source video URLs (1–3), must be http(s) links
reference_urls	body	string[]	✓	Reference image URLs (1–9), must be http(s) links
prompt	body	string	✓	Replacement prompt describing the desired swap
resolution	body	string	—	Output resolution; default 720P
aspect_ratio	body	string	—	Aspect ratio; default 9:16
model	body	string	—	Video model; uses default if omitted
duration_seconds	body	number	—	Total source video duration (seconds) for billing estimate; auto-detected if omitted
seed	body	integer	—	Random seed for reproducible results
watermark	body	boolean	—	Whether to add watermark; default false

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/videos/replace-character" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "video_urls": [
    "https://example.com/video1.mp4"
  ],
  "reference_urls": [
    "https://example.com/face1.jpg",
    "https://example.com/face2.jpg"
  ],
  "prompt": "将视频中的人物替换为参考图中的人物，保持表情和动作自然",
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "model": "dashscope-wan2.1-i2v-plus",
  "duration_seconds": 10.5,
  "seed": 12345,
  "watermark": false
}'

Request Body Example

{
  "video_urls": [
    "https://example.com/video1.mp4"
  ],
  "reference_urls": [
    "https://example.com/face1.jpg",
    "https://example.com/face2.jpg"
  ],
  "prompt": "将视频中的人物替换为参考图中的人物，保持表情和动作自然",
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "model": "dashscope-wan2.1-i2v-plus",
  "duration_seconds": 10.5,
  "seed": 12345,
  "watermark": false
}

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Get task status

GET/api/developer/v1/tasks/{task_id}

Poll async task status and results. Poll every 3–5 seconds until status is completed or failed.

Parameters

name	in	type	required	desc
task_id	path	string	✓	Task ID returned by image/video/replace endpoints

Code Sample

curl -X GET "https://vivareel.ai/api/developer/v1/tasks/{task_id}" \
  -H "Authorization: Bearer sk_live_xxx"

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_type": "standalone_image_generate",
    "status": "completed",
    "progress": 1,
    "points_cost": 10,
    "result_url": "https://storage.vivareel.com/output/xxx.png",
    "error_message": null,
    "extra": {
      "model": "dashscope-wan2.1-t2i-turbo",
      "aspect_ratio": "16:9"
    }
  }
}

Upload file

POST/api/developer/v1/files

Upload a file to storage and receive a referenceable URL. Use for first-frame images, reference images, reference videos, or reference audio (Content-Type: multipart/form-data).

Parameters

name	in	type	required	desc
file	formData	file	✓	File to upload (image, video, audio, etc.)

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/files" \
  -H "Authorization: Bearer sk_live_xxx"

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "url": "https://storage.vivareel.com/uploads/xxx.jpg",
    "storage_key": "uploads/2024/01/xxx.jpg",
    "original_filename": "my_image.jpg",
    "size_bytes": 204800,
    "content_type": "image/jpeg"
  }
}

List models

GET/api/developer/v1/models

List available image and video models with capabilities, supported parameters, and pricing. Before calling Wan 3.0, confirm capabilities, duration_range, and max_reference_images / videos / audios.

Parameters

None

Code Sample

curl -X GET "https://vivareel.ai/api/developer/v1/models" \
  -H "Authorization: Bearer sk_live_xxx"

Response Example

{
  "code": 200,
  "message": "ok",
  "data": {
    "image_models": [
      {
        "name": "dashscope-wan2.1-t2i-turbo",
        "display_name": "Wan 2.1 Turbo",
        "icon_url": "https://api.vivareel.com/icons/wan.png",
        "capabilities": [
          "text_to_image"
        ],
        "capability_labels": {
          "text_to_image": "文生图"
        },
        "max_reference_images": 0,
        "pricing_by_capability": {
          "text_to_image": {
            "capability": "text_to_image",
            "feature_key": "image_generation",
            "billing_unit": "flat",
            "label": "文生图",
            "points": 10
          }
        }
      }
    ],
    "video_models": [
      {
        "name": "wan-3.0",
        "display_name": "Wan 3.0",
        "icon_url": "https://api.vivareel.com/icons/wan_video.png",
        "capabilities": [
          "text_to_video",
          "first_frame",
          "flf2v",
          "image_reference"
        ],
        "capability_labels": {
          "text_to_video": "文生视频",
          "first_frame": "首帧生视频",
          "flf2v": "首尾帧生视频",
          "image_reference": "全能参考"
        },
        "duration_range": {
          "min": 2,
          "max": 30
        },
        "max_duration_seconds": {
          "text_to_video": 30,
          "first_frame": 30,
          "flf2v": 30,
          "image_reference": 30
        },
        "max_reference_images": 10,
        "max_reference_videos": 5,
        "max_reference_audios": 5,
        "pricing_by_capability": {
          "image_reference": {
            "capability": "image_reference",
            "feature_key": "video_generation_image_reference",
            "billing_unit": "per_second",
            "label": "全能参考",
            "points_per_second": 5
          }
        }
      }
    ]
  }
}

Virtual portrait library

Add a public https portrait to the virtual portrait library for the current channel, then pass that same https URL when generating video. Do not send asset://.

Before you call

Authenticate with an API Key. Do not send X-Team-Id or channel. The channel comes only from the backend portrait_channel setting: byteplus is the official library, baidu is the Baidu library.
The image must be a public https URL. When generating video, pass that same https URL. Do not pass asset://.
Call order: upload the file to get a URL, sync it into the library, check status when needed, generate video with the same URL, then remove it when you no longer need it.
message follows Accept-Language. The examples below are in Chinese.

Errors

code	When
400	image_url is not a public https URL, or the image is not in the current channel's library.
403	The user behind the API Key is not VIP or SVIP.
404	The image was not found when removing it.
502	The official or Baidu create or remove call failed. message includes the upstream text.
503	Credentials for the current channel are not configured.
504	Sync timed out.

Channel switch

After the backend switches the channel from Baidu to official, or back from official to Baidu, call sync again for the same image.

Sync a portrait

POST/api/developer/v1/virtual-assets/sync

Add an image to the current channel's virtual portrait library. The call waits until sync succeeds or fails. An image that is already Active on the current channel is not uploaded again. data.outcome is created for a new upload, already_active when it is already in the library, or reused when the same image is already linked and was not uploaded again. On success, in_virtual_asset_library is true.

Parameters

name	in	type	required	desc
image_url	body	string	✓	Public https image URL
name	body	string	—	Display name. Optional.

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/sync" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://cdn.example/a.png",
  "name": "角色甲"
}'

Request Body Example

{
  "image_url": "https://cdn.example/a.png",
  "name": "角色甲"
}

Response Example

{
  "code": 200,
  "message": "已加入 Seedance 虚拟资产库",
  "data": {
    "asset_id": 321,
    "image_url": "https://cdn.example/a.png",
    "in_virtual_asset_library": true,
    "outcome": "created"
  },
  "pagination": null
}

Check portrait status

POST/api/developer/v1/virtual-assets/status

Check whether image URLs are Active in the current channel's virtual portrait library. Active on the official library does not make the result true under the Baidu channel. asset_id is null when a URL does not match.

Parameters

name	in	type	required	desc
urls	body	string[]	✓	Image URLs, from 1 to 200

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/status" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "urls": [
    "https://cdn.example/a.png"
  ]
}'

Request Body Example

{
  "urls": [
    "https://cdn.example/a.png"
  ]
}

Response Example

{
  "code": 200,
  "message": "获取资产 URL 状态成功",
  "data": [
    {
      "url": "https://cdn.example/a.png",
      "in_virtual_asset_library": true,
      "asset_id": 321
    }
  ],
  "pagination": null
}

Remove a portrait

POST/api/developer/v1/virtual-assets/remove

Remove the record for the current channel only. The official channel clears official asset fields. The Baidu channel deletes only the Baidu binding and leaves official fields unchanged. The local image record stays, so you can sync it again after switching back. in_virtual_asset_library is false after removal.

Parameters

name	in	type	required	desc
image_url	body	string	✓	Public https image URL to remove

Code Sample

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/remove" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://cdn.example/a.png"
}'

Request Body Example

{
  "image_url": "https://cdn.example/a.png"
}

Response Example

{
  "code": 200,
  "message": "已移出 Seedance 虚拟资产库",
  "data": {
    "asset_id": 321,
    "image_url": "https://cdn.example/a.png",
    "in_virtual_asset_library": false
  },
  "pagination": null
}