视频生成 API 文档

通过 API Key 调用 Videos 系列模型生成视频。支持纯文生、首尾帧、多图参考、视频参考和音频参考。异步任务模式：先创建任务拿到任务 ID，再轮询查询结果。

① 鉴权与计费 ② 模型介绍与特性 ③ 创建视频任务 ④ 请求参数详解 ⑤ 使用场景 ⑥ 查询视频任务 ⑦ 最佳实践与提示词 ⑧ 错误响应

① 鉴权与计费

鉴权

在 密钥管理 创建 API Key，所有请求需在请求头携带 Bearer token：

Authorization: Bearer sk-你的密钥

Base URL

https://aicodehub.net

计费

每成功创建一个视频生成任务，计费 9 元 / 次（不区分模型与时长），从密钥所属账户余额扣除。
采用「预授权冻结 + 结算」：创建时冻结 9 元，生成成功后结算扣费；若任务生成失败，将自动释放冻结额度（不扣费）。查询响应中的 amount 字段固定为 9.00。

② 模型介绍与特性

支持三种模型，通过 model 字段指定：

  • seedance2：Seedance 2.0 标准模型，支持更多画幅与音频参考
  • seedance2_stable：Seedance 2.0 满血模型 （暂无资源，等待后续通知）
  • seedance2_fast：Seedance 2.0 快速模型 （暂无资源，等待后续通知）
模型时长范围素材能力支持比例
seedance24-15 秒最多 9 张图、3 个视频、3 段音频21:9、16:9、4:3、1:1、3:4、9:16
seedance2_stable4-15 秒最多 4 张图、3 个视频、1 段音频16:9、9:16、1:1
seedance2_fast4-15 秒最多 4 张图、3 个视频、1 段音频16:9、9:16、1:1

③ 创建视频任务

POST /openapi/v1/videos

创建视频生成任务。支持纯文生、首尾帧、多图/视频/音频参考。视频生成为异步处理，请保存返回的 id 用于后续查询。

幂等（可选）

携带请求头 Idempotency-Key，相同 Key 24 小时内返回同一任务，避免重复扣费。

请求示例 · 纯文生视频

curl --request POST \
  --url https://aicodehub.net/openapi/v1/videos \
  --header 'Authorization: Bearer sk-你的密钥' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance2",
    "prompt": "一只可爱的小猫在草地上玩耍，电影感",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

请求示例 · 首尾帧模式

curl --request POST \
  --url https://aicodehub.net/openapi/v1/videos \
  --header 'Authorization: Bearer sk-你的密钥' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance2",
    "prompt": "从清晨过渡到黄昏的海边延时镜头",
    "duration": 8,
    "first_image": "https://example.com/sea-morning.jpg",
    "last_image": "https://example.com/sea-evening.jpg",
    "ratio": "16:9"
  }'

请求示例 · 图音频参考

curl --request POST \
  --url https://aicodehub.net/openapi/v1/videos \
  --header 'Authorization: Bearer sk-你的密钥' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance2",
    "prompt": "可爱的兔子在玩耍，背景音乐是@音频1",
    "duration": 5,
    "referenceImages": ["https://example.com/rabbit.png"],
    "referenceAudios": ["https://example.com/bgm.mp3"],
    "ratio": "9:16"
  }'

请求示例 · 图/视频/音频混合参考

curl --request POST \
  --url https://aicodehub.net/openapi/v1/videos \
  --header 'Authorization: Bearer sk-你的密钥' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance2",
    "prompt": "角色在咖啡馆中自然对话，画面柔和，带轻微镜头推进",
    "duration": 10,
    "referenceImages": [
      "https://example.com/character-a.jpg",
      "https://example.com/character-b.jpg"
    ],
    "referenceVideos": ["https://example.com/cafe-scene.mp4"],
    "referenceAudios": ["https://example.com/dialogue-style.mp3"],
    "ratio": "16:9"
  }'

请求示例 · Python

import requests

resp = requests.post(
    "https://aicodehub.net/openapi/v1/videos",
    headers={
        "Authorization": "Bearer sk-你的密钥",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance2",
        "prompt": "A cute kitten playing in the grass, cinematic style",
        "duration": 5,
        "ratio": "16:9",
        "resolution": "720p",
    },
)
task_id = resp.json()["id"]

请求示例 · Java

HttpClient client = HttpClient.newHttpClient();

