使用 API

该地址为平台统一接入地址，兼容 OpenAI 协议；以下示例中的地址均自动取自此处。

1. 登录控制台，进入「令牌」页面
2. 点击「添加令牌」，设置名称与额度，创建后复制 sk- 开头的密钥
3. 将密钥作为 api_key 填入客户端或代码中

操练场是内置的在线测试工具，无需编写代码即可直接与模型对话，适合快速验证令牌是否可用。

1. 在控制台左侧导航点击「操练场」（或直接访问 /console/playground）
2. 在左侧选择要测试的模型
3. 在底部输入框输入消息内容，点击发送，右侧对话区域显示模型回复

视频生成接口采用异步任务模型：先调用生成接口创建任务获得 task_id，再循环轮询状态接口直到任务完成（data.status 为 SUCCESS），从 data.result_url 取出视频下载地址。

1. 创建任务时立即预扣费（余额不足返回 403）
2. 任务完成后按实际消耗多退少补结算
3. 任务失败自动退还预扣额度

两套地址均可使用，请求参数与返回结构完全相同（统一返回 {code, message, data} 规范结构）。

POST /v1/videos 与 POST /v1/video/generations 请求体相同（JSON）：

不同模型支持的参数范围不同，请以控制台「视频模型」页面为准。例如 doubao-seedance-2.0 要求 duration 与 resolution 必填；视频编辑类模型不接受 duration 和 ratio。

omni_reference_task_type 用于引导 Seedance 2.5 的全模态参考生视频任务类型，取值如下：

前置校验（提交即校验，不符合立即报错）

仅当显式指定 edit 或 extend 时生效：不符合会立即返回参数错误、任务不会创建。auto / reference 不做该校验。

异步校验（任务启动后报错）

声明的任务类型与提示词意图不一致时，提交仍会成功、任务正常创建，但任务启动后会异步失败，错误码为 InvalidParameter.TaskTypeMismatch。此时请检查 omni_reference_task_type 与提示词描述是否吻合，或改用 auto 由模型自行判定。

计费：显式 duration 按该时长预扣；传 -1（edit / extend 等时长未知场景）时按参考视频时长预扣，任务完成后按实际产出时长多退少补。

HappyHorse 系列为阿里云百炼新一代视频模型，输出物理真实、运动流畅的视频，支持文生视频、图生视频（首帧）、参考生视频、视频编辑四种形态。调用方式与上方统一视频接口完全一致，仅模型名称与输入素材不同。

文本与素材同样可以通过 content 传入：type:text 作提示词，image_url / video_url 按模型形态自动归位（i2v 取第 1 张图、r2v 取全部图片、video-edit 取输入视频），无需拆成扁平字段。

HappyHorse 参数说明

HappyHorse 按产出视频时长（秒）× 分辨率档位单价计费：创建任务时按请求时长预扣；视频编辑因输出时长未知按 15 秒上限预扣，任务完成后按实际产出时长多退少补。

请求示例

# 文生视频（16:9、720p、5 秒）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-t2v",
    "prompt": "一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

# 图生视频（首帧驱动，宽高比跟随首帧）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-i2v",
    "prompt": "一只猫在草地上奔跑",
    "image_urls": ["https://example.com/first-frame.png"],
    "duration": 5,
    "resolution": "720p"
  }'

# 参考生视频（prompt 中以 [Image N] 指代参考图）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-r2v",
    "prompt": "[Image 1]中身着红色旗袍的女性，轻抬玉手展开[Image 2]中的折扇",
    "image_urls": ["https://example.com/girl.jpg", "https://example.com/fan.jpg"],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

# 视频编辑（指令 + 输入视频，可选参考图）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "让视频中的角色穿上图片中的条纹毛衣",
    "video_urls": ["https://example.com/input.mp4"],
    "image_urls": ["https://example.com/sweater.webp"],
    "resolution": "720p"
  }'

轮询与结果获取方式与其他视频模型完全相同：两条 API 均返回统一结构，成功时从 data.result_url（或 data.metadata.url）取视频地址；视频链接有效期 24 小时，请及时下载转存。

万相 3.0 是全能参考视频生成模型（All-in-One），统一支持文生视频、图生视频（首帧 / 首尾帧）、参考生视频、视频编辑与视频延长。模型名称：wan3.0-video（标准版）、wan3.0-video-prime（高速版，能力对齐标准版）。

prompt 与素材至少提供其一：文生视频只传提示词；其余形态通过 content 携带素材，平台会把每个素材部件的 role 原样映射为素材类型。

素材组合规则：first_frame / last_frame 与 reference_image / reference_video / reference_audio 互斥，不能在同一请求中混用；参考类素材之间可自由组合。使用扁平字段时， image_urls 单图按首帧、多图按参考图处理。

