视频生成 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.5",
  "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.5",
  "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
}

使用 content_url 下载视频。

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 202 后，应持续轮询返回的 task_id；重复调用创建接口可能产生另一个任务。
• 轮询和下载的 GET 请求可以安全重试。
• 轮询返回 HTTP 404 不代表生成失败，也不要因此重新提交。保留原任务 ID，核对返回的 status_url 或改用 GET /v1/videos/tasks/{id}，并使用任务所属账户的有效 API Key。任务可能已成功且已结算，可查看用量明细；仍无法查询时向客服提供任务 ID 和提交时间。
• 如果创建接口返回 submission_unknown，不要重新提交。任务可能已经被接受；请向客服提供请求时间、模型和提示词摘要。
• 已确认任务进入终态 failed 后，如果确实要重新生成，可重新创建任务。

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

创建请求参数

参考素材列表（content）

• 支持 URL 的模型。例如 Seedance 2.5 和 Motion Control。每项素材的 image_url 或 video_url 直接填写一个 HTTPS URL 字符串，确保地址在任务读取期间可公开访问。
• 要求上传素材的模型。Kling 4、Kling 4.0 Flash、FLUX3 Video、本页列出的 Vidu Q3/Q4 和 Gemini Omni 模型使用同一账户上传的素材。先上传参考素材，再在各项的 asset_id 中填入返回的 id。

下面演示使用 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。
• 当前不支持参考音频素材。

上传视频素材

上传时，multipart 的 kind 必须在 file 之前；kind 用 image 或 video，须与文件类型匹配。

curl -sS https://api.icodeeasy.cc/v1/videos/assets \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -F 'kind=video' \
  -F '[email protected];type=video/mp4'

HTTP 201 返回素材对象。将 id 放入创建请求的 content[].asset_id。

删除视频素材

curl -i -sS -X DELETE 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

用素材所属账户的 Key 删除素材，成功返回 HTTP 204。

响应与下载行为

任务响应使用统一结构：

使用 content_url 下载。鉴权内容接口支持 HTTP Range 和常见的条件下载请求头，可能返回 200、206 Partial Content 或重定向到 Relay 管理的存储。请让客户端跟随重定向。任务成功前请求内容会返回 409 video_not_ready。

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

删除已结束的任务

curl -i -sS -X DELETE 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

安全删除终态任务会返回 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.5",
  "error": { "code": "generation_failed" }
}

计费

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

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

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

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

Seedance 2.5 参考视频计费

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

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

首帧 + 尾帧完整调用

把两张图片放在可公开读取的 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 本身始终必填。服务会在开始任务前校验参数组合。

Kling 4

kling-v4 支持 720p / 1080p、3–30 秒整数时长（默认 5 秒），音轨始终开启，generate_audio: false 本地拒绝。Kling 4 系列支持 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"
    }
  ]
}

Kling 4.0 Flash

Kling 4.0 Flash 支持 720p、3–20 秒（默认 5 秒）和生成音轨，继续使用 omni_reference_task_type。首帧模式只传一张 first_frame，省略 ratio，输出跟随图片比例。参考生成最多使用 10 张图和 5 个视频，每段视频 3–20 秒且合计不超过 20 秒。编辑使用一段 3–20 秒视频，可另加参考图。续写只传一段视频，省略图片和 ratio，结果只返回新增片段。素材均使用本人上传的 asset_id。

720p 无视频输入的生成及续写新增片段每秒 ¥0.66。编辑和带参考视频的生成每计费秒 ¥0.440003，计费秒数为输出时长加上输出时长和向上取整后输入时长中的较大值。

新增视频模型

所有新型号素材先上传为本用户的 asset_id。站内图片每张最多 10 MB，视频至少 3 秒、最多 100 MiB。暂不提供 Vidu Q4 音频参考。

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 1.1 Flash

gemini-omni-1.1-flash

支持 360p/720p/1080p/4k、16:9 或 9:16，时长 4/6/8/10 秒（默认 6 秒）。各模式均需提示词。可纯文生、上传 1 张首帧，或提供 1 张或 3 张普通参考图。generation_mode 可选 auto、t2v、frame 或 reference。省略音轨参数。暂不支持尾帧、视频输入或来源任务续写，按条计价。

Gemini Omni Flash Preview

gemini-omni-flash-preview 支持 720p、最多 16 张普通参考图或一段 3–24 秒视频。使用视频输入时省略 ratio。提示词决定 3–10 秒的输出时长，省略 duration、generate_audio、seed、负向提示词和数量。

续写本人已完成且结算的 Preview 任务时，在历史中选择「继续生成」并输入新提示词。使用站内 source_task_id 或上传视频，二选一。支持 auto/t2v/i2v/reference/edit/extend。

FLUX3 和 Gemini Omni Flash Preview 展示参考输出价，素材和上下文可能另计，按任务实际费用结算。进度到 99% 时可能仍在等待结算，请继续查询原任务。

Gemini Omni 1.2 Flash

Gemini Omni 1.2 Flash 支持 360p/720p/1080p/4k 和 16:9 或 9:16，各模式都需要提示词。文生视频或首尾帧使用 generation_mode: auto，参考图使用 reference（最多 10 张）。参考图与首尾帧分开使用。输出时长 3–15 秒（默认 10 秒），首尾帧模式为 3–10 秒。

编辑或续写使用 generation_mode: edit 或 extend，上传一段不超过 15 秒、64 MB 的 MP4 或 MOV 并传入其 asset_id。编辑省略 duration，按源视频时长计费；续写的 duration 为新增的 3–10 秒，只按新增秒数计费。也可用本人已完成的同模型站内 source_task_id 续写。省略 generate_audio。

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

Gemini Omni 1.1 Flash 最终人民币参考价（每条）