Skip to main content

​
Overview

These endpoints are for teams that already use the Volc-style Seedance task shape. They preserve the task-oriented request and response structure while using TokenLab authentication, billing, model availability, and task polling. 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 in this version. Requests with only AK/SK signing return a Volc-style authentication error.
  • Use the official task path: POST /api/v3/contents/generations/tasks.
  • Existing TokenLab Action aliases are retained only for backward compatibility. They are not part of the official wire-compatible task contract.

​
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.
  • role: "reference_image", reference_video, and reference_audio are used as references.
  • 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 official top-level fields. TokenLab-specific fields such as top-level material_asset_id, material_asset_ids, and priority are rejected. Put a TokenLab material URI inside the official image_url.url object instead.

​
Parameter Notes

  • ratio accepts 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive.
  • duration is the video length in seconds, including model-supported automatic duration values.
  • resolution accepts 480p, 720p, or 1080p.
  • generate_audio defaults to false; set it to true when synchronized audio is required.
  • watermark, return_last_frame, seed, execution_expires_after, and safety_identifier are accepted when valid for the selected model.
  • callback_url may point to a public HTTP(S) endpoint. TokenLab validates and stores it without forwarding it to the provider handling the task.

​
Callback Delivery

When callback_url is present, TokenLab sends an HTTP POST whenever task status changes. Callback statuses are queued, running, succeeded, failed, and expired. The JSON body is exactly the task object returned by the get-task endpoint, regardless of which provider handled the task. A 2xx response acknowledges delivery. For succeeded and failed, a delivery that does not succeed within five seconds is retried up to three times, matching the official behavior. 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. Callbacks are notifications. Keep polling available as a recovery path if your callback endpoint is unavailable for an extended period.

​
Image Preparation

When content[] contains image URLs, TokenLab prepares them as reusable materials when required by the selected Seedance model. If preparation is not complete within 60 seconds, the create request returns a retryable material-preparing error instead of submitting an incomplete video task. 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

The create response contains only the compatibility task ID. Store it and poll the task endpoint, even when callback delivery is enabled, so you retain a recovery path.

​
Idempotent Retries And Lost Responses

For production creates, send a unique Idempotency-Key header and persist it with the exact JSON request body. If the connection closes before you receive the create response, retry the same REST request with the same TokenLab API credential, key, and unchanged body:
  • If the original task was created, TokenLab returns the same cgt-... ID and adds Idempotency-Replayed: true.
  • If the original request is still being registered, TokenLab returns 409 IdempotencyRequestInProgress with Retry-After; retry the same key and body after that delay.
  • Reusing the key with a different body returns 409 IdempotencyConflict and never creates a second task.
Idempotency applies to the official v3 REST create path. It does not change the JSON response shape, and it is not inferred from X-Request-ID or from identical request bodies without a key.

​
Example

​
REST Create

For existing materials, put each URI in the official content[] item and declare its role:

​
Next Step

Use the returned cgt-... ID with Get Task (Volc Compatible) until the task reaches a terminal status.