> ## 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.
# Submit Video Task
> Submit a video generation task with models such as Sora 2, Veo, and Dreamina Seedance
## Introduction
The video task submission endpoint creates asynchronous video generation tasks. MixRoute provides one unified entry point for video models such as Sora 2, Veo, and Dreamina Seedance.
Video generation is asynchronous. After submitting a task, poll the task status with the task ID, then retrieve the video result after the task succeeds.
## API Base URL
```text theme={null}
https://api.mixroute.ai/v1
```
## Authentication
Use a Bearer Token:
```http theme={null}
Authorization: Bearer sk-xxxxxxxxxx
```
## Workflow
1. **Submit a task**: `POST /v1/video/generations`
2. **Poll the status**: `GET /v1/video/generations/{task_id}`
3. **Retrieve the result**: after the task succeeds, get the video URL or result object from the query endpoint response
## Supported Models
| Model ID | Provider | Description |
| ----------------------------------- | --------- | ----------------------------- |
| `sora-2` | OpenAI | Sora 2 video generation model |
| `veo-3.0-fast-generate-001` | Google | Veo 3.0 fast model |
| `veo-3.1-fast-generate-preview` | Google | Veo 3.1 fast model |
| `veo-3.0-generate-preview` | Google | Veo 3.0 standard model |
| `veo-3.1-generate-preview` | Google | Veo 3.1 standard model |
| `dreamina-seedance-2-0-260128` | ByteDance | Dreamina Seedance 2.0 |
| `dreamina-seedance-2-0-fast-260128` | ByteDance | Dreamina Seedance 2.0 Fast |
| `dreamina-seedance-2-0-mini-260615` | ByteDance | Dreamina Seedance 2.0 Mini |
| `seedance-1-5-pro-251215` | ByteDance | Seedance 1.5 Pro |
| `seedance-1-0-pro-250528` | ByteDance | Seedance 1.0 Pro |
| `seedance-1-0-pro-fast-251015` | ByteDance | Seedance 1.0 Pro Fast |
Pass the full model ID exactly as shown in the table. Do not use shortened aliases such as `seedance-1.0`, `seedance-1.0-pro`, or `seedance-1.5-pro`.
***
## Request Body
Parameter names differ by model. `model` and `prompt` are top-level request fields. Pass all other parameters according to the selected model.
### Common Fields
The model ID to call.
The video description prompt.
### Sora 2 Parameters
Video duration in seconds: `5`, `10`, `15`, or `20`. Defaults to `5`.
Resolution: `480p`, `720p`, or `1080p`. Defaults to `720p`.
Aspect ratio: `16:9`, `9:16`, or `1:1`. Defaults to `16:9`.
Reference image URL for image-to-video mode.
Source video URL for Remix mode.
### Veo Parameters
Video duration in seconds: `4`, `6`, or `8`.
Aspect ratio: `16:9` or `9:16`.
Resolution: `720p` or `1080p`.
First-frame reference image, as an image URL or Base64 string.
Last-frame reference image. Supported only by the `veo-3.1` series.
Whether to generate synchronized audio. Defaults to `false`.
### Dreamina Seedance Parameters
When calling Seedance through MixRoute, only `model`, `prompt`, and `asset` are placed at the top level of the JSON body. Official Seedance parameters such as `content`, `duration`, `generate_audio`, `resolution`, `ratio`, and `watermark` are placed inside the `metadata` object.
Seedance on MixRoute uses `metadata.ratio`, not `aspect_ratio`; it uses `metadata.content` to describe text, image, video, and audio inputs. Do not use top-level `first_frame`, `last_frame`, or `reference_image`.
Whether to enable the human asset library or authorized asset capability. Set this to `true` when using the asset library, virtual human assets, or authorized real-person assets.
The container for official Seedance parameters. Except for `model`, `prompt`, and `asset`, all Seedance parameters go inside this object.
The content array passed to Seedance. It is recommended to always include one `text` object whose text matches the top-level `prompt`.
Video duration in seconds. Seedance 1.0 Pro / 1.0 Pro Fast supports `[2, 12]`; Seedance 1.5 Pro supports `[4, 12]` or `-1`; Seedance 2.0 series supports `[4, 15]` or `-1`. `-1` lets the model automatically choose an appropriate duration.
Whether to generate audio synchronized with the visuals. Supported by Seedance 2.0 series and Seedance 1.5 Pro. Defaults to `true`.
Resolution: `480p`, `720p`, `1080p`, or `4k`. Seedance 2.0 Fast and 2.0 Mini do not support `1080p`; `4k` is supported only by the standard Seedance 2.0 model.
Aspect ratio: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, or `adaptive`. Seedance 2.0 series and Seedance 1.5 Pro default to `adaptive`.
Whether to add an `AI generated` watermark in the lower-right corner of the generated video. Defaults to `false`.
#### metadata.content Types
| Type | Structure | role | Description |
| ---------- | --------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Text | `{ "type": "text", "text": "..." }` | None | Text-to-video, or text used together with media inputs |
| Image | `{ "type": "image_url", "image_url": { "url": "..." } }` | `first_frame`, `last_frame`, `reference_image` | First frame, last frame, or reference image |
| Video | `{ "type": "video_url", "video_url": { "url": "..." } }` | `reference_video` | Supported only by Seedance 2.0 series |
| Audio | `{ "type": "audio_url", "audio_url": { "url": "..." } }` | `reference_audio` | Supported only by Seedance 2.0 series. Audio cannot be the only input; provide at least one reference image or video |
| Draft task | `{ "type": "draft_task", "draft_task": { "id": "..." } }` | None | Supported only by Seedance 1.5 Pro |
Images and audio can use public URLs, Base64 strings, or asset IDs. Videos can use public URLs or asset IDs. Asset IDs use the format `asset://`.
#### Seedance Capability Constraints
| Scenario | Supported models | Requirements |
| -------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Text-to-video | All Seedance models | `metadata.content` must contain at least one `text` object |
| Image-to-video - first frame | All Seedance models | Pass one `image_url`; `role` may be `first_frame` or omitted |
| Image-to-video - first and last frames | Seedance 2.0 series, Seedance 1.5 Pro, Seedance 1.0 Pro | Pass two `image_url` objects and set their `role` values to `first_frame` and `last_frame` |
| Multimodal reference-to-video | Seedance 2.0 series | You can pass 0-9 reference images, 0-3 reference videos, and 0-3 reference audio clips; audio cannot be the only input |
***
## Examples
```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": "A golden retriever runs on a sunny beach, slow-motion shot",
"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": "Morning sunlight falls across the towers of a cyberpunk city as the camera slowly pushes forward",
"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": "A white ceramic cup on a wooden desk in soft morning light, slow camera push-in",
"metadata": {
"content": [
{
"type": "text",
"text": "A white ceramic cup on a wooden desk in soft morning light, slow camera push-in"
}
],
"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": "The person slowly turns their head and smiles, while the background stays softly blurred",
"metadata": {
"content": [
{
"type": "text",
"text": "The person slowly turns their head and smiles, while the background stays softly blurred"
},
{
"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": "A car smoothly accelerates from a standstill into the distance, tracked from a low camera angle",
"metadata": {
"content": [
{
"type": "text",
"text": "A car smoothly accelerates from a standstill into the distance, tracked from a low camera angle"
},
{
"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": "Use the first-person POV composition from Video 1 and use Audio 1 as the background music throughout. Create a fruit tea ad, start with Image 1, and freeze on Image 2 at the end.",
"metadata": {
"content": [
{
"type": "text",
"text": "Use the first-person POV composition from Video 1 and use Audio 1 as the background music throughout. Create a fruit tea ad, start with Image 1, and freeze on Image 2 at the end."
},
{
"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
}'
```
***
## Response Examples
### Task Submission Response
```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
}
```
### Task Query Response
```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
}
}
}
```
Status fields can vary by model and upstream platform. Clients should handle `queued`, `running`, `succeeded`, `failed`, `expired`, and upstream status values returned by the query endpoint, such as `NOT_START` and `SUCCESS`. After success, the video URL is usually available from the outer `data.result_url` field or the nested `data.data.content.video_url` field.
***
## Python Example
```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(
"A white ceramic cup on a wooden desk in soft morning light, slow camera push-in"
)
print(f"Task submitted: {task_id}")
print(wait_for_task(task_id))
```
***
## Model Comparison
| Feature | Sora 2 | Veo | Dreamina Seedance |
| ---------------------- | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Maximum duration | 20 seconds | 8 seconds | Seedance 2.0 up to 15 seconds; Seedance 1.5 Pro up to 12 seconds; Seedance 1.0 series up to 12 seconds |
| Maximum resolution | 1080p | 1080p | Standard Seedance 2.0 up to 4k; other common variants up to 1080p |
| First-frame constraint | Supported | Supported | Supported |
| Last-frame constraint | Not supported | Supported by the `veo-3.1` series | Supported by Seedance 2.0, 1.5 Pro, and 1.0 Pro |
| Audio generation | Not supported | Supported | Supported by Seedance 2.0 and 1.5 Pro |
| Multimodal reference | Not supported | Partially supported | Seedance 2.0 supports image, video, and audio references |
## Notes
* Video generation is asynchronous and requires polling for status.
* Parameter names differ by model: Sora uses `aspect_ratio`, Veo uses `aspectRatio`, and Seedance uses `ratio` inside `metadata`.
* For Seedance on MixRoute, all Seedance parameters except `model`, `prompt`, and `asset` should be placed inside `metadata`.
* Seedance 2.0 Fast and 2.0 Mini do not support `1080p`; use `720p` or another supported resolution.
* Audio in `metadata.content` cannot be the only input. Provide at least one reference image or video together with the audio.
* Generated videos have a limited retention period. Download and store them promptly after the task succeeds.
* Follow the content policy and avoid generating prohibited content.
```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": "A white ceramic cup on a wooden desk in soft morning light, slow camera push-in",
"metadata": {
"content": [
{
"type": "text",
"text": "A white ceramic cup on a wooden desk in soft morning light, slow camera push-in"
}
],
"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 = "A white ceramic cup on a wooden desk in soft morning light, slow camera push-in"
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 = 'A white ceramic cup on a wooden desk in soft morning light, slow camera push-in';
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
}
```