视频生成 API

视频生成 API 使用异步任务。创建请求会返回 HTTP 202 和任务 ID；使用该 ID 轮询，直到任务进入 succeeded 或 failed，成功后再下载 MP4 视频。

下文以 https://api.icodeeasy.cc 为 Base URL。以下接口调用都必须携带 API Key；成功后返回的带签名结果文件 URL 是唯一例外：

Authorization: Bearer <你的 API Key>

接口一览

五分钟快速接入

第一步：创建任务

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.5",
    "prompt": "雨夜的未来城市街道，镜头缓慢向前推进，霓虹灯倒映在湿润路面上",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

创建成功返回 HTTP 202：

{
  "id": "vid_1785398400000000000",
  "task_id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "queued",
  "model": "doubao-seedance-2.5",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:00Z"
}

优先使用 task_id 作为任务 ID，用于查询、下载和删除；id 在兼容期内保留且值相同。HTTP 202 表示任务已接受，不表示视频已经完成。

第二步：轮询任务

把创建响应中的 task_id 填入 TASK_ID：

TASK_ID='vid_1785398400000000000'
curl "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}" \
  -H 'Authorization: Bearer <你的 API Key>'

建议约每 5 秒轮询一次。当前任务处于 queued 或 running 时，不要重复创建新任务。

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "running",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:20Z",
  "progress": 42
}

progress 是尽力提供的进度，可能缺失。应以 status 而不是进度数值判断任务状态。

第三步：下载视频

当 status 变为 succeeded，响应会包含 url 和最终 cost_rmb：

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:01:18Z",
  "progress": 100,
  "url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "cost_rmb": 0.528
}

通过规范的鉴权内容路由下载，并允许客户端跟随重定向：

TASK_ID='vid_1785398400000000000'
curl -L "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}/content" \
  -H 'Authorization: Bearer <你的 API Key>' \
  -o result.mp4

内容路由支持 HTTP Range 和常见的条件下载请求头。任务成功前请求内容会返回 409 video_not_ready。

任务生命周期与安全重试

重试规则：

• 收到 HTTP 202 后，应持续轮询返回的 task_id；重复调用创建接口可能产生另一个任务。
• 轮询和下载的 GET 请求可以安全重试。
• 如果创建接口返回 submission_unknown，不要重新提交。任务可能已经被接受；请向客服提供请求时间、模型和提示词摘要。
• 已确认任务进入终态 failed 后，如果确实要重新生成，可重新创建任务。

当前不支持 Webhook 和 callback_url，请轮询任务接口。

创建请求参数

所有文字提示词都放在 prompt。content 只用于参考图片和参考视频。

参考素材列表（content）

content 是参考素材列表，因为一个任务可能需要首帧和尾帧、多张无顺序参考图，或 Motion Control 的一张图片加一个视频。每项素材的 image_url 或 video_url 直接填写一个 HTTPS URL 字符串。

[
  { "type": "image_url", "image_url": "https://cdn.example.com/first.png", "role": "first_frame" },
  { "type": "image_url", "image_url": "https://cdn.example.com/last.png", "role": "last_frame" }
]

• 图片类型：image_url 或 input_image。
• 视频类型：video_url 或 input_video。
• 首尾帧角色：first_frame 和 last_frame；尾帧始终要求同时提供首帧。
• Motion Control 角色：一个 reference_image 和一个 reference_video。
• Grok 参考图无需角色，也接受 reference_image。
• 当前不支持参考音频素材。
• 媒体地址必须是公网可访问的 HTTPS URL，并在任务读取期间保持有效。
• 图片使用 image_url，视频使用 video_url。

首帧 + 尾帧完整调用

