> ## 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 張參考圖片或 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 張參考圖片或 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
}
```