{"doc":{"category_id":null,"content":"# 火山引擎(方舟)视频生成接入指南\n\nOpenAI 兼容：`POST /v1/video/generations`。原生路径：`/api/v3/contents/generations/tasks`。[视频生成 API](https://www.volcengine.com/docs/82379/1520757)\n\n时长 `4`–`30` 或 `-1`，分辨率 `480p`/`720p`/`1080p`，参考最多 50（图 30 + 视频 10 + 音频 10）。\n\n| 场景 | Body | 2.5 约束 |\n| :--- | :--- | :--- |\n| 文生 | 仅 `prompt` | 无 |\n| 首帧 / 首尾帧 | `images`：`first_frame` / `last_frame` | `ratio=adaptive` |\n| 参考生 | `reference_*` + `omni_reference_task_type=auto` | 参考视频建议 4–30 秒 |\n| 编辑 | `reference_video` + `omni_reference_task_type=edit` | `ratio=adaptive`，`duration=-1` |\n| 延长 | `reference_video` + `omni_reference_task_type=extend` | `ratio=adaptive`；时长 4–30 或 `-1` |\n| 样片预览 (Draft) | `draft=true` | 仅支持 `480p`（缺省自动兜底），计费同普通 480p，7 天有效 |\n| 样片转正片 | `draft_task_id` + `resolution` | 自动继承样片 Prompt 与素材，指定目标分辨率生成正片 |\n\n```http\nPOST https://{{domain}}/v1/video/generations\nAuthorization: Bearer sk-your_token\nContent-Type: application/json\n```\n\n### 文生\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"一只穿红大衣的小猫在雪地里抓雪花，电影微距\",\n  \"resolution\": \"720p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 8,\n  \"generate_audio\": true\n}\n```\n`duration` 可改为 `30` 或 `-1`（模型自选）。\n\n### 图生（首帧 / 首尾帧）\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"画面从日出过渡到雷雨，女孩对着镜头说茄子，环绕运镜\",\n  \"images\": [\n    {\"url\": \"https://example.com/first.png\", \"role\": \"first_frame\"},\n    {\"url\": \"https://example.com/last.png\", \"role\": \"last_frame\"}\n  ],\n  \"ratio\": \"adaptive\",\n  \"duration\": 5,\n  \"generate_audio\": true\n}\n```\n只要首帧时去掉 `last_frame` 那一项。两张纯 URL 也会按首/尾帧推断。\n\n### 参考生\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"角色跟参考图一致，动作跟参考视频，节奏贴合参考音频\",\n  \"images\": [{\"url\": \"https://example.com/char.png\", \"role\": \"reference_image\"}],\n  \"videos\": [{\"url\": \"https://example.com/motion.mp4\", \"role\": \"reference_video\"}],\n  \"audios\": [{\"url\": \"https://example.com/bgm.mp3\", \"role\": \"reference_audio\"}],\n  \"ratio\": \"16:9\",\n  \"duration\": 12,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"auto\"\n}\n```\n可只传图、只传视频或只传音频（2.5）。`role` 与 `type` 等价。\n\n### 视频编辑\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"将外套改为红色，构图与运镜不变\",\n  \"videos\": [{\"url\": \"https://example.com/edit.mp4\", \"role\": \"reference_video\"}],\n  \"ratio\": \"adaptive\",\n  \"duration\": -1,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"edit\",\n  \"output_format\": \"mov\"\n}\n```\n\n### 视频延长\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"延续故事，人物继续走入街道\",\n  \"videos\": [{\"url\": \"https://example.com/clip.mp4\", \"role\": \"reference_video\"}],\n  \"ratio\": \"adaptive\",\n  \"duration\": 11,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"extend\",\n  \"output_format\": \"mov\"\n}\n```\n\n### 样片预览与转正片（Draft Mode）\n\nSeedance 2.5 支持两阶段样片模式：先低成本生成 480p 预览样片，满意后再转成高清正式视频。\n\n#### 阶段 1：生成 480p 预览样片\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"一只穿红大衣的小猫在雪地里抓雪花，电影微距\",\n  \"draft\": true\n}\n```\n> **提示**：配置 `\"draft\": true` 后无需传入分辨率，系统默认按 `480p` 提交，计费与普通 480p 视频一致。提交成功后获取任务 ID，该样片任务 ID 有效期为 **7 天**。\n\n#### 阶段 2：基于样片生成高清正片\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"draft_task_id\": \"cgt-xxxxxxxx\",\n  \"resolution\": \"1080p\"\n}\n```\n> **提示**：传入 `draft_task_id`（填入 7 天内的样片任务 ID）与目标分辨率（如 `720p` / `1080p`），模型会自动继承原样片的 Prompt、参考素材、宽高比与种子，无需重复传递入参。系统将自动进行同账号渠道亲和绑定，确保 100% 成功。\n\n`omni_reference_task_type`：`auto`（按提示词判断，不符限制时异步报错）/ `edit` / `extend`（提交时前置校验）。提示词需与类型一致（编辑：修改/替换/加上/去掉；延长：延长/延续/续写）。\n\n`output_format`：`mp4`（默认，兼容好）/ `mov`（编辑、延长推荐，后期调色用）。\n\n常用可选：`web_search`、`watermark`、`return_last_frame`、`seed`。已有官方 `content` 则整包透传，不要再叠 `prompt`/`images`。\n\n### 响应（OpenAI 兼容）\n\n`POST /v1/video/generations` 立即返回任务 ID：\n\n```json\n{\n  \"id\": \"cgt-xxxxxxxx\",\n  \"object\": \"video.generation\",\n  \"status\": \"pending\",\n  \"created\": 1719441600\n}\n```\n\n`GET /v1/video/generations/{id}` 完成时：\n\n```json\n{\n  \"id\": \"cgt-xxxxxxxx\",\n  \"object\": \"video.generation\",\n  \"status\": \"completed\",\n  \"created\": 1719441600,\n  \"data\": [{ \"url\": \"https://example.com/output/seedance.mp4\" }],\n  \"usage\": {\n    \"prompt_tokens\": 128,\n    \"completion_tokens\": 256,\n    \"total_tokens\": 384\n  }\n}\n```\n\n成片取 `data[0].url`。`usage` 为 OpenAI token 消耗；上游未回时为 0。失败时 `status` 为 `failed`，带 `error`。\n\n## 完整参数字典说明\n\n| 参数 | 类型 | 必填 | 说明 |\n| :--- | :--- | :--- | :--- |\n| `model` | string | 是 | 推荐 `doubao-seedance-2-5` |\n| `prompt` | string | 是 | 画面 / 编辑 / 延长意图 |\n| `images` / `image_urls` | array | 否 | URL 或 `{url, role}`：`first_frame` / `last_frame` / `reference_image` |\n| `videos` | array | 否 | `{url, role: \"reference_video\"}` |\n| `audios` | array | 否 | `{url, role: \"reference_audio\"}`；2.5 可仅音频 |\n| `resolution` | string | 否 | 2.5：`480p` / `720p` / `1080p` |\n| `ratio` | string | 否 | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |\n| `duration` | integer | 否 | 2.5：`4`–`30` 或 `-1`（模型自选） |\n| `omni_reference_task_type` | string | 否 | 全模态任务类型：`auto` / `edit` / `extend`。`edit`/`extend` 提交时校验；`auto` 不符限制则异步报错 |\n| `output_format` | string | 否 | `mp4`（默认）/ `mov`（编辑、延长推荐） |\n| `generate_audio` | boolean | 否 | 是否出音轨 |\n| `watermark` | boolean | 否 | 水印 |\n| `return_last_frame` | boolean | 否 | 结果带回尾帧图 |\n| `web_search` | boolean | 否 | 联网搜索 |\n| `seed` | integer | 否 | 随机种子 |\n| `camera_fixed` | boolean | 否 | 锁定镜头 |\n| `content` | array | 否 | 官方多模态数组，有则直通 |\n| `draft` | boolean | 否 | 样片模式开关；开启后固定生成 480p 样片 |\n| `draft_task_id` | string | 否 | 样片转正片时引用的样片任务 ID（7天内有效） |\n\n`role` 与 `type` 等价。\n\n---\n\n## 2.0 及更早\n\n`doubao-seedance-2-0`（及 fast/mini）：把上面示例的 `model` 换成对应 ID。时长为 `4`–`15` 或 `-1`；分辨率可到 `4k`（非 fast/mini）；首帧不强制 `adaptive`；参考上限 15（图 9 + 视频 3 + 音频 3），不能只传音频。\n\n```json\n{\n  \"model\": \"doubao-seedance-2-0\",\n  \"prompt\": \"一只穿红大衣的小猫在雪地里抓雪花，电影微距\",\n  \"resolution\": \"720p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5,\n  \"generate_audio\": true\n}\n```\n\n\n\n### 5. 常见错误码与问题排查\n\nHTTP 状态码、错误体格式及分场景排查已 **统一维护** 于专页，避免与各调用示例重复不同步。\n\n👉 **[网关常见错误码与排查]({{error_codes_href}})**\n\n**速记**（详情见专页）：\n\n| 码 | 含义 |\n| :---: | :--- |\n| **400** | 参数非法 / 内容风控或版权拦截 |\n| **402** | 账户余额不足（**不是** 429） |\n| **429** | 令牌 RPS/RPM 限频，或低余额在途任务过多 |\n| **403** | 令牌/IP/模型权限（余额见 402；内容拦截见 400） |\n| **200 + `status: failed`** | 异步视频等长任务的业务失败（轮询时常见） |\n\nHTTP 响应码与控制台调用日志 `status_code` 一致，可按 `log_id` 追溯。\n\n> **维护约定**：新增或调整错误说明时，请只更新专页 `error-codes`；本附录通过链接自动指向最新内容。\n","created_at":"2026-08-20T10:08:07.679Z","id":47,"is_active":1,"is_dir":0,"is_preset":1,"parent_id":36,"slug":"volc-video","sort_order":50,"title":"火山方舟视频","translations":{"en":{"content":"# Volcengine Seedance Video Generation\n\nOpenAI-compatible: `POST /v1/video/generations`. Native: `/api/v3/contents/generations/tasks`. [Video API](https://www.volcengine.com/docs/82379/1520757)\n\nDuration `4`–`30` or `-1`; resolution `480p`/`720p`/`1080p`; up to 50 refs (30 images + 10 videos + 10 audios).\n\n| Task | Body | 2.5 constraint |\n| :--- | :--- | :--- |\n| Text | `prompt` only | none |\n| First / last frame | `first_frame` / `last_frame` | `ratio=adaptive` |\n| Reference | `reference_*` + `omni_reference_task_type=auto` | ref video 4–30s |\n| Edit | `reference_video` + `omni_reference_task_type=edit` | `ratio=adaptive`, `duration=-1` |\n| Extend | `reference_video` + `omni_reference_task_type=extend` | `ratio=adaptive`; duration `4`–`30` or `-1` |\n\n```http\nPOST https://{{domain}}/v1/video/generations\nAuthorization: Bearer sk-your_token\nContent-Type: application/json\n```\n\n### Text-to-video\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"A kitten in a red coat catching snowflakes, cinematic close-up\",\n  \"resolution\": \"720p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 8,\n  \"generate_audio\": true\n}\n```\nUse `30` or `-1` (model picks duration).\n\n### Image-to-video (first / last frame)\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"Sunrise to storm; the girl says cheese, orbit camera\",\n  \"images\": [\n    {\"url\": \"https://example.com/first.png\", \"role\": \"first_frame\"},\n    {\"url\": \"https://example.com/last.png\", \"role\": \"last_frame\"}\n  ],\n  \"ratio\": \"adaptive\",\n  \"duration\": 5,\n  \"generate_audio\": true\n}\n```\nDrop `last_frame` for first-frame only. Two plain URLs are treated as first + last.\n\n### Reference\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"Match the image character, video motion, and audio rhythm\",\n  \"images\": [{\"url\": \"https://example.com/char.png\", \"role\": \"reference_image\"}],\n  \"videos\": [{\"url\": \"https://example.com/motion.mp4\", \"role\": \"reference_video\"}],\n  \"audios\": [{\"url\": \"https://example.com/bgm.mp3\", \"role\": \"reference_audio\"}],\n  \"ratio\": \"16:9\",\n  \"duration\": 12,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"auto\"\n}\n```\nAny subset is fine (2.5 allows audio-only). `role` ≡ `type`.\n\n### Edit\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"Change the coat to red; keep framing and camera\",\n  \"videos\": [{\"url\": \"https://example.com/edit.mp4\", \"role\": \"reference_video\"}],\n  \"ratio\": \"adaptive\",\n  \"duration\": -1,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"edit\",\n  \"output_format\": \"mov\"\n}\n```\n\n### Extend\n```json\n{\n  \"model\": \"doubao-seedance-2-5\",\n  \"prompt\": \"Continue as they walk into the street\",\n  \"videos\": [{\"url\": \"https://example.com/clip.mp4\", \"role\": \"reference_video\"}],\n  \"ratio\": \"adaptive\",\n  \"duration\": 11,\n  \"generate_audio\": true,\n  \"omni_reference_task_type\": \"extend\",\n  \"output_format\": \"mov\"\n}\n```\n\n`omni_reference_task_type`: `auto` (infer from prompt; mismatch fails async) / `edit` / `extend` (validated on submit). Keep the prompt aligned (edit: change/add/remove; extend: extend/continue).\n\n`output_format`: `mp4` (default) / `mov` (recommended for edit/extend).\n\nOptional: `web_search`, `watermark`, `return_last_frame`, `seed`. If `content` is set, it is forwarded as-is.\n\n### Response (OpenAI-compatible)\n\n`POST /v1/video/generations` returns a task id immediately:\n\n```json\n{\n  \"id\": \"cgt-xxxxxxxx\",\n  \"object\": \"video.generation\",\n  \"status\": \"pending\",\n  \"created\": 1719441600\n}\n```\n\n`GET /v1/video/generations/{id}` when completed:\n\n```json\n{\n  \"id\": \"cgt-xxxxxxxx\",\n  \"object\": \"video.generation\",\n  \"status\": \"completed\",\n  \"created\": 1719441600,\n  \"data\": [{ \"url\": \"https://example.com/output/seedance.mp4\" }],\n  \"usage\": {\n    \"prompt_tokens\": 128,\n    \"completion_tokens\": 256,\n    \"total_tokens\": 384\n  }\n}\n```\n\nUse `data[0].url` for the video. `usage` is OpenAI token usage (zeros if upstream omitted it). On failure, `status` is `failed` with `error`.\n\n## Parameter reference\n\n| Field | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `model` | string | yes | Prefer `doubao-seedance-2-5` |\n| `prompt` | string | yes | Scene / edit / extend intent |\n| `images` / `image_urls` | array | no | URL or `{url, role}`: `first_frame` / `last_frame` / `reference_image` |\n| `videos` | array | no | `{url, role: \"reference_video\"}` |\n| `audios` | array | no | `{url, role: \"reference_audio\"}`; 2.5 allows audio-only |\n| `resolution` | string | no | 2.5: `480p` / `720p` / `1080p` |\n| `ratio` | string | no | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |\n| `duration` | integer | no | 2.5: `4`–`30` or `-1` |\n| `omni_reference_task_type` | string | no | `auto` / `edit` / `extend`. `edit`/`extend` validated on submit |\n| `output_format` | string | no | `mp4` (default) / `mov` (edit/extend) |\n| `generate_audio` | boolean | no | Soundtrack |\n| `watermark` | boolean | no | Watermark |\n| `return_last_frame` | boolean | no | Include last-frame image |\n| `web_search` | boolean | no | Web search |\n| `seed` | integer | no | Random seed |\n| `camera_fixed` | boolean | no | Lock camera |\n| `content` | array | no | Official array, pass-through |\n\n`role` ≡ `type`.\n\n---\n\n## 2.0 and earlier\n\n`doubao-seedance-2-0` (and fast/mini): swap `model` in the examples above. Duration `4`–`15` or `-1`; resolution up to `4k` (not fast/mini); first-frame need not use `adaptive`; max 15 refs; audio-only is not supported.\n\n```json\n{\n  \"model\": \"doubao-seedance-2-0\",\n  \"prompt\": \"A kitten in a red coat catching snowflakes, cinematic close-up\",\n  \"resolution\": \"720p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5,\n  \"generate_audio\": true\n}\n```\n\n\n\n### 5. Common Error Codes & Troubleshooting\n\nHTTP codes, error body format, and troubleshooting are **maintained in one dedicated page** (not duplicated under each example).\n\n👉 **[Gateway Error Codes & Troubleshooting]({{error_codes_href}})**\n\n**Quick reference**:\n\n| Code | Meaning |\n| :---: | :--- |\n| **402** | Insufficient balance (**not** 429) |\n| **400** | Bad request / content or copyright filter |\n| **429** | RPS/RPM limits or in-flight task cap (low balance) |\n| **403** | Token / IP / model permission (balance → 402; content filter → 400) |\n| **200 + `status: failed`** | Async video/long-task business failure on poll |\n\nHTTP status matches call log `status_code` for traceability by `log_id`.\n\n> **Maintenance**: update the `error-codes` article only; this appendix links to it.\n","title":"Volcengine Video"}},"updated_at":"2026-10-31T15:20:23.284Z"}}