把两张图片放在可公开读取的 HTTPS 地址，然后直接将 URL 放进 content：

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "镜头从首帧平滑过渡到尾帧",
    "content": [
      {"type":"image_url","image_url":"https://cdn.example.com/first.png","role":"first_frame"},
      {"type":"image_url","image_url":"https://cdn.example.com/last.png","role":"last_frame"}
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

可以只传首帧；如果没有在同一个请求中提供首帧，就不能单独传尾帧。

分模型接入示例

Seedance：文本、首帧和尾帧

Seedance 2.5、Seedance 2.0 Standard、Fast、Mini 以及 Seedance 1.5 Pro 支持文生视频和首尾帧生成。参考图片必须明确标注帧角色；Seedance 2.5 排在该系列首位。

{
  "model": "doubao-seedance-2.5",
  "prompt": "镜头环绕玻璃雕塑，晨光逐渐变化",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-last.png", "role": "last_frame" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5 不传生成规格时，默认使用 480p、9:16、4 秒，并默认开启生成音频。使用首帧或首尾帧时，比例会规范化为 adaptive。

MiniMax H3：文本、首帧和尾帧

MiniMax-H3 通过同一套公开请求支持文生视频和首尾帧生成。它支持 768P 或 2K、4–15 秒，以及 21:9、16:9、4:3、1:1、3:4、9:16 比例；默认值为 768P、9:16、5 秒。请不要传 generate_audio：H3 的公开契约没有生成音频请求开关。

Kling：首尾帧引导

{
  "model": "kling-v3",
  "prompt": "列车穿过薄雾驶入站台",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-last.png", "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

Kling 各版本的重要差异：

• kling-v2-6：使用尾帧必须选择 1080p；生成音频也只支持 1080p，且不能与尾帧同时使用。
• kling-3.0-turbo：仅支持首帧，不支持生成音频。
• kling-v3 和 kling-v3-omni：支持首尾帧和生成音频。
• kling-v3-omni 还支持最多两张不带角色的参考图，但同一请求中不能混用无角色参考图和首尾帧角色图。
• kling-video-o1：支持首尾帧，不支持生成音频。

Grok：无顺序参考图

Grok 最多接受七张参考图 URL，不要设置 first_frame 或 last_frame。

{
  "model": "grok-imagine-1.5-video",
  "prompt": "云层掠过峡谷，镜头缓慢升高",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/grok-reference.png" }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 6
}

Grok 默认使用 480p、9:16 和 6 秒，不支持生成音频。

Kling Motion Control

提供一张公网 HTTPS 图片和一个公网 HTTPS MP4 视频：

{
  "model": "kling-v3-motion-control",
  "prompt": "保持角色身份并跟随参考动作",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/character.png", "role": "reference_image" },
    { "type": "video_url", "video_url": "https://cdn.example.com/motion.mp4", "role": "reference_video" }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}

• character_orientation: "image"：参考视频必须为 3–10 秒。
• character_orientation: "video"：参考视频必须为 3–30 秒。
• Motion Control 模型不能传 resolution、ratio、duration 或 generate_audio。

模型能力表

标准模型省略可选字段时，会使用上表及前文说明的默认值；model 本身始终必填。服务会在开始任务前校验参数组合。

响应与下载行为

任务响应使用统一结构：

建议始终使用 GET /v1/videos/tasks/{id}/content 下载，不要依赖 url 的具体形状。使用 curl -L，或在 HTTP 客户端中启用重定向。鉴权内容接口可能返回 200、206 Partial Content，或重定向到 Relay 管理的存储。

带签名的 Relay 文件 URL 无需 API Key 即可打开；获得完整 URL 就能访问对应视频。不要把它暴露在公开日志、公开页面或客户端分析数据中。

安全删除终态任务会返回 HTTP 204，同时可能删除 Relay 中保存的视频文件。删除任务前，请先下载并保存需要的结果。运行中或计费尚未完成的任务会返回 409 video_delete_unsafe。删除本地任务记录不会取消已经开始的视频生成。

错误处理

HTTP 错误统一为：

{
  "error": {
    "type": "invalid_request",
    "message": "model is not supported"
  }
}

失败任务响应示例：

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

计费

视频生成使用账户余额，不使用月卡额度。

任务费用 = 所选模型及规格在价格页展示的人民币单秒价格 × 计费秒数

当前各模型单秒价格请查看价格页面。分辨率、生成音频或 Motion Control 模式可能对应不同的单秒价格行。标准模型的计费秒数就是请求中的 duration；Motion Control 使用系统识别的参考视频时长，不足整秒时向上取整。

创建任务时，余额必须能够覆盖该任务。余额不足会在开始生成前返回 402。成功任务中的 cost_rmb 是最终实际费用；明确失败的任务不收费。