API 文档

鉴权

Base URL：https://api.vivareel.com/api/developer/v1。所有开放 API 均使用 API Key 鉴权：Authorization: Bearer sk_live_xxx 或 sk_test_xxx。

响应与计费

开放 API 统一返回 code、message、data 三个字段，code 为 200 表示成功。按账号积分扣费，可通过 GET /models 查看定价。异步任务建议每 3-5 秒轮询 GET /tasks/task_id。

Wan 3.0 能力说明

Wan 3.0 是 All-in-One 参考生视频模型：同一模型即可完成文生视频、首帧/首尾帧图生视频，以及图片、视频、音频混合参考生视频。调用时传入 GET /models 返回的模型 name（如 wan-3.0），无需切换专用接口。

官方能力与素材组合规则见 Wan3.0 Video Generation API Reference。本平台通过 POST /api/developer/v1/videos/generations 封装，字段名与 DashScope 的 input.media[] 不同，请以本页参数为准。

字段适用范围

通用：model、motion_instruction（条件必填）、aspect_ratio、duration_seconds、capability、image_url（模式相关）、last_frame_url（模式相关；HappyHorse 不支持）、reference_urls（参考模式）。
多模型：reference_video_urls（Seedance / Wan3 语义 / Wan2.7 R2V / VivaReel2.0）；reference_audio_urls（Seedance / Wan3 语义 / Wan2.7 R2V / minimax-H3）。
Wan3 语义：resolution、audio、seed、prompt_extend、smart_duration。这些字段在走 Wan 3 语义的模型上生效。
仅 dashscope-wan3.0-video：watermark、enable_thinking、document_url、web_url。

生成模式

文生视频：只传 motion_instruction，capability 不传或为 null。
首帧生视频：传 image_url，capability 为 first_frame。
首尾帧生视频：同时传 image_url 与 last_frame_url，capability 为 flf2v。
全能参考：reference_urls、reference_video_urls、reference_audio_urls 可自由组合，capability 为 image_reference，motion_instruction 必填。
视频编辑 / 延展：传入 reference_video_urls，并在 motion_instruction 中写明编辑或延展意图，例如「改成黏土风格」或「将 Video 1 向前延展」。

互斥规则

image_url / last_frame_url 不得与 reference_urls、reference_video_urls、reference_audio_urls 同时传入。
首帧 / 首尾帧模式不支持参考音频驱动。需要音频驱动时，改用全能参考（参考图 + 参考音频）。
至少提供 motion_instruction，或一组符合当前模式的素材。

素材与成片约束

参考图最多 10 张；JPEG / JPG / PNG / BMP / WEBP，单边 240–8000 px，单张不超过 20MB。实际上限以 GET /models 的 max_reference_images 为准。
参考视频最多 5 段，单段 1–15 秒、合计不超过 15 秒；mp4 / mov，单段不超过 100MB。实际上限以 max_reference_videos 为准。
参考音频最多 5 段，单段 1–15 秒、合计不超过 15 秒；wav / mp3，单段不超过 15MB。实际上限以 max_reference_audios 为准。
无参考视频时，成片时长通常为 2–30 秒；有参考视频时，输入视频总时长 + 成片时长不超过 30 秒。具体范围以模型 duration_range / max_duration_seconds 为准。
成片为 MP4、30fps，默认可包含对白、BGM 和音效。

提示词中的素材引用

按类型分别计数：第 1 张参考图为 Image 1，第 1 段参考视频为 Video 1，第 1 段参考音频为 Audio 1。可写 Image 1、Video 1，或 @Image 1 / @Video 1 / @Audio 1。

生成图片

POST/api/developer/v1/images/generations

提交独立生图任务，支持文生图和参考图合成两种模式。返回 task_id，轮询 GET /api/developer/v1/tasks/task_id 获取结果。

请求参数

name	in	type	required	desc
model	body	string	✓	生图模型名称，通过 GET /models 接口获取可用模型列表
prompt	body	string	✓	文本描述，描述要生成的图片内容
aspect_ratio	body	string	—	画幅比例，可选值：16:9、9:16、4:3、3:4
image_resolution	body	string	—	输出分辨率，可选值：1K、2K、4K
reference_urls	body	string[]	—	参考图 URL 数组，0-5 个；非空时启用参考图合成模式

代码示例

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"
  ]
}'

请求体示例

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

返回示例

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

生成视频

POST/api/developer/v1/videos/generations

提交独立生视频任务。Wan 3.0 等全能模型支持文生视频、首帧、首尾帧，以及图片 / 视频 / 音频混合参考。返回 task_id，轮询 GET /api/developer/v1/tasks/task_id 获取结果。

