视频生成 API

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

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

Authorization: Bearer <你的 API Key>

接口一览

创建和查询响应中的 status_url、content_url 是相对于 Base URL 的规范查询与下载地址，建议直接使用。兼容读取地址 GET /v1/videos/generations/{id} 和 GET /v1/videos/generations/{id}/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.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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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 请求可以安全重试。
• 轮询返回 HTTP 404 不代表生成失败，也不要因此重新提交。保留原任务 ID，核对返回的 status_url 或改用 GET /v1/videos/tasks/{id}，并使用任务所属账户的有效 API Key。任务可能已成功且已结算，可查看用量明细；仍无法查询时向客服提供任务 ID 和提交时间。
• 如果创建接口返回 submission_unknown，不要重新提交。任务可能已经被接受；请向客服提供请求时间、模型和提示词摘要。
• 已确认任务进入终态 failed 后，如果确实要重新生成，可重新创建任务。

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

创建请求参数

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

参考素材列表（content）

content 是参考素材列表，因为一个任务可能需要首帧和尾帧、多张无顺序参考图、Seedance 2.5 的参考视频，或 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；仅首尾帧生成时，尾帧要求同时提供首帧。
• Seedance 2.5 参考视频角色：reference_video；同时提供的普通参考图使用 reference_image。
• 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": "adaptive",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5 文生视频不传生成规格时，默认使用 480p、9:16、4 秒，并默认开启生成音频。首帧或首尾帧模式（不含参考视频）会跟随首帧图片的比例：ratio 必须设为 adaptive 或省略，aspect_ratio 兼容别名遵循同样规则。显式传入 16:9 等固定比例会返回 400 invalid_request，不会被静默改写。竖版首帧会生成竖版视频；若需要 16:9 输出，请先把首帧裁剪或扩图到 16:9，再使用 adaptive。文生视频和参考视频模式仍可指定 16:9 等固定比例。

Seedance 2.5：参考视频

向 POST https://api.icodeeasy.cc/v1/videos/generations 提交以下 JSON，并携带 Authorization: Bearer <你的 API Key> 和 Content-Type: application/json：

{
  "model": "doubao-seedance-2.5",
  "prompt": "参考 @Video1 的动作，生成一段流畅的视频",
  "content": [
    { "type": "video_url", "video_url": "https://cdn.example.com/reference.mp4", "role": "reference_video" }
  ],
  "resolution": "480p",
  "ratio": "9:16",
  "duration": 4,
  "generate_audio": true
}

将示例地址替换为可公开读取的 HTTPS 视频地址。video_url 直接传 URL 字符串；duration 指输出时长，参考视频时长由系统读取，无需提交时长字段。多个视频依次加入 content，每项都使用 reference_video；提示词中的 @Video1、@Video2 按视频在列表中的顺序引用。

• 输入最多 10 个 MP4/MOV 视频，每个 2–30 秒，合计不超过 30 秒，每个文件不超过 100 MiB。
• 输出为 4–30 秒，支持 480p、720p；可设置 ratio 和 generate_audio，不使用 Motion Control 的专用参数。
• 可同时提供最多 2 张图片，使用 type: "image_url"、image_url 字符串和 role: "reference_image"。此模式中的图片是普通参考图，不保证作为首帧或尾帧；首尾帧角色也会按普通参考处理。
• 视频须使用 H.264/H.265 编码，帧率 24–60 fps；宽、高各为 300–6000 像素，总像素数（宽×高）为 409,600–8,295,044，宽/高比为 0.4–2.5。720×720 是符合尺寸限制的示例。

创建成功后，按返回的 status_url 或 GET /v1/videos/tasks/{id} 轮询同一任务；下载方式与其他模型相同。参考视频模式的费用包含参考输入与输出，详见下方计费说明。

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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

计费

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

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

当前各模型单秒价格请查看价格页面。分辨率、生成音频或 Motion Control 模式可能对应不同的单秒价格行。未使用参考视频的标准模型，计费秒数就是请求中的 duration；Motion Control 使用系统识别的参考视频时长，不足整秒时向上取整。Seedance 2.5 参考视频采用下面的预占与实际费用结算规则，不只按输出秒数计费。

创建任务时会先预占费用并从可用余额中扣除，因此生成期间余额已经减少。余额不足会在开始生成前返回 402。成功时按最终费用结算并处理预占差额，此时写入用量明细；cost_rmb 是最终实际费用。明确失败时退回全部预占费用。相邻请求的余额差额可能包含视频预占或退回，不能直接当作该条请求的费用。

Seedance 2.5 参考视频计费

参考视频模式会根据“参考视频合计时长向上取整 + 输出秒数”和价格页中的参考视频估算单价预占费用。例如，2 秒参考视频生成 4 秒输出，会先按 6 秒估算预占；这不是最终费用承诺。

最终按实际费用结算：低于预占金额时退回差额，高于预占金额时补扣差额；cost_rmb 和用量明细显示最终费用。明确失败时退回全部预占。若生成进度停在 99%，可能正在等待费用结算，请继续轮询原任务，不要重复提交。