万相 3.0 参数说明

计费：按产出视频时长（秒）× 分辨率档位单价计费；未指定分辨率按上游默认 1080p 档位计价。duration=-1 时按上限预扣，任务完成后按实际产出时长多退少补。

请求示例

# 参考生视频（文本走 content，图片角色 reference_image）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "duration": 5,
    "resolution": "480p",
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      { "type": "text", "text": "图1中的机器人在赛博朋克街头行走" },
      { "type": "image_url", "image_url": { "url": "https://example.com/robot.jpg" }, "role": "reference_image" }
    ]
  }'

# 首尾帧生视频（role 为 first_frame / last_frame）
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive",
    "content": [
      { "type": "text", "text": "从首帧平滑过渡到尾帧" },
      { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "role": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/last.png" }, "role": "last_frame" }
    ]
  }'

HTTP 200。两个创建地址（/v1/videos 与 /v1/video/generations）返回相同的统一结构 {code, message, data}，任务初始为 NOT_START（或排队态）：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "action": "generate",
    "status": "NOT_START",
    "fail_reason": "",
    "submit_time": 1790742666,
    "start_time": 0,
    "finish_time": 0,
    "progress": "0%",
    "model": "doubao-seedance-2-0",
    "metadata": { "url": null, "resolution": "480p", "duration": 4, "ratio": "16:9" },
    "usage": { "total_tokens": null, "completion_tokens": null }
  }
}

其中 data.task_id 用于后续轮询。

GET /v1/videos/{task_id} 与 GET /v1/video/generations/{task_id} 返回完全相同的统一结构 {code, message, data}，字段随任务推进而更新：

生成成功响应示例：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://example.com/video.mp4",
    "submit_time": 1790747575,
    "start_time": 1790747717,
    "finish_time": 1790747882,
    "progress": "100%",
    "model": "doubao-seedance-2-0",
    "usage": { "total_tokens": 40594, "completion_tokens": 40594 },
    "metadata": { "url": "https://example.com/video.mp4", "resolution": "480p", "duration": 4, "ratio": "16:9" }
  }
}

出于简洁与账号安全，统一结构不包含 user_id / channel_id / quota / group / platform 等内部字段；渠道原始返回仅保留在服务端日志中。视频链接有效期 24 小时，请及时下载转存。

status 状态码

平台原生格式（/v1/video/generations）与 OpenAI 兼容格式（/v1/videos）现返回完全相同的统一结构，参见上方「状态查询响应」，不再单列。

错误响应体格式：{"code": "错误码", "message": "错误描述", "data": null}。

Python 示例

from openai import OpenAI
import time

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",
    base_url="…"
)

# 1. 创建视频任务
resp = client.post(
    "/videos",
    body={
        "model": "doubao-seedance-2.0",
        "prompt": "一只猫在草地上奔跑",
        "duration": 5,
        "resolution": "720p"
    },
    cast_to=object
)
task_id = resp["data"]["task_id"]
print(f"Task created: {task_id}")

# 2. 轮询状态直到完成
while True:
    time.sleep(10)
    status_resp = client.get(f"/videos/{task_id}", cast_to=object)
    data = status_resp["data"]
    status = data["status"]
    print(f"Status: {status}")
    if status == "SUCCESS":
        video_url = data["result_url"]
        print(f"Video URL: {video_url}")
        break
    elif status == "FAILURE":
        print(f"Failed: {data.get('fail_reason')}")
        break

cURL 示例

# 创建任务
curl …/videos \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "一只猫在草地上奔跑",
    "duration": 5,
    "resolution": "720p"
  }'

# 轮询状态（将 {task_id} 替换为实际值）
curl …/videos/{task_id} \
  -H "Authorization: Bearer sk-xxxxxxxx"

平台原生格式示例（Python requests）

import requests, time

BASE = "…"
HEADERS = {"Authorization": "Bearer sk-xxxxxxxx", "Content-Type": "application/json"}

# 1. 创建任务
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json={
    "model": "doubao-seedance-2.0",
    "prompt": "一只猫在草地上奔跑",
    "duration": 5,
    "resolution": "720p"
}).json()
task_id = resp["data"]["task_id"]
print(f"Task created: {task_id}")

# 2. 轮询状态直到 SUCCESS
while True:
    time.sleep(10)
    data = requests.get(f"{BASE}/video/generations/{task_id}",
                        headers=HEADERS).json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "SUCCESS":
        print(f"Video URL: {data['result_url']}")
        break
    elif data["status"] == "FAILURE":
        print(f"Failed: {data['fail_reason']}")
        break