使用 API

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

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

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

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

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

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

两套地址均可使用：OpenAI 兼容格式与平台原生格式，请求参数完全相同，仅查询响应结构不同。

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

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

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

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

轮询与结果获取方式与其他视频模型完全相同（OpenAI 兼容格式取 metadata.url，平台原生格式取 data.result_url）；上游视频链接有效期 24 小时，请及时下载转存。

HTTP 200。两个创建地址（/v1/videos 与 /v1/video/generations）返回相同的 OpenAI Video 对象：

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1783495738,
  "metadata": null
}

其中 task_id 用于后续轮询。

GET /v1/videos/{task_id} 返回与创建时相同的 OpenAI Video 对象，关键字段随任务推进变化：

生成成功响应示例：

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1783495738,
  "completed_at": 1783496011,
  "metadata": { "url": "https://example.com/video.mp4" }
}

status 状态码（OpenAI 兼容格式）

GET /v1/video/generations/{task_id} 返回 {code, message, data} 结构，视频地址在 data.result_url：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://example.com/video.mp4",
    "fail_reason": "",
    "submit_time": 1783495738,
    "start_time": 1783495740,
    "finish_time": 1783496011
  }
}

status 状态码（平台原生格式）

错误响应体格式：{"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["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)
    status = status_resp["status"]
    print(f"Status: {status}")
    if status == "completed":
        video_url = status_resp["metadata"]["url"]
        print(f"Video URL: {video_url}")
        break
    elif status == "failed":
        print(f"Failed: {status_resp.get('error')}")
        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["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