Video & Materials
Create Task (Volc Compatible)
Create a Seedance task with the Volc-compatible API.
Overview
Existing Volc-style Seedance clients can use TokenLab by changing the API address and key.
The examples use Seedance 2.0. This endpoint also supports Seedance 2.5 with the model-specific differences below. The reusable TokenLab material URI examples on this page apply to Seedance 2.0.
See also Seedance 2.0 Video Models and Video Generation.
Authentication And Endpoints
- Use
Authorization: Bearer <TOKENLAB_API_KEY>. - Volc AK/SK signing is not accepted. Requests must include a TokenLab Bearer key.
- Use the official task path:
POST /api/v3/contents/generations/tasks.
Content Rules
type: "text"is the prompt text.type: "image_url"withoutrole, or withrole: "first_frame", is treated as the first frame.role: "last_frame"must be paired with a first frame.type: "video_url"requiresrole: "reference_video", andtype: "audio_url"requiresrole: "reference_audio".role: "reference_image"marks a reference image.- Item limits: Seedance 2.0 accepts up to 16
contentitems (1 text, 9 image, 3 video, 3 audio, 1draft_task). Seedance 2.5 accepts up to 51 (1 text, 30 image, 10 video, 10 audio, 1draft_task). image_url.urlaccepts a public image URL or a material URI such asasset://asset-YYYYMMDDHHMMSS-xxxxx. Theroledetermines whether that material is a first frame, last frame, or reference image.- Do not mix first/last frame inputs with reference media in one request.
- The REST body accepts only the fields on this page. Any other top-level field, including
material_asset_idandmaterial_asset_ids, returns400 UnsupportedParameter. Put a TokenLab material URI inimage_url.url.
Parameter Notes
model accepts a TokenLab model ID such as seedance-2.0 or seedance-2.5. Existing clients can keep sending the Volcengine model ID they already use for these models. The get-task response returns the model value you sent. An unrecognized value returns 400 InvalidParameter.
duration is an integer number of seconds; -1 selects automatic duration. Defaults and limits differ by model:
| Parameter | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (default: 5) | 4–30 / -1 (default: -1) |
resolution | 480p, 720p, 1080p (default: 720p) | 480p, 720p (default: 720p) |
generate_audio | boolean (default: false) | boolean (default: true) |
priority | Not supported | integer: 0–9 |
seed | integer: -1–4294967295 (default: -1) | Not supported |
execution_expires_after | 3600–259200 seconds (default: 172800) | 3600–259200 seconds (default: 172800) |
For Seedance 2.5, first-frame, first/last-frame, video extension, and video-to-video requests require ratio: "adaptive"; video-to-video also requires duration: -1. output_format accepts mp4 or mov only for Seedance 2.5.
ratioaccepts16:9,4:3,1:1,3:4,9:16,21:9, oradaptive(default:adaptive).watermarkandreturn_last_frameare booleans (default:false).safety_identifieris a string of up to 64 characters.service_tieraccepts onlydefault;flexreturns400 UnsupportedParameter.toolsaccepts at most one item,{"type": "web_search"}.draft: true,frames, andcamera_fixedare not supported.camera_fixed: falseis accepted for Seedance 2.0 only.callback_urlmay point to a public HTTP(S) endpoint of up to 2,048 characters.
Callback Delivery
When callback_url is present, TokenLab sends an HTTP POST when task status changes. Callback statuses are queued, running, succeeded, failed, and expired. The JSON body matches the get-task response.
A 2xx response acknowledges delivery. For succeeded and failed, a delivery that does not succeed within five seconds is retried up to three times. The callback has only the standard JSON content header and no TokenLab-specific delivery headers. Redirects are not followed, and private or reserved network targets are rejected.
Save the task ID. If a callback is not delivered, you can still retrieve the result with the get-task endpoint.
Image Preparation
Public HTTP(S) image URLs and supported data URLs are used as supplied; they are not automatically saved as reusable materials. Explicit asset://asset-... references use existing TokenLab materials. TokenLab checks ownership and readiness before generation. If a referenced material is still preparing, wait until it is ready and retry; inspect error.code and error.message when creation fails.
For existing materials, use the public asset-YYYYMMDDHHMMSS-xxxxx ID rather than an original asset ID returned by another system. TokenLab verifies material ownership before generation.
Create Response
{
"id": "cgt-20260102030405-a1b2c"
}The create response contains only the task ID. Save it so you can retrieve status and results at any time.
Prevent Duplicate Tasks
Send a unique Idempotency-Key (1–255 characters, no line breaks) with create requests. If the connection closes before the response arrives, retry with the same API key, idempotency key, and request body:
- If the original task was created, TokenLab returns the same
cgt-...ID and addsIdempotency-Replayed: true. - Reusing the key with a different body returns
409with codeidempotency_conflictand never creates a second task. - A key that is longer than 255 characters or contains line breaks returns
400 InvalidParameter.
The key does not change the JSON response shape. TokenLab does not infer duplicates from X-Request-ID or from identical request bodies without a key.
Example
REST Create
curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Idempotency-Key: $CLIENT_JOB_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"content": [
{"type": "text", "text": "A cinematic forest at sunset"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p",
"generate_audio": false,
"callback_url": "https://example.com/webhooks/seedance"
}'For existing materials, put each URI in the official content[] item and declare its role:
[
{
"type": "image_url",
"role": "first_frame",
"image_url": {"url": "asset://asset-20260720123458-start"}
},
{
"type": "image_url",
"role": "last_frame",
"image_url": {"url": "asset://asset-20260720123459-end01"}
}
]Errors
REST errors use {"error": {"code", "message", "param", "type"}}. Request problems return 400 with InvalidParameter or UnsupportedParameter, and a missing Bearer key returns 401 AuthenticationError. Errors from video generation, such as insufficient balance (402) or a rate limit (429), keep their HTTP status.
The same operations are also available as the Actions CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks, and DeleteContentsGenerationsTasks on POST /api/v3?Version=2024-01-01. New integrations should use the REST paths above.
Next Step
Use the returned cgt-... ID with Get Task (Volc Compatible) until the task reaches a terminal status.
curl -X POST "https://example.com/api/v3/contents/generations/tasks" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.0", "content": [ { "type": "text", "text": "A cinematic forest at sunset" }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/ref.png" } } ], "ratio": "16:9", "duration": 5, "resolution": "720p", "generate_audio": false }'{ "id": "string"}Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.
Value in
- "auto"
- "verified"
- "official"
Client-generated key for idempotent REST task creation, 1-255 characters without line breaks. Under the same TokenLab API credential, reusing the same key with the same JSON body returns the original cgt task ID; reusing it with a different body returns 409 with code idempotency_conflict. A key that is too long or contains line breaks returns 400. Keep the credential, key, and request body unchanged when retrying after a timeout or disconnect.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json