TokenLab

Video & Materials

Create Task (Volc Compatible)

Create a Seedance task with the Volc-compatible API.

POST
/api/v3/contents/generations/tasks

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" without role, or with role: "first_frame", is treated as the first frame.
  • role: "last_frame" must be paired with a first frame.
  • type: "video_url" requires role: "reference_video", and type: "audio_url" requires role: "reference_audio". role: "reference_image" marks a reference image.
  • Item limits: Seedance 2.0 accepts up to 16 content items (1 text, 9 image, 3 video, 3 audio, 1 draft_task). Seedance 2.5 accepts up to 51 (1 text, 30 image, 10 video, 10 audio, 1 draft_task).
  • image_url.url accepts a public image URL or a material URI such as asset://asset-YYYYMMDDHHMMSS-xxxxx. The role determines 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_id and material_asset_ids, returns 400 UnsupportedParameter. Put a TokenLab material URI in image_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:

ParameterSeedance 2.0Seedance 2.5
duration4–15 / -1 (default: 5)4–30 / -1 (default: -1)
resolution480p, 720p, 1080p (default: 720p)480p, 720p (default: 720p)
generate_audioboolean (default: false)boolean (default: true)
priorityNot supportedinteger: 0–9
seedinteger: -1–4294967295 (default: -1)Not supported
execution_expires_after3600–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.

  • ratio accepts 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive (default: adaptive).
  • watermark and return_last_frame are booleans (default: false). safety_identifier is a string of up to 64 characters.
  • service_tier accepts only default; flex returns 400 UnsupportedParameter.
  • tools accepts at most one item, {"type": "web_search"}.
  • draft: true, frames, and camera_fixed are not supported. camera_fixed: false is accepted for Seedance 2.0 only.
  • callback_url may 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 adds Idempotency-Replayed: true.
  • Reusing the key with a different body returns 409 with code idempotency_conflict and 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
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json