Seedance 2.0 (Text-to-Video) generates Hollywood-grade cinematic videos from text prompts with native audio-visual synchronization, director-level camera and lighting control, and exceptional motion stability. Built on Seed's unified multimodal architecture, it leads on instruction adherence, motion quality, and visual aesthetics.
Integration Steps
Asynchronous Polling1.8s for up to 180s.succeeded / failed / cancelled.output_payload.assets[] URLs.Step 1 · Create Request
Submit generation input. Choose a backend language example below.
curl -X POST https://api.openoctopus.com/v1/videos/generations \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer ooq_your_api_key" \\
-d '{
"model": "openoctopus/bytedance/seedance-2.0/text-to-video",
"prompt": "a cinematic octopus swimming through a neon underwater city",
"input": {
"reference_images": ["https://example.com/reference-image.png"],
"duration": 5,
"reference_videos": ["https://example.com/reference-video.mp4"],
"reference_audios": ["https://example.com/reference-audio.mp3"],
"resolution": "720p"
}
}'Poll Task Status
Use the task ID from create response to poll execution status.
curl https://api.openoctopus.com/v1/tasks/task_id_from_previous_response \
-H "Authorization: Bearer ooq_your_api_key"const timeoutMs = 180000;
const intervalMs = 1800;
const startedAt = Date.now();
while (Date.now() - startedAt < timeoutMs) {
const r = await fetch("https://api.openoctopus.com/v1/tasks/task_id_from_previous_response", {
headers: { Authorization: "Bearer " + process.env.OPENOCTOPUS_API_KEY },
});
const task = await r.json();
if (!r.ok) throw new Error(task?.error?.message ?? "task query failed");
if (task.status === "queued" || task.status === "processing") {
await new Promise((resolve) => setTimeout(resolve, intervalMs));
continue;
}
if (task.status === "succeeded") {
console.log(task.output_payload);
break;
}
throw new Error(task?.error_message ?? "task failed");
}import time, requests
timeout_s = 180
interval_s = 1.8
started = time.time()
while time.time() - started < timeout_s:
resp = requests.get(
"https://api.openoctopus.com/v1/tasks/task_id_from_previous_response",
headers={"Authorization": f"Bearer {OPENOCTOPUS_API_KEY}"},
timeout=30,
)
task = resp.json()
if resp.status_code >= 400:
raise RuntimeError(task.get("error", {}).get("message", "task query failed"))
status = task.get("status")
if status in ("queued", "processing"):
time.sleep(interval_s)
continue
if status == "succeeded":
print(task.get("output_payload"))
break
raise RuntimeError(task.get("error_message", "task failed"))Input Schema (Standard + Provider Extension)
Standard request contract merged with this model's upstream input parameters.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| reference_images | array of string | No | Reference image URLs to guide visual style, characters, or scene composition. | - |
| reference_videos | array of string | No | Reference video URLs (total length must not exceed 15 seconds). | - |
| reference_audios | array of string | No | Reference audio URLs (total length must not exceed 15 seconds). | - |
| aspect_ratio | string | No | The aspect ratio of the generated video. Default: "16:9". Options: "16:9", "9:16", "4:3", "3:4", "1:1", "21:9" | 16:9 |
| resolution | string | No | The output video resolution. Default: "720p". Options: "480p", "720p", "1080p" | 720p |
| duration | integer | No | The duration of the generated video in seconds (4-15s). Default: 5. Range: 4 to 15 | 5 |
| enable_web_search | boolean | No | Enable web search for real-time information. Default: false | false |
| generate_audio | boolean | No | Whether to generate native audio synchronized with the output video. Defaults to true. | true |
{
"standard": {
"model": "public model slug (required)",
"prompt": "user prompt (required)",
"input": "provider-specific options (optional object)"
},
"providerExtension": {
"params": [
{
"name": "reference_images",
"type": "array of string",
"maxItems": 9,
"required": false,
"description": "Reference image URLs to guide visual style, characters, or scene composition.",
"exposedToCustomer": true
},
{
"name": "reference_videos",
"type": "array of string",
"maxItems": 3,
"required": false,
"description": "Reference video URLs (total length must not exceed 15 seconds).",
"exposedToCustomer": true
},
{
"name": "reference_audios",
"type": "array of string",
"maxItems": 3,
"required": false,
"description": "Reference audio URLs (total length must not exceed 15 seconds).",
"exposedToCustomer": true
},
{
"name": "aspect_ratio",
"type": "string",
"example": "16:9",
"required": false,
"description": "The aspect ratio of the generated video. Default: \"16:9\". Options: \"16:9\", \"9:16\", \"4:3\", \"3:4\", \"1:1\", \"21:9\"",
"exposedToCustomer": true
},
{
"enum": [
"480p",
"720p",
"1080p",
"1440p",
"2160p",
"0.5k",
"1k",
"2k",
"3k",
"4k"
],
"name": "resolution",
"type": "string",
"example": "720p",
"required": false,
"description": "The output video resolution. Default: \"720p\". Options: \"480p\", \"720p\", \"1080p\"",
"exposedToCustomer": true
},
{
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15"
],
"name": "duration",
"step": 1,
"type": "integer",
"example": "5",
"maximum": 60,
"minimum": 1,
"required": false,
"description": "The duration of the generated video in seconds (4-15s). Default: 5. Range: 4 to 15",
"exposedToCustomer": true
},
{
"name": "enable_web_search",
"type": "boolean",
"example": "false",
"required": false,
"description": "Enable web search for real-time information. Default: false",
"exposedToCustomer": true
},
{
"name": "generate_audio",
"type": "boolean",
"example": "true",
"required": false,
"description": "Whether to generate native audio synchronized with the output video. Defaults to true.",
"exposedToCustomer": true
}
]
}
}Output Schema (Standard + Provider Extension)
Standard output contract merged with provider extension fields.
Note: integrate against output_payload.assets[]. raw is optional and may be omitted by endpoint policy.
| Field | Type | Exposed | Description | Example |
|---|---|---|---|---|
| outputs | array of object | Yes | Array of URLs to the generated content (empty when status is not completed). | - |
| status | string | Yes | Status of the task: created, processing, completed, or failed. | - |
| urls | object | Yes | Object containing related API endpoints. | [object Object] |
| created_at | string (date-time) | Yes | ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z"). | - |
| has_nsfw_contents | array of boolean | Yes | Array of boolean values indicating NSFW detection for each output. | - |
| id | string | Yes | Unique identifier for the prediction, the ID of the prediction to get. | - |
| model | string | Yes | Model ID used for the prediction. | - |
{
"standard": {
"id": "task id",
"status": "queued | processing | succeeded | failed | cancelled",
"queue": {
"enabled": "whether OpenOctopus local queue is enabled for this model",
"position": "1-based queue position while queued, 0 while processing, null when unavailable",
"size": "current queued request count for this model",
"concurrency": "local concurrent upstream submissions allowed for this model",
"upstreamQueueSupported": "whether the upstream provider has a reliable queue",
"upstreamCancelSupported": "whether the upstream provider supports cancellation"
},
"asset_storage": {
"provider": "supabase | aliyun-oss | tencent-cos",
"inputBucket": "bucket used for uploaded reference media",
"outputBucket": "bucket used for generated media",
"custom": "true when this model overrides default system asset storage"
},
"capability": "image_generation | video_generation",
"output_payload": {
"format": "openoctopus.image.output.v1 | openoctopus.video.output.v1",
"assets": "normalized output assets",
"raw": "optional sanitized debug payload (may be omitted depending on endpoint policy)"
}
},
"providerExtension": {
"fields": [
{
"name": "outputs",
"type": "array of object",
"description": "Array of URLs to the generated content (empty when status is not completed).",
"exposedToCustomer": true
},
{
"name": "status",
"type": "string",
"description": "Status of the task: created, processing, completed, or failed.",
"exposedToCustomer": true
},
{
"name": "urls",
"type": "object",
"example": "[object Object]",
"description": "Object containing related API endpoints.",
"exposedToCustomer": true
},
{
"name": "created_at",
"type": "string (date-time)",
"description": "ISO timestamp of when the request was created (e.g., \"2023-04-01T12:34:56.789Z\").",
"exposedToCustomer": true
},
{
"name": "has_nsfw_contents",
"type": "array of boolean",
"description": "Array of boolean values indicating NSFW detection for each output.",
"exposedToCustomer": true
},
{
"name": "id",
"type": "string",
"description": "Unique identifier for the prediction, the ID of the prediction to get.",
"exposedToCustomer": true
},
{
"name": "model",
"type": "string",
"description": "Model ID used for the prediction.",
"exposedToCustomer": true
}
]
}
}Step 4 · Error Handling Guide
Error codes below are loaded from internal gateway error definitions and should be treated as source of truth.
| Code | HTTP | Retryable | Category | Message |
|---|---|---|---|---|
| invalid_request | 400 | No | validation | The request payload is invalid. Check the required fields and try again. |
| unauthorized | 401 | No | auth | Authentication is required for this request. |
| invalid_api_key | 401 | No | auth | The API key is invalid or inactive. |
| insufficient_balance | 402 | No | billing | Your wallet balance is insufficient. Please top up and try again. |
| model_not_available | 404 | No | routing | The requested model is currently unavailable. |
| task_not_found | 404 | No | task | The requested task could not be found. |
| file_not_found | 404 | No | asset | The requested generated file is not available. |
| provider_offline | 503 | Yes | upstream | The selected model is temporarily unavailable. Please retry later. |
| provider_model_inactive | 503 | Yes | routing | The selected model is temporarily unavailable. Please retry later. |
| provider_credential_missing | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| provider_credential_incomplete | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| provider_credential_unusable | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| provider_credential_legacy | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| provider_credential_unavailable | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| provider_credential_decrypt_failed | 503 | Yes | system | The service is temporarily unavailable for this model. Please retry later. |
| model_billing_not_configured | 503 | No | system | The selected model is temporarily unavailable. Please retry later. |
| provider_pricing_not_configured | 503 | No | system | The selected model is temporarily unavailable. Please retry later. |
| database_operation_failed | 503 | Yes | system | The service could not access required internal records. Please retry later. |
| billing_resolution_failed | 503 | Yes | system | The selected model pricing could not be evaluated. Please retry later. |
| request_record_write_failed | 503 | Yes | system | The request could not be recorded internally. Please retry later. |
| api_key_touch_failed | 503 | Yes | system | The request was accepted but internal key tracking failed. Please retry later. |
| queue_unavailable | 503 | Yes | system | The internal job queue is temporarily unavailable. Please retry later. |
| provider_submit_failed | 502 | Yes | upstream | The generation provider could not accept the request. Please retry shortly. |
| provider_poll_failed | 502 | Yes | upstream | The generation provider could not complete the request. Please retry shortly. |
| upstream_failed | 502 | Yes | upstream | The generation provider failed to complete the request. Please retry shortly. |
| content_policy_violation | 400 | No | safety | The prompt or image was rejected by the provider safety policy. Please adjust the content and try again. |
| upstream_timeout | 504 | Yes | upstream | The generation request timed out. Please retry shortly. |
| upstream_result_missing | 502 | Yes | upstream | The generation provider returned an incomplete result. Please retry shortly. |
| video_output_missing | 502 | Yes | upstream | The generation provider returned an incomplete result. Please retry shortly. |
| service_unavailable | 503 | Yes | system | The service is temporarily unavailable. Please retry later. |
| internal_error | 500 | Yes | system | The service encountered an unexpected error. Please retry later. |
task.status=failed, always read error.code and match the table above; retry only when retryable=true.