# 视频生成（豆包原生）
> 以 Seedance 原生结构提交异步视频任务
> 支持文生视频、图生视频、首尾帧与全模态参考
> 提交即返回任务 ID，用任务状态接口轮询
`POST /doubao/api/v3/contents/generations/tasks`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 Seedance 系列的接口需要在 [ark 站](https://ark.oairoute.com/) 单独获取 Key，与 api 站的 Key 不通用。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_ARK_KEY ```
## 请求结构
`content` 放在顶层，不放在 `metadata` 里。`prompt` 可在顶层，也可作为 `content` 中的 `text` 条目。时长字段是整数类型的 `duration`。其余参数（`ratio`、`resolution`、`watermark` 等）在顶层。
## 支持的场景
| 场景 | content 条目 |
|---|---|
| 文生视频 | `text` |
| 图生视频·首帧 | `text` + `image_url`，role 为 `first_frame` |
| 图生视频·首尾帧 | `text` + 两个 `image_url`，role 分别为 `first_frame`、`last_frame` |
| 全模态参考 | `text` + 任意组合的 `image_url`、`video_url`、`audio_url` |
| 编辑视频 | 引用 `@视频1` 的 `text` + `video_url`，并设 `omni_reference_task_type: edit` |
| 延长视频 | 引用 `@视频1` 的 `text` + `video_url`，并设 `omni_reference_task_type: extend` |
**素材引用**：每个引用既可以是 HTTP(S) URL，也可以是 Base64 data URI，例如 `data:image/png;base64,...`，格式标识需小写。
网关对 Base64 素材有两种处理：渠道配置了图床时，会先把 Base64 转存为 URL 再上送上游（便于走真人过白）；未配置图床则原样转发。单渠道可以覆盖这个行为，设为跟随全局、始终转存或从不转存。
> **Note:** 提交后拿到的只是任务 ID。轮询结果用任务状态接口，见[获取任务状态](../tasks/status.html)。
## 请求参数
- `model` (string / 必填) — 取值：`seedance-2.5`、`seedance-2.0`、`seedance-2.0-fast`、`seedance-2.0-mini`。
- `content` (array / 必填) — 内容数组。至少包含一个 `text` 条目或一条素材引用。
- `content[].type` (string / 必填) — 取值 `text`、`image_url`、`video_url`、`audio_url`。
- `content[].text` (string / 可选) — `type` 为 `text` 时使用，写提示词。
- `content[].image_url.url` (string / 可选) — 图片地址，支持 HTTP(S) 与 Base64 data URI。
- `content[].video_url.url` (string / 可选) — 视频地址，按视频输入计费。
- `content[].audio_url.url` (string / 可选) — 音频地址。
- `content[].role` (string / 可选) — 取值 `first_frame`、`last_frame`、`reference_image`、`reference_video`、`reference_audio`。首帧、首尾帧、全模态参考三类互斥，不能混用。
- `prompt` (string / 可选) — 会被 `content` 里的 `text` 条目覆盖。
- `duration` (integer / 可选) — 时长，单位秒。传 `-1` 由模型决定。2-5 最长 30 秒，其余 2.x 最长 15 秒。
- `ratio` (string / 可选) — 取值 `adaptive`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`。
- `resolution` (string / 可选) — 取值 `480p`、`720p`、`1080p`、`4k`。2-5 支持到 1080p，2-0 支持 4K，fast 与 mini 仅 480p 与 720p。
- `seed` (integer / 可选) — 随机种子，范围 0 到 2147483647。
- `watermark` (boolean / 可选) — 是否加水印，默认 `false`。
- `camera_fixed` (boolean / 可选) — 固定镜头，默认 `false`。
- `generate_audio` (boolean / 可选) — 是否同时生成音频，默认 `false`。
- `return_last_frame` (boolean / 可选) — 是否返回末帧图片，默认 `false`。
- `draft` (boolean / 可选) — 草稿模式，默认 `false`。先用低成本出片看构图，确认后再正式生成。
- `omni_reference_task_type` (string / 可选) — 取值 `reference`、`edit`、`extend`。仅 2-5 使用，不传则由模型推断。
- `output_format` (string / 可选) — 取值 `mp4`（默认）或 `mov`。
- `service_tier` (string / 可选) — 影响优先级，示例值 `default`。
- `callback_url` (string / 可选) — 按方舟格式接收完成回调。
## 响应
- `id` (string) — 任务 ID。
- `model` (string) — 实际使用的模型。
- `status` (string) — 取值 `pending`、`processing`、`succeeded`、`failed`。
- `content.video_url` (string) — 成功时返回的成片地址。
- `seed` (integer) — 本次实际使用的种子。
- `resolution` (string) — 输出分辨率。
- `duration` (integer) — 实际输出秒数。
- `ratio` (string) — 输出画幅比例。
- `framespersecond` (integer) — 输出帧率。
- `service_tier` (string) — 实际生效的服务档位。
- `usage.completion_tokens` (integer) — 上游返回时才有。
- `usage.total_tokens` (integer) — 上游返回时才有。
- `error.code` (string) — 失败时返回，如 `content_policy_violation`。
- `error.message` (string) — 失败时的错误描述。
- `created_at` (integer) — 创建时间，Unix 秒。
- `updated_at` (integer) — 状态更新时间，Unix 秒。
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 permission_error |
| 429 | 触发限流 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
以下视频模型均可通过本接口提交任务，清单只列各厂商最新一代，实际可用范围以你的账号分组为准：
:::models video
各型号的能力差异：
| 项目 | 2.0 家族 | 2.5 |
|---|---|---|
| 最长时长 | 15 秒 | 30 秒 |
| 分辨率 | 480p / 720p / 1080p / 4k | 480p / 720p / 1080p |
2.0 家族里 fast 与 mini 只支持 480p 与 720p，4K 仅 2.0 标准版可用。
> **Note:** 完整模型目录（含时长上限、音画能力）可读取 `GET https://ark.oairoute.com/api/pricing`。
## 使用示例
### 文生视频
豆包原生通道用 `content` 数组描述输入：文本和图片都是 content 条目。提交后返回 `task_id`，再用任务状态接口轮询。
### 图生视频
把首帧图作为 content 条目传进去，`role` 标为 `first_frame`，模型会以这张图起手生成。
### 首尾帧过渡
同时给首帧和尾帧，模型生成中间的过渡过程。两帧风格差异越大，中间的运动幅度越明显。
### 参考视频
传 `video_url` 可以按参考视频的运镜和节奏生成新内容，适合批量做同风格素材。
**文生视频{Text to video}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "海面日落，镜头缓慢前推"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}'
```
**文生视频{Text to video}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "海面日落，镜头缓慢前推"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生视频{Text to video}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "海面日落，镜头缓慢前推"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}),
});
console.log(await res.json());
```
**首尾帧{First and last frame}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "让人物从站立缓缓转身"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last.png"
      },
      "role": "last_frame"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 5
}'
```
**首尾帧{First and last frame}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "让人物从站立缓缓转身"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last.png"
      },
      "role": "last_frame"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**首尾帧{First and last frame}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "让人物从站立缓缓转身"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last.png"
      },
      "role": "last_frame"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 5
}),
});
console.log(await res.json());
```
**图片参考{Image reference}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "@图片1 的人物在海边行走，镜头跟随"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ref.png"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 8
}'
```
**图片参考{Image reference}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "@图片1 的人物在海边行走，镜头跟随"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ref.png"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 8
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**图片参考{Image reference}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "@图片1 的人物在海边行走，镜头跟随"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ref.png"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 8
}),
});
console.log(await res.json());
```
**视频参考{Video reference}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "参考 @视频1 的运镜节奏，生成一段城市夜景"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/ref.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "reference"
}'
```
**视频参考{Video reference}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "参考 @视频1 的运镜节奏，生成一段城市夜景"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/ref.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "reference"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视频参考{Video reference}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "参考 @视频1 的运镜节奏，生成一段城市夜景"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/ref.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "reference"
}),
});
console.log(await res.json());
```
**视频编辑{Video editing}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "视频编辑：删除 @视频1 中的行人，只保留主角"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "output_format": "mov"
}'
```
**视频编辑{Video editing}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "视频编辑：删除 @视频1 中的行人，只保留主角"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "output_format": "mov"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视频编辑{Video editing}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "视频编辑：删除 @视频1 中的行人，只保留主角"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "output_format": "mov"
}),
});
console.log(await res.json());
```
**延长视频{Extend video}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "延长 @视频1，镜头继续向前推进，进入室内"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "extend",
  "output_format": "mov"
}'
```
**延长视频{Extend video}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "延长 @视频1，镜头继续向前推进，进入室内"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "extend",
  "output_format": "mov"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**延长视频{Extend video}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "延长 @视频1，镜头继续向前推进，进入室内"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "adaptive",
  "resolution": "1080p",
  "duration": 11,
  "omni_reference_task_type": "extend",
  "output_format": "mov"
}),
});
console.log(await res.json());
```
**200 文生视频{Text to video}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS1",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456789,
  "resolution": "1080p",
  "duration": 5,
  "ratio": "16:9",
  "framespersecond": 24,
  "created_at": 1763088289,
  "updated_at": 1763088289
}
```
**200 首尾帧{First and last frame}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS2",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456790,
  "resolution": "1080p",
  "duration": 5,
  "ratio": "adaptive",
  "framespersecond": 24,
  "created_at": 1763088290,
  "updated_at": 1763088290
}
```
**200 图片参考{Image reference}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS3",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456791,
  "resolution": "1080p",
  "duration": 8,
  "ratio": "16:9",
  "framespersecond": 24,
  "created_at": 1763088291,
  "updated_at": 1763088291
}
```
**200 视频参考{Video reference}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS4",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456792,
  "resolution": "1080p",
  "duration": 11,
  "ratio": "16:9",
  "framespersecond": 24,
  "created_at": 1763088292,
  "updated_at": 1763088292
}
```
**200 视频编辑{Video editing}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS5",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456793,
  "resolution": "1080p",
  "duration": -1,
  "ratio": "adaptive",
  "framespersecond": 24,
  "created_at": 1763088293,
  "updated_at": 1763088293
}
```
**200 延长视频{Extend video}**
```
{
  "id": "task_doubao_01KA040M0HP1GJWBJYZMKX1XS6",
  "model": "seedance-2.5",
  "status": "pending",
  "content": {},
  "seed": 123456794,
  "resolution": "1080p",
  "duration": 11,
  "ratio": "adaptive",
  "framespersecond": 24,
  "created_at": 1763088294,
  "updated_at": 1763088294
}
```