Kling 4

kling-v4 支持 720p / 1080p、3–30 秒整数时长（默认 5 秒），音轨始终开启，generate_audio: false 本地拒绝。omni_reference_task_type 仅此型号支持 auto / reference / edit / extend。比例为 16:9 / 9:16 / 1:1 / 21:9，参考模式另支持 auto；续写不传 ratio。支持首尾帧、最多 8 张参考图、最多 5 个视频；每个视频 3–30 秒、合计不超过 30 秒，编辑/续写只用一个视频。编辑省略 duration 时按输入视频时长向上取整；其它模式默认 5 秒。所有素材（含首尾帧）都使用 asset_id：先向 POST /v1/videos/assets 以 multipart 提交 kind=image 或 kind=video 及 file，再把返回的 id 放入生成请求。不接收原始图片/视频 URL、音频引用或高级中间帧。续写可单独提供目标尾帧。

参考价：普通 720p ¥1.0486/秒、1080p ¥1.5729/秒；视频输入 720p ¥0.62916/计费秒、1080p ¥0.94374/计费秒。 参考/编辑含视频时计费秒数 = 输出秒数 + max(输出秒数, 输入总秒数向上取整)；续写只计新增秒数。

{
  "model": "kling-v4",
  "prompt": "Preserve the subject and change the setting",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "omni_reference_task_type": "edit",
  "content": [
    {
      "type": "video_url",
      "role": "reference_video",
      "asset_id": "vasset_uploaded_video"
    }
  ]
}

新增视频模型

所有新型号素材先上传为本用户的 asset_id。站内图片每张最多 10 MB，视频至少 3 秒、最多 100 MiB；这些是站内上传限制。暂不提供 Vidu Q4 音频参考或 Omni Ext 视频输入。音轨输出选项与音频参考是不同功能。

FLUX3 Video

FLUX3 支持文生、图生和单段视频编辑，5–20 秒（默认 5）；hd / fhd，比例 auto,21:9,2:1,16:9,4:3,1:1,3:4,9:16。图片最多 10 张，按首帧 → 中间 reference_image → 尾帧排列，保留顺序和重复；单个视频 3–30 秒。draft: true 仅支持 HD。generation_mode 可为 auto/t2v/i2v/v2v/draft_enhance。输出音轨默认开启，可关闭，参考价相同。

已完成的本站 FLUX3 草稿可从历史记录点击「生成正片 / 增强」。只提交 model、generation_mode: draft_enhance、本站来源 source_task_id、resolution；不新增提示词、素材、时长或音轨参数。仅同用户、同型号且已成功结算的草稿可增强，草稿费用不抵扣。

Vidu

Vidu Q4：单张首帧图生（提示词可省略）或 1–15 张参考图（提示词必填、最多 20000 字符），不支持纯文生或尾帧；单张 reference_image 明确选择参考模式，不与首帧混用。3–16 秒，默认 5；540p/720p/1080p/2K/4K。Q3：必须 1–7 张参考图，提示词最多 5000 字符，3–16 秒；Q3 Mix 为 1–16 秒且只有 720p/1080p。Q3 Pro/Turbo 支持纯文生、1 张首帧或首尾 2 帧，1–16 秒，540p/720p/1080p；纯文生提示词必填且最多 2000 字符，图生可省略。五款默认 720p、5 秒；参考模式和纯文生比例为 1:1/9:16/16:9/3:4/4:3，首帧图生跟随图片，不传比例。Q3/Mix 不发送音轨开关；Q4/Pro/Turbo 默认有音轨，可关闭，参考价相同。

Gemini Omni

Gemini Omni 主线 gemini-omni-1.1-flash：360p/720p/1080p/4k、16:9/9:16，最多 10 张图，首尾帧或普通参考，以及 1 段 3–10 秒视频。Preview 只有 720p、最多 16 张普通参考图、1 段 3–24 秒视频，不提供首尾帧模式；有视频时不传比例。两者输出长度由提示词控制（3–10 秒），不要发送 duration、generate_audio、seed、负向提示词或数量。参考输出价不含可能的素材和上下文用量，不是费用上限；按实际用量结算。

主线与 Preview 已成功结算的同型号站内任务，可从历史点击「继续生成」，新提示词必填，source_task_id 与视频输入互斥。不要输入供应商任务 ID。模式为 auto/t2v/i2v/reference/edit/extend。

Omni Ext：360p/720p/1080p/4k、16:9/9:16，4/6/8/10 秒（默认 6），按条计价。支持纯文生、1 张首帧或恰好 1/3 张参考图，不支持 2 张首尾帧、视频输入或来源任务续写。提示词必填，模式 auto/t2v/frame/reference；不发送音轨参数。

FLUX3 和 Omni 主线/Preview 均为参考输出价，实际任务费用优先；素材和上下文可能另计，先预留后结算，差额退还或补扣。99% 可能仍在等待结算，继续轮询原任务，勿重复提交。

最终人民币参考价（每秒）

Omni Ext 最终人民币参考价（每条）