Skip to main content
If your application already uses the Volcengine Seedance API, you can keep its REST paths, content[] body, response fields, callbacks, and PascalCase material Actions. Change the API host and replace AK/SK signing with a TokenLab API key.

​
What Changes

Requests signed only with AK/SK return 401 AuthenticationError. Every TokenLab request must include Authorization: Bearer <TOKENLAB_API_KEY>.

​
Choose an endpoint

For video tasks, keep the existing REST method, path, and JSON body. Material and verification requests continue to use Action and Version query parameters.

​
Official Task Paths

REST clients can use these equivalent references:

​
Request Body Rules

  • content[] accepts text, image_url, video_url, audio_url, and draft_task items.
  • For image_url, omit role or use first_frame for image-to-video. Use last_frame together with a first frame, or reference_image for reference-to-video.
  • A public material URI such as asset://asset-YYYYMMDDHHMMSS-xxxxx can be used where the selected Seedance workflow accepts that media role.
  • The REST body accepts only official fields, including model, content, ratio, duration, resolution, generate_audio, watermark, return_last_frame, seed, execution_expires_after, and safety_identifier. generate_audio defaults to false.
  • callback_url accepts a public HTTP(S) endpoint. TokenLab sends the same query-task body for queued, running, succeeded, failed, and expired; only succeeded and failed use the official five-second, three-retry behavior.

​
Minimal REST Example

Store the returned cgt-... ID. Poll until status becomes succeeded, failed, cancelled, or expired; do not treat the create response as a completed video. If you provide callback_url, allow repeated succeeded or failed notifications and keep polling as a recovery path.

​
Keep v1 And v3 Types Separate

Do not reuse a /v1/tasks/{id} response struct for this endpoint. The unified v1 API reports pending, processing, completed, and failed; the Volc-compatible v3 API reports queued, running, succeeded, failed, cancelled, and expired. The official v3 response also represents duration as a JSON string and omits error on non-failed tasks. For safe recovery after a create timeout or disconnect, add a unique Idempotency-Key to the REST create request. Retrying the same body with the same key returns the original cgt-... ID; the same key with a different body returns 409.

​
Materials And Real-Person Verification

The same Action endpoint also supports the 10 material and material-group operations. See Material Actions (Volc Compatible) for their exact PascalCase bodies, filters, paging, response envelope, and 12-hour material URLs. Real-person materials add two Actions before upload:
  1. Create Visual Validation Session
  2. Get Visual Validation Result
The second Action returns the verified GroupId. Use that ID with CreateAsset; a client cannot create a LivenessFace group directly.

​
Migration Checklist

  1. Replace the API host with https://api.tokenlab.sh.
  2. Replace AK/SK signing with a TokenLab Bearer API key.
  3. Keep the official REST task method, path, and request-body casing; keep Action and version only for material or validation operations.
  4. Keep the same ProjectName across related material and verification requests.
  5. Store the TokenLab task, group, and asset IDs returned by these endpoints.
  6. Verify one create, poll, list, and error response before moving production traffic.