请求参数

name	in	type	required	desc
model	body	string	✓	【通用】生视频模型名称，通过 GET /models 获取；常见如 wan-3.0 或 dashscope-wan3.0-video
motion_instruction	body	string \| null	—	【通用 / 条件必填】提示词 / 运动指令。文生视频、全能参考、视频编辑与延展必填；可引用 Image 1 / Video 1 / Audio 1
aspect_ratio	body	16:9 \| 9:16 \| 4:3 \| 3:4 \| null	—	【通用】画幅比例：16:9、9:16、4:3、3:4
duration_seconds	body	integer \| null	—	【通用】成片时长（秒）。以 GET /models 的 duration_range / max_duration_seconds 为准
capability	body	first_frame \| flf2v \| image_reference \| null	—	【通用】first_frame、flf2v 或 image_reference；不传或 null 时按字段推断（仅有 motion_instruction 即为文生视频）
image_url	body	string \| null	—	【通用 / 模式相关】首帧图片 URL，用于 first_frame / flf2v；不可与 reference_* 同时传入
last_frame_url	body	string \| null	—	【通用 / 模式相关】尾帧图片 URL，用于 flf2v；须与 image_url 同时使用且不可相同。HappyHorse 不支持
reference_urls	body	string[]	—	【通用 / 参考模式】参考图 URL 数组，用于 image_reference
reference_video_urls	body	string[]	—	【多模型】Seedance / Wan3 语义 / Wan2.7 R2V / VivaReel2.0。参考视频 URL 数组
reference_audio_urls	body	string[]	—	【多模型】Seedance / Wan3 语义 / Wan2.7 R2V / minimax-H3。参考音频 URL 数组
resolution	body	480P \| 720P \| 1080P \| null	—	【Wan3 语义】输出分辨率：480P、720P、1080P
audio	body	boolean \| null	—	【Wan3 语义】是否生成音频
seed	body	integer \| null	—	【Wan3 语义】随机种子，用于结果复现
watermark	body	boolean \| null	—	【仅 dashscope-wan3.0-video】是否加水印
prompt_extend	body	boolean \| null	—	【Wan3 语义】是否开启提示词扩写
smart_duration	body	boolean	—	【Wan3 语义】是否智能时长，默认 false
enable_thinking	body	boolean \| null	—	【仅 dashscope-wan3.0-video】是否开启思考过程
document_url	body	string \| null	—	【仅 dashscope-wan3.0-video】文档参考 URL
web_url	body	string \| null	—	【仅 dashscope-wan3.0-video】网页参考 URL

代码示例

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
}'

请求体示例

{
  "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
}

返回示例

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

视频换人

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

提交视频换人任务，支持 1-3 个源视频和 1-9 张参考图。返回 task_id，轮询 GET /api/developer/v1/tasks/task_id 获取 result_url。

请求参数

name	in	type	required	desc
video_urls	body	string[]	✓	源视频 URL 数组，1-3 个，必须为 http(s) 链接
reference_urls	body	string[]	✓	参考图 URL 数组，1-9 个，必须为 http(s) 链接
prompt	body	string	✓	换人提示词，描述替换要求
resolution	body	string	—	输出分辨率，默认 720P
aspect_ratio	body	string	—	画幅比例，默认 9:16
model	body	string	—	生视频模型，不传则使用默认模型
duration_seconds	body	number	—	源视频总时长（秒），用于积分预估；不传则由服务端自动探测
seed	body	integer	—	随机种子，用于结果复现
watermark	body	boolean	—	是否添加水印，默认 false

代码示例

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
}'

请求体示例

{
  "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
}

返回示例

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

查询任务状态

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

轮询异步任务状态，获取任务进度和结果。建议每 3-5 秒轮询一次，直至 status 为 completed 或 failed。

请求参数

name	in	type	required	desc
task_id	path	string	✓	任务 ID，由生图/生视频/换人接口返回

代码示例

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

返回示例

{
  "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"
    }
  }
}

上传文件

POST/api/developer/v1/files

上传文件到存储，返回可引用的 URL。常用于上传首帧图、参考图、参考视频或参考音频（Content-Type: multipart/form-data）。

请求参数

name	in	type	required	desc
file	formData	file	✓	上传的文件（图片、视频、音频等）

代码示例

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

返回示例

{
  "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"
  }
}

获取模型列表

GET/api/developer/v1/models

查询可用的生图和生视频模型，包含模型能力、支持参数和定价信息。调用 Wan 3.0 前先确认 capabilities、duration_range 与 max_reference_images / videos / audios。

请求参数

无

代码示例

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

返回示例

{
  "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
          }
        }
      }
    ]
  }
}