String body = """
{
  "model": "seedance2",
  "prompt": "A cute kitten playing in the grass, cinematic style",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p"
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://aicodehub.net/openapi/v1/videos"))
    .header("Authorization", "Bearer sk-你的密钥")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

响应参数

字段类型说明
idstring任务唯一标识符（vtask_ 开头），用于后续查询
objectstring对象类型，固定为 video
createdinteger任务创建时间戳（秒）
modelstring使用的模型名称
statusstringqueued / processing / completed / failed
errorstring错误信息，失败时返回

响应示例 · 创建成功

{
  "id": "vtask_9f3a1c8b2e...",
  "object": "video",
  "created": 1774836724,
  "model": "seedance2",
  "status": "queued",
  "error": null
}

响应示例 · 创建失败

{
  "id": null,
  "object": "error",
  "status": "failed",
  "error": "referenceAudios 最多支持 1 段，当前: 2"
}

④ 请求参数详解

基础参数

字段类型说明
modelstring可选，默认 seedance2。可选 seedance2 / seedance2_stable / seedance2_fast
prompt 必填string视频生成提示词。seedance2_stable / seedance2_fast 最大 5000 字符；seedance2 不限制为 5000
duration 必填integer视频时长（秒），范围 4-15，默认 5
ratiostring输出比例，默认 16:9。seedance2 支持 21:9/16:9/4:3/1:1/3:4/9:16；seedance2_stable / seedance2_fast 仅 16:9/9:16/1:1
resolutionstring输出分辨率，默认 720p（当前仅支持 720p）
autoFaceboolean是否自动人脸处理，默认 false。仅 seedance2 生效，其他模型传递不生效

首尾帧模式

字段类型说明
first_imagestring首帧图片 URL，必须搭配 last_image 使用
last_imagestring尾帧图片 URL，必须搭配 first_image 使用

引用素材模式

字段类型说明
referenceImagesarray参考图片 URL 列表。seedance2 最多 9 张，其他 4 张；每张 ≤ 20MB。可与视频/音频参考组合
referenceVideosarray参考视频 URL 列表。最多 3 个；总时长 ≤ 15 秒，总大小 ≤ 200MB；单个分辨率需在 720px-2160px 之间
referenceAudiosarray参考音频 URL 列表。seedance2 最多 3 段，其他 1 段；总时长 ≤ 15 秒
互斥规则：
· 首尾帧模式：first_image 和 last_image 必须成对使用。
· 引用素材模式：referenceImages、referenceVideos、referenceAudios 可单独或组合使用。
· 模式互斥：首尾帧模式不能与引用素材模式或音频参考同时使用；首尾帧模式不支持 referenceAudios。

⑤ 使用场景

场景说明
纯文生视频仅传 prompt、model、duration 等基础参数
首尾帧视频通过 first_image 和 last_image 精确控制开头与结尾画面
多模态混合参考通过 referenceImages、referenceVideos 与 referenceAudios 组合提供更强的素材约束

⑥ 查询视频任务

GET /openapi/v1/videos/{id}

使用创建任务返回的 id 查询任务状态与结果。

状态流程

状态说明
queued任务已创建并进入队列，等待处理
processing任务处理中，模型正在生成视频
completed任务完成，可通过 video_url 获取结果
failed任务失败，通过 error 查看原因

轮询建议

· 建议轮询间隔 30-60 秒；一般数分钟内完成，复杂素材参考场景可能更久。
· 不要过于频繁轮询，避免触发限流。
· 当状态为 completed 或 failed 时停止轮询。
· 生成结果为临时下载地址，请及时保存。

请求示例 · cURL

curl --request GET \
  --url https://aicodehub.net/openapi/v1/videos/vtask_9f3a1c8b2e... \
  --header 'Authorization: Bearer sk-你的密钥'

请求示例 · Python

import requests

resp = requests.get(
    "https://aicodehub.net/openapi/v1/videos/vtask_9f3a1c8b2e...",
    headers={"Authorization": "Bearer sk-你的密钥"},
)
print(resp.json())

响应参数

字段类型说明
idstring任务唯一标识符
objectstring对象类型，固定为 video
createdinteger任务创建时间戳（秒）
modelstring使用的模型名称
statusstringqueued / processing / completed / failed
video_urlstring生成的视频 URL，completed 时返回
actualDurationnumber视频实际输出时长（秒），completed 时返回
amountnumber本次任务计费金额（元），固定 9.00
errorstring错误信息，failed 时返回

响应示例 · 处理中

{
  "id": "vtask_9f3a1c8b2e...",
  "object": "video",
  "created": 1761635478,
  "model": "seedance2",
  "status": "processing",
  "video_url": null,
  "actualDuration": null,
  "amount": 9.00,
  "error": null
}

响应示例 · 已完成

{
  "id": "vtask_9f3a1c8b2e...",
  "object": "video",
  "created": 1761635478,
  "model": "seedance2",
  "status": "completed",
  "video_url": "https://example.com/video.mp4",
  "actualDuration": 8.0,
  "amount": 9.00,
  "error": null
}

响应示例 · 失败

{
  "id": "vtask_9f3a1c8b2e...",
  "object": "video",
  "created": 1761635478,
  "model": "seedance2",
  "status": "failed",
  "video_url": null,
  "amount": 9.00,
  "error": "Generation failed: reference video resolution is not supported"
}
任务失败时不扣费，冻结的 9 元会自动释放归还账户余额。

⑦ 最佳实践与提示词建议

最佳实践

  • 视频生成为异步处理，请保存创建返回的 id 用于后续查询。
  • 提示词尽量包含具体场景、动作、镜头和风格描述。
  • 使用首尾帧模式时，确保两张图片在风格和构图上连续。
  • 使用视频或音频参考时，优先提供清晰、时长较短、主体明确的素材。
  • 需要更快速度时，使用 seedance2_fast。

提示词建议

  • 描述主体、动作和镜头语言。
  • 补充风格词，如"电影感""写实""梦幻"。
  • 如有运动轨迹诉求，可直接写明镜头推进、转场或视角变化。
  • 多素材组合时，在提示词中用 @Image1、@Video1、@音频1 等显式指代素材。
  • 建议避免违规、侵权、涉政、涉黄等高风险内容，否则任务可能直接失败。

⑧ 错误响应

出错时返回对应 HTTP 状态码与统一结构：

{ "id": null, "object": "error", "status": "failed", "error": "insufficient balance" }
HTTPerror说明
401invalid api key密钥无效或已禁用
400参数错误信息参数不合法（如比例不支持、缺提示词、音频数量超限）
402insufficient balance账户余额不足 9 元
403forbidden无权访问该任务
404task not found任务不存在
500上游/系统错误信息创建失败（已自动释放冻结）