> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 提交视频任务
> 提交视频生成任务，支持 Sora 2、Veo、Dreamina Seedance 等模型
## 简介
提交视频任务接口用于创建异步视频生成任务。MixRoute 通过统一入口支持 Sora 2、Veo 和 Dreamina Seedance 等视频模型。
视频生成是异步任务。提交成功后，需要使用任务 ID 轮询查询任务状态，并在任务成功后获取视频结果。
## API Base URL
```text theme={null}
https://api.mixroute.ai/v1
```
## 认证
使用 Bearer Token：
```http theme={null}
Authorization: Bearer sk-xxxxxxxxxx
```
## 调用流程
1. **提交任务**：`POST /v1/video/generations`
2. **轮询状态**：`GET /v1/video/generations/{task_id}`
3. **获取结果**：任务成功后，从查询接口返回的数据中获取视频 URL 或结果对象
## 支持的模型
| 模型 ID | 厂商 | 说明 |
| ----------------------------------- | ------ | -------------------------- |
| `sora-2` | OpenAI | Sora 2 视频生成模型 |
| `veo-3.0-fast-generate-001` | Google | Veo 3.0 快速版 |
| `veo-3.1-fast-generate-preview` | Google | Veo 3.1 快速版 |
| `veo-3.0-generate-preview` | Google | Veo 3.0 标准版 |
| `veo-3.1-generate-preview` | Google | Veo 3.1 标准版 |
| `dreamina-seedance-2-0-260128` | 字节跳动 | Dreamina Seedance 2.0 |
| `dreamina-seedance-2-0-fast-260128` | 字节跳动 | Dreamina Seedance 2.0 Fast |
| `dreamina-seedance-2-0-mini-260615` | 字节跳动 | Dreamina Seedance 2.0 Mini |
| `seedance-1-5-pro-251215` | 字节跳动 | Seedance 1.5 Pro |
| `seedance-1-0-pro-250528` | 字节跳动 | Seedance 1.0 Pro |
| `seedance-1-0-pro-fast-251015` | 字节跳动 | Seedance 1.0 Pro Fast |
文档中的模型 ID 必须按表格完整传入。不要使用 `seedance-1.0`、`seedance-1.0-pro`、`seedance-1.5-pro` 等简写别名。
***
## 请求体结构
不同模型的参数名称不完全一致。`model` 和 `prompt` 位于请求体第一层，其余参数按模型要求传入。
### 通用字段
要调用的模型 ID。
视频描述提示词。
### Sora 2 参数
视频时长（秒）：`5`、`10`、`15`、`20`，默认 `5`。
分辨率：`480p`、`720p`、`1080p`，默认 `720p`。
宽高比：`16:9`、`9:16`、`1:1`，默认 `16:9`。
参考图片 URL，用于图生视频模式。
原始视频 URL，用于 Remix 模式。
### Veo 参数
视频时长（秒）：`4`、`6`、`8`。
宽高比：`16:9`、`9:16`。
分辨率：`720p`、`1080p`。
首帧参考图，支持图片 URL 或 Base64。
尾帧参考图，仅 `veo-3.1` 系列支持。
是否生成同步音频，默认 `false`。
### Dreamina Seedance 参数
MixRoute 调用 Seedance 时，第一层 JSON 只放 `model`、`prompt`、`asset`。官方 Seedance 的 `content`、`duration`、`generate_audio`、`resolution`、`ratio`、`watermark` 等参数都放在 `metadata` 对象内。
Seedance 在 MixRoute 中使用 `metadata.ratio`，不是 `aspect_ratio`；使用 `metadata.content` 描述文本、图片、视频和音频输入，不使用第一层的 `first_frame`、`last_frame` 或 `reference_image`。
是否启用真人素材库或授权素材能力。需要使用素材库、虚拟人像或已授权真人素材时，设为 `true`。
Seedance 官方参数容器。除 `model`、`prompt`、`asset` 外，Seedance 参数均放入此对象。
输入给 Seedance 的内容数组。建议始终包含一个 `text` 对象，且文本与第一层 `prompt` 保持一致。
视频时长，单位为秒。Seedance 1.0 Pro / 1.0 Pro Fast 支持 `[2, 12]`；Seedance 1.5 Pro 支持 `[4, 12]` 或 `-1`；Seedance 2.0 系列支持 `[4, 15]` 或 `-1`。`-1` 表示由模型自动选择合适时长。
是否生成与画面同步的音频。Seedance 2.0 系列和 Seedance 1.5 Pro 支持，默认 `true`。
分辨率：`480p`、`720p`、`1080p`、`4k`。Seedance 2.0 Fast 和 2.0 Mini 不支持 `1080p`；`4k` 仅 Seedance 2.0 标准版支持。
宽高比：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。Seedance 2.0 系列和 Seedance 1.5 Pro 默认 `adaptive`。
是否在生成视频右下角添加 `AI 生成` 水印，默认 `false`。
#### metadata.content 类型
| 类型 | 结构 | role | 说明 |
| ---- | --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
| 文本 | `{ "type": "text", "text": "..." }` | 无 | 文生视频或与媒体输入配合使用 |
| 图片 | `{ "type": "image_url", "image_url": { "url": "..." } }` | `first_frame`、`last_frame`、`reference_image` | 首帧、尾帧或参考图 |
| 视频 | `{ "type": "video_url", "video_url": { "url": "..." } }` | `reference_video` | 仅 Seedance 2.0 系列支持 |
| 音频 | `{ "type": "audio_url", "audio_url": { "url": "..." } }` | `reference_audio` | 仅 Seedance 2.0 系列支持，不能单独输入，至少需要 1 个参考图片或视频 |
| 样片任务 | `{ "type": "draft_task", "draft_task": { "id": "..." } }` | 无 | 仅 Seedance 1.5 Pro 支持 |
图片、音频可以使用公网 URL、Base64 或素材 ID；视频可以使用公网 URL 或素材 ID。素材 ID 格式为 `asset://`。
#### Seedance 能力约束
| 场景 | 支持模型 | 要求 |
| ---------- | ------------------------------------------------- | -------------------------------------------------------------- |
| 文生视频 | 所有 Seedance 模型 | `metadata.content` 至少包含一个 `text` 对象 |
| 图生视频 - 首帧 | 所有 Seedance 模型 | 传入 1 个 `image_url`；`role` 可为 `first_frame` 或省略 |
| 图生视频 - 首尾帧 | Seedance 2.0 系列、Seedance 1.5 Pro、Seedance 1.0 Pro | 传入 2 个 `image_url`，且分别设置 `role` 为 `first_frame` 和 `last_frame` |
| 多模态参考生视频 | Seedance 2.0 系列 | 可输入 0-9 张参考图片、0-3 个参考视频、0-3 段参考音频；音频不能单独输入 |
***
## 使用示例
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "sora-2",
"prompt": "一只金毛犬在海滩上奔跑，阳光明媚，慢动作镜头",
"duration": 10,
"resolution": "1080p",
"aspect_ratio": "16:9"
}'
```
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "veo-3.1-fast-generate-preview",
"prompt": "清晨阳光洒在赛博城市的高楼群，镜头慢慢推进",
"durationSeconds": 6,
"aspectRatio": "16:9",
"resolution": "1080p",
"generateAudio": false
}'
```
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "dreamina-seedance-2-0-fast-260128",
"prompt": "清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进",
"metadata": {
"content": [
{
"type": "text",
"text": "清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进"
}
],
"duration": 4,
"generate_audio": false,
"resolution": "720p",
"ratio": "16:9",
"watermark": false
},
"asset": true
}'
```
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "seedance-1-5-pro-251215",
"prompt": "人物缓缓转头微笑，背景保持柔和虚化",
"metadata": {
"content": [
{
"type": "text",
"text": "人物缓缓转头微笑，背景保持柔和虚化"
},
{
"type": "image_url",
"image_url": {
"url": "https://api.mixroute.ai/portrait.jpg"
},
"role": "first_frame"
}
],
"duration": 5,
"generate_audio": false,
"resolution": "720p",
"ratio": "adaptive",
"watermark": false
},
"asset": true
}'
```
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "dreamina-seedance-2-0-260128",
"prompt": "汽车从静止状态平稳加速驶向远方，镜头低角度跟随",
"metadata": {
"content": [
{
"type": "text",
"text": "汽车从静止状态平稳加速驶向远方，镜头低角度跟随"
},
{
"type": "image_url",
"image_url": {
"url": "https://api.mixroute.ai/car-start.jpg"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://api.mixroute.ai/car-end.jpg"
},
"role": "last_frame"
}
],
"duration": 6,
"generate_audio": false,
"resolution": "720p",
"ratio": "16:9",
"watermark": false
},
"asset": true
}'
```
```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "dreamina-seedance-2-0-fast-260128",
"prompt": "使用 Video 1 的第一人称视角构图，并使用 Audio 1 作为全片背景音乐。制作一支果茶广告，开场使用 Image 1，结尾定格在 Image 2。",
"metadata": {
"content": [
{
"type": "text",
"text": "使用 Video 1 的第一人称视角构图，并使用 Audio 1 作为全片背景音乐。制作一支果茶广告，开场使用 Image 1，结尾定格在 Image 2。"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/r2v_tea_pic1.jpg"
},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/r2v_tea_pic2.jpg"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_video/r2v_tea_video1.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_audio/r2v_tea_audio1.mp3"
},
"role": "reference_audio"
}
],
"duration": 5,
"generate_audio": true,
"resolution": "720p",
"ratio": "16:9",
"watermark": false
},
"asset": true
}'
```
***
## 响应示例
### 提交任务响应
```json theme={null}
{
"id": "task_N6QRBeaX4ohVAiODaVKCu7LGH4fPEO3B",
"task_id": "task_N6QRBeaX4ohVAiODaVKCu7LGH4fPEO3B",
"object": "video",
"model": "dreamina-seedance-2-0-fast-260128",
"status": "queued",
"progress": 0,
"created_at": 1782556739
}
```
### 查询任务响应
```json theme={null}
{
"code": "success",
"message": "",
"data": {
"task_id": "task_N6QRBeaX4ohVAiODaVKCu7LGH4fPEO3B",
"status": "SUCCESS",
"progress": "100%",
"fail_reason": "",
"result_url": "https://example.com/generated-video.mp4",
"properties": {
"upstream_model_name": "dreamina-seedance-2-0-fast-260128",
"origin_model_name": "dreamina-seedance-2-0-fast-260128"
},
"data": {
"id": "cgt-20260627183858-cq47w",
"status": "succeeded",
"content": {
"video_url": "https://example.com/generated-video.mp4"
},
"duration": 4,
"ratio": "16:9",
"resolution": "720p",
"generate_audio": false
}
}
}
```
状态字段可能因模型和上游平台而异。客户端应同时处理 `queued`、`running`、`succeeded`、`failed`、`expired`，以及查询接口中返回的上游状态值，例如 `NOT_START`、`SUCCESS`。成功后通常可从外层 `data.result_url` 或嵌套的 `data.data.content.video_url` 读取视频地址。
***
## Python 示例
```python theme={null}
import time
import requests
API_KEY = "sk-xxxxxxxxxx"
BASE_URL = "https://api.mixroute.ai/v1"
def submit_seedance_task(prompt: str) -> str:
payload = {
"model": "dreamina-seedance-2-0-fast-260128",
"prompt": prompt,
"metadata": {
"content": [
{
"type": "text",
"text": prompt,
}
],
"duration": 4,
"generate_audio": False,
"resolution": "720p",
"ratio": "16:9",
"watermark": False,
},
"asset": True,
}
response = requests.post(
f"{BASE_URL}/video/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
return data["task_id"]
def wait_for_task(task_id: str) -> dict:
while True:
response = requests.get(
f"{BASE_URL}/video/generations/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=60,
)
response.raise_for_status()
result = response.json()
data = result.get("data", result)
status = data.get("status")
if status in {"succeeded", "SUCCEEDED", "SUCCESS"}:
return data
if status in {"failed", "FAILED", "expired", "EXPIRED"}:
raise RuntimeError(data.get("fail_reason") or data)
time.sleep(5)
task_id = submit_seedance_task(
"清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进"
)
print(f"任务已提交: {task_id}")
print(wait_for_task(task_id))
```
***
## 模型对比
| 特性 | Sora 2 | Veo | Dreamina Seedance |
| ----- | ------ | -------------- | -------------------------------------------------------------------- |
| 最大时长 | 20 秒 | 8 秒 | Seedance 2.0 最高 15 秒；Seedance 1.5 Pro 最高 12 秒；Seedance 1.0 系列最高 12 秒 |
| 最高分辨率 | 1080p | 1080p | Seedance 2.0 标准版最高 4k；其他常用档位最高 1080p |
| 首帧约束 | 支持 | 支持 | 支持 |
| 尾帧约束 | 不支持 | `veo-3.1` 系列支持 | Seedance 2.0、1.5 Pro、1.0 Pro 支持 |
| 音频生成 | 不支持 | 支持 | Seedance 2.0 和 1.5 Pro 支持 |
| 多模态参考 | 不支持 | 部分支持 | Seedance 2.0 支持图片、视频、音频参考 |
## 注意事项
* 视频生成是异步任务，需要轮询查询状态。
* 不同模型的参数名称不同：Sora 使用 `aspect_ratio`，Veo 使用 `aspectRatio`，Seedance 在 `metadata` 中使用 `ratio`。
* Seedance 在 MixRoute 中除 `model`、`prompt`、`asset` 外，其他 Seedance 参数都应放入 `metadata`。
* Seedance 2.0 Fast 和 2.0 Mini 不支持 `1080p`；需要使用 `720p` 或其他受支持分辨率。
* `metadata.content` 中的音频不能单独输入，至少需要同时提供 1 个参考图片或视频。
* 生成的视频有一定有效期，建议任务成功后及时下载保存。
* 请遵守内容政策，避免生成违规内容。
```bash cURL theme={null}
curl --request POST \
--url https://api.mixroute.ai/v1/video/generations \
--header 'Authorization: Bearer sk-xxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "dreamina-seedance-2-0-fast-260128",
"prompt": "清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进",
"metadata": {
"content": [
{
"type": "text",
"text": "清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进"
}
],
"duration": 4,
"generate_audio": false,
"resolution": "720p",
"ratio": "16:9",
"watermark": false
},
"asset": true
}'
```
```python Python theme={null}
import requests
url = "https://api.mixroute.ai/v1/video/generations"
headers = {
"Authorization": "Bearer sk-xxxxxxxxxx",
"Content-Type": "application/json",
}
prompt = "清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进"
payload = {
"model": "dreamina-seedance-2-0-fast-260128",
"prompt": prompt,
"metadata": {
"content": [{"type": "text", "text": prompt}],
"duration": 4,
"generate_audio": False,
"resolution": "720p",
"ratio": "16:9",
"watermark": False,
},
"asset": True,
}
response = requests.post(url, json=payload, headers=headers, timeout=60)
print(response.json())
```
```javascript JavaScript theme={null}
const prompt = '清晨的木质桌面上，一只白色陶瓷杯被柔和阳光照亮，镜头缓慢推进';
const response = await fetch('https://api.mixroute.ai/v1/video/generations', {
method: 'POST',
headers: {
Authorization: 'Bearer sk-xxxxxxxxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'dreamina-seedance-2-0-fast-260128',
prompt,
metadata: {
content: [{ type: 'text', text: prompt }],
duration: 4,
generate_audio: false,
resolution: '720p',
ratio: '16:9',
watermark: false
},
asset: true
})
});
const data = await response.json();
console.log(data);
```
```json Response theme={null}
{
"id": "task_N6QRBeaX4ohVAiODaVKCu7LGH4fPEO3B",
"task_id": "task_N6QRBeaX4ohVAiODaVKCu7LGH4fPEO3B",
"object": "video",
"model": "dreamina-seedance-2-0-fast-260128",
"status": "queued",
"progress": 0,
"created_at": 1782556739
}
```