TokenLab

Video & Materials

Create Video

Start a video generation task

POST
/v1/videos/generations

Overview

Video generation is asynchronous. A successful create request returns a task id (the same value as task_id) and a poll_url. Call GET /v1/tasks/{id} with that ID until status is completed or failed, then read video_url. See Get Video Status.

  • The result file is saved for 30 days. Download it if you need it longer; see Data retention.
  • A queued Seedance task can be cancelled with Cancel Task.
  • Cost can be reserved when the task is accepted and is settled when the task finishes or fails. See Billing & Pricing.
  • Send an Idempotency-Key header to retry a create request safely after a timeout.

Each model accepts its own operations and fields. GET /v1/models/{model} (Get Model) lists, for every operation, the accepted fields, resolutions, durations, and aspect ratios. A field or value outside that list returns 400 with the accepted values. Set duration, resolution, aspect_ratio, and output_audio yourself: when you omit one, TokenLab uses the model's default for the operation, and if no default matches, the request returns 400 and names the field to set.

Audio and Media Input

Audio behavior depends on the selected model and operation. A video may contain sound even when no audio selector is exposed. Omitting a selector is different from sending false.

  • veo3.1, veo3.1-fast, and veo3.1-lite always generate audio. Omit output_audio or send true; false is rejected.
  • wan-2.6 and wan-2.7 always include audio. Omit output_audio or send true. wan-3.0 and wan-3.0-prime also always include audio and take no audio selector.
  • hailuo-h3 generates native audio and has no mute switch. Do not send an audio selector that the model detail does not list.
  • viduq3-pro and viduq3-turbo generate audio by default; send output_audio: false (or audio: false) for silent output. Seedance and PixVerse models take output_audio; send it explicitly instead of relying on the default. Use it only for operations that list it.
  • audio_url / audio_urls provide input or reference audio. They are not audio-output switches. Video editing, motion transfer, and style transfer may retain the input soundtrack; preserving source audio does not mean muting it.

Check the model detail for allowed values and audio-dependent prices. Where a model lists them, the aliases outputAudio, generate_audio, and boolean audio must agree with output_audio when combined. Do not assume every version or operation in a model family shares the same audio controls.

Use publicly reachable https URLs for images, videos, and audio, and keep them valid until the task starts. A media URL can be up to 8,192 characters. Some models also accept inline data: image URLs (up to 2,000,000 characters per field); URLs are more reliable for large files. Do not mix inline base64 and remote URLs in the same request.

Request Body

modelstringdefault: veo3.1

Video model ID. List current video models with List models (recommended_for=video), then send the model explicitly.

PixVerse

  • Model: pixverse-c1, pixverse-v6, pixverse-v5.6
  • Operations: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • Audio selector: output_audio

On TokenLab, the PixVerse models above do not accept operation=video-extension.

HappyHorse

  • Model: happyhorse-1.0, happyhorse-1.1
  • Operations: text-to-video, image-to-video, reference-to-video; happyhorse-1.0 also takes video-to-video
  • Audio selector: Do not send output_audio
promptstring

Text description of the video, up to 10,000 characters. Most operations need one; the model details say which do not.

operationstring

Generation mode: text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, or motion-control. Each model supports only some of them; the others return 400 unsupported_operation. If you omit it, TokenLab infers it from the inputs: a task_id with extend_at or extend_times gives video-extension, reference images or materials give reference-to-video, end_image gives start-end-to-video, a video input gives video-to-video, an image input (image, image_url, image_urls or start_image) gives image-to-video, and otherwise text-to-video. Send it explicitly so a mismatched field fails early.

image_urlstring

Publicly accessible URL of the first-frame image. Seedance 2.0 models also accept asset://asset-YYYYMMDDHHMMSS-xxxxx to use an ACTIVE TokenLab material as the first frame. Prefer an https URL for the widest model support.

imagestring

Inline image as a data URL (for example, data:image/jpeg;base64,...). Only some models accept it; image_url works on more.

image_urlsarray

Image URLs for models that list this field. See reference_images for the count limits.

reference_imagesarray

Reference images for reference-to-video, as https URLs or data URLs. The count limit depends on the model:

  • seedance-2.0, seedance-2.0-fast, and seedance-2.0-mini: up to 9 image references in total, including material assets. More returns 400 too_many_seedance_reference_images.
  • seedance-2.5: up to 30 image inputs in total across image_urls and reference_images.
  • grok-imagine-video: up to 7, and duration is capped at 10 seconds. grok-imagine-video-1.5 and grok-imagine-video-1.5-preview take no reference images.
  • Other models: see the model details. A request over the limit returns 400 too_many_items.

Seedance 2.0 models also accept asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material. For model selection, 4K boundaries, and Mini notes, see the Seedance 2.0 video models guide. For grok-imagine-video, do not combine reference images with image_url or image.

start_imagestring

First-frame image. With end_image, the request is start-end-to-video. Without end_image, it is image-to-video, and start_image works like image on models whose contract lists it. Accepts a public URL or a data URL; Seedance 2.0 models also accept asset://asset-YYYYMMDDHHMMSS-xxxxx.

end_imagestring

Last-frame image for start-end-to-video. Accepts the same inputs as start_image.

material_asset_idstring

TokenLab Seedance material asset ID returned by Create Material Asset. Accepted by the Seedance 2.0 models only; other models return 400 unsupported_seedance_material_asset_model. The asset must be ACTIVE and belong to your account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image meaning explicitly, put asset://<material_asset_id> in start_image, end_image, or reference_images instead.

material_asset_idsarray

Up to 9 TokenLab Seedance material asset IDs. They count toward the 9 image references of the Seedance 2.0 models.

Ordinary image URLs are passed as image inputs; they do not create reusable material assets. Create reusable assets through the material API, then use their TokenLab IDs or asset://asset-YYYYMMDDHHMMSS-xxxxx URIs. If an explicit material returns 409 seedance_material_preparing, check the returned inactive_asset_ids and retry after those materials become ACTIVE.

video_urlstring

Publicly accessible URL of the source video, for the operations that take one: video-to-video, video-extension, and motion-control, on models that list this field.

video_urlsarray

Source or reference videos for models that list this field. seedance-2.5 accepts up to 10 video inputs in total across video_url and video_urls. See the model details for other models.

audio_urlstring

Public audio URL for an audio reference or audio-driven operation, on models that list this field. It is an input, not an audio-output switch.

audio_urlsarray

Reference audio for models that list this field. seedance-2.5 accepts up to 10 audio inputs in total across audio_url and audio_urls and allows a request with audio references and no prompt. For seedance-2.5, reference audio plus reference video lasts at most 30 seconds combined.

task_idstring

ID of an earlier task in your workspace, for video-extension on models that list this field. A task that does not belong to your workspace returns 403 task_not_owned.

extend_atinteger

Second of the source video where a video-extension starts. Required by grok-imagine-video.

extend_timesstring

Seconds to add in a video-extension, on models that list this field. grok-imagine-video takes 6 or 10.

durationinteger

Output duration in seconds. The allowed values depend on the model and operation; other values return 400 invalid_duration. Seedance models also accept -1 to let the model choose within its range; billing is then estimated conservatively until the task finishes. Some operations take no duration, such as motion-control and grok-imagine-video video-to-video.

secondsinteger

Compatibility alias for duration. If both are sent, they must be identical.

aspect_ratiostring

Aspect ratio, for example 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive (Seedance). The allowed values depend on the model and operation; other values return 400 invalid_aspect_ratio.

resolutionstring

Output resolution, for example 480p, 720p, 1080p, or 4k. The allowed values depend on the model and operation, and some models also use 360p, 540p, or 768p. Other values return 400 invalid_resolution.

output_audioboolean

Audio-output selector for operations that list it. Omission follows the model default; false requests silent output only where the model allows it. See the audio notes above and the selected model details.

output_formatstring

Container format, mp4 or mov, for models that list this field, such as seedance-2.5. Omit it for models that do not list it.

return_last_frameboolean

Also return the last generated frame as last_frame_url. Seedance models only.

watermarkboolean

Watermark toggle for models that list this field (Seedance models).

negative_promptstring

What to avoid in the generated video, up to 5,000 characters, for models that list this field.

seedinteger

Seed for reproducible generation, for models that list this field. Seedance 2.0 models accept -1 for a random seed; seedance-2.5 does not accept this field.

fpsinteger

Frames per second (1-120), for models that list this field.

framesinteger

Frame count, for models that list this field. Seedance models do not accept it.

execution_expires_afterinteger

Seconds the task may wait in the queue before it expires (3600 to 259200), for Seedance models.

priorityinteger

Task priority from 0 to 9, for Seedance models. Do not combine it with service_tier=flex.

service_tierstring

default is accepted as a compatibility no-op on Seedance 2.0 and 2.5 models. flex is rejected on those models.

safety_identifierstring

End-user safety identifier (up to 128 characters), for Seedance models. If omitted, TokenLab uses user when provided.

toolsarray

Tools the model may use while generating, for Seedance 2.0 and 2.5 models. The supported tool is {"type": "web_search"}.

userstring

A unique identifier for the end-user. For Seedance models, TokenLab also uses it as safety_identifier when that field is omitted.

Compatible Field Names

  • Primary fields use snake_case: aspect_ratio, output_audio, and reference_images.
  • For compatibility, TokenLab also accepts ratio, generate_audio, outputAudio, seconds, and referenceImages.
  • If a primary field and its alias are both sent, their values must match. A mismatch returns 400 with conflicting_audio_selector, conflicting_duration, or conflicting_aspect_ratio.

Seedance Parameters

Seedance models (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, and seedance-2.5) take the TokenLab field names above and the aliases seconds, ratio, and generate_audio. The versions differ:

Seedance 2.0 modelsseedance-2.5
Resolutionseedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast and seedance-2.0-mini: 480p, 720p480p, 720p
Duration-1, 4 to 15 seconds-1, 4 to 30 seconds
Aspect ratio1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptiveSame for text-to-video and reference-to-video. Image-to-video, start-end, video editing, and extension need adaptive; video editing also needs duration=-1
Output formatmp4mp4 or mov
seedAcceptedNot accepted
Reference inputs9 image references including materials (materials are accepted only on these models)30 images, 10 videos, and 10 audio files in total

The model details are the current source for these values. Send duration, resolution, aspect_ratio, and output_audio explicitly instead of relying on a default; the model's recommended_request shows a typical request.

duration=-1 or seconds=-1 lets Seedance choose the output duration within the model's range. TokenLab estimates cost conservatively before the task finishes, then settles from the completed task's usage when it is available. service_tier=flex and frames are rejected on these models.

Seedance Example

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

Response

Fields describing results, errors, timestamps, and the model are returned when available for the task.

idstring

Task ID. Identical to task_id.

task_idstring

Task ID to poll with GET /v1/tasks/{id}.

poll_urlstring

Status URL for this task, /v1/tasks/{id}. Call it with your API key.

statusstring

Task status: pending, processing, completed, failed. A new task is normally pending.

createdinteger

Unix timestamp when the task was created.

modelstring

Model used.

billing_transaction_idstring

Billing transaction ID when settlement already completed. It is separate from the task ID.

video_urlstring

Video URL, present only when the create response already carries the result. Normally you read it from the status response.

errorstring | object

Error message or structured error object when the task fails.

Errors

Status and codeMeaning
400 invalid_requestA field is malformed, out of range, or missing. error.param names it. A message such as "Set aspect_ratio explicitly" means the omitted field has no default for this request.
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_longThe request does not match what the model accepts for the operation. The error usually lists the accepted values.
400 invalid_parameterAn input does not fit the operation, for example an image sent with text-to-video.
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratioAn alias and its primary field disagree.
400 unpriceable_selectionThe selected combination has no price. Change resolution, duration, aspect_ratio, or the audio setting.
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_modelToo many image references for a Seedance 2.0 model, or a material sent to another model.
402Insufficient balance.
403 task_not_ownedThe task_id belongs to another workspace.
409 seedance_material_preparing, seedance_material_route_unavailableA material is not ACTIVE yet, or the selected model cannot use the provided materials.
429Rate limit exceeded. See Rate limits.

Request

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Response

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

Image to Video

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

Reference to Video

Use operation=reference-to-video when the model supports dedicated reference conditioning. Image references go in reference_images; models that take reference videos and audio use video_urls and audio_urls. duration sets the generated output length only. It does not limit the length of reference video input. See reference_images above for the count limits per model.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Keyframe Control

Use start_image and end_image to control the first and last frames:

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p"
    }
)

Video to Video

Use operation=video-to-video when the model accepts an existing video as the primary input. For grok-imagine-video, send a public HTTPS .mp4 URL in video_url and the editing prompt, and omit resolution, duration, and aspect_ratio.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

Video Extension

Use operation=video-extension to continue an earlier result. Send the task_id of a task from your workspace and a prompt; the other fields depend on the model. grok-imagine-video also needs extend_at and takes extend_times of 6 or 10. veo3.1 and veo3.1-fast take task_id and prompt. Seedance models list video_url, video_urls, and task_id for this operation.

Motion Control

Use operation=motion-control when the model expects both a subject image and a motion reference video. Send image_url and video_url; resolution is required.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject identity stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

Model Discovery

Public video inventory and supported operations change over time. Use the Models API to check current support before you wire a model-specific flow:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

Read the model detail response before relying on model-specific operations or fields. Operations such as video-extension and motion-control are model-specific; confirm current availability there instead of relying on static examples in this page.

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

Optional key that makes a create request safe to retry. Send a new unique value, such as a UUID, for each task. A retry with the same key and the same body returns the result of the original create request, usually the original task, and does not create, dispatch, or charge a second task. A different body with a key that was already accepted is rejected with 409. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json