Media Guides
Video Generation
Create videos from text, images, audio, or existing clips
Video generation is asynchronous. POST /v1/videos/generations returns a task ID and usually a poll_url. Poll GET /v1/tasks/{id} with that ID until the finished video is ready.
Send public HTTP(S) URLs or supported data URLs in the image fields accepted by your selected model. These inputs follow the normal media path and do not automatically create reusable material IDs.
When an explicit material is still preparing, POST /v1/videos/generations returns 409 seedance_material_preparing with inactive_asset_ids. Poll those assets until ACTIVE, then retry with the same material IDs. If an asset is FAILED, inspect error_message and correct or reimport it before retrying.
Choose an API
Use /v1/videos/generations for a new video integration. Existing Seedance 2.0 clients that already send Volcengine content[] or Action requests can keep that format through /api/v3. Both APIs use a TokenLab Bearer key, but their fields and status values are different.
Choose what to create
Set operation explicitly so the API can validate the right fields for the job.
| Operation | Required or typical input | Use case |
|---|---|---|
text-to-video | prompt | Generate from text only |
image-to-video | image_url or compatible image | Animate a starting image |
reference-to-video | reference_images and optional video_urls / audio_urls on supported models | Keep identity, style, or asset references |
start-end-to-video | start_image, end_image | Control first and last frames |
video-to-video | video_url or model-specific task_id | Transform or upscale an existing clip |
motion-control | image_url plus video_url | Apply motion reference to a subject |
audio-to-video | audio_url | Audio-conditioned video flows |
video-extension | task_id, extend_at, or model-specific extension fields | Continue a generated video |
Choose a model
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"Use a model ID returned by TokenLab, then choose the generation type with operation and the corresponding media inputs. Do not use an operation name as the model ID.
Read the selected model detail before relying on specialized fields such as reference_images, kling_elements, output_audio, duration, resolution, or aspect_ratio.
Create a video
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'Use https URLs for media that can be fetched from the internet. Temporary URLs must stay valid until TokenLab creates the task.
Fix a rejected parameter
A 400 on POST /v1/videos/generations names the rejected field in param and lists the values that field accepts for the selected model, so the next request needs no guessing:
| Field | Meaning |
|---|---|
allowed_durations | duration or seconds values the model supports, in seconds |
allowed_resolutions | resolution values the model details list |
supported_operations | operation names the model details list |
recommended_request | One request that uses an allowed value; send it, or swap in another value from the same lists |
Those lists belong to the selected model. Read them from the error body or from the model detail (GET /v1/models/{id}); another model's values do not apply.
A request that sends seconds: 20 to a model that accepts 4, 6, and 8 seconds answers with param: "duration", allowed_durations: ["4", "6", "8"], and a recommended_request that keeps the prompt and sets duration to 4.
When the operation needs an input only you can supply, such as an image for image-to-video, the error leaves out recommended_request and names the missing inputs in required_selectors and in hint.
An invalid operation name is rejected before the model details are read; the same supported_operations list tells you which names to send instead. The allowed values are per operation, so keep sending operation while you correct duration or resolution.
Model-specific fields
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, andveo3.1-litealways generate audio. Omitoutput_audioor sendtrue;falseis rejected.wan-2.6andwan-2.7always include audio. Omitoutput_audioor sendtrue.wan-3.0andwan-3.0-primealso always include audio and take no audio selector.hailuo-h3generates native audio and has no mute switch. Do not send an audio selector that the model detail does not list.viduq3-proandviduq3-turbogenerate audio by default; sendoutput_audio: false(oraudio: false) for silent output. Seedance and PixVerse models takeoutput_audio; send it explicitly instead of relying on the default. Use it only for operations that list it.audio_url/audio_urlsprovide 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.
- For the Seedance 2.0 family, read the Seedance 2.0 video models guide before using 4K output, Fast/Mini resolution caps, or multimodal reference inputs.
- For
grok-imagine-videovideo-to-video, sendpromptand a public HTTPS.mp4video_url. A TokenLab.mp4result URL from an earlier task works. This operation does not useduration,resolution, oraspect_ratioselectors.
PixVerse and HappyHorse
| Model | Operations | Inputs | Resolution | Duration | Audio selector |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Any integer from 1 to 15 seconds | output_audio |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Same fields as C1 and V6 | 360p, 540p, 720p, 1080p | 5, 8, or 10 seconds; 1080p supports 5 or 8 seconds | output_audio |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 to 15 seconds for generation operations; video-to-video output is capped at 15 seconds | Do not send output_audio |
happyhorse-1.1 | text-to-video, image-to-video, reference-to-video | prompt; image_url; reference_images | 720p, 1080p | 3 to 15 seconds | Do not send output_audio |
On TokenLab, the PixVerse models above do not accept operation=video-extension.
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'Get the finished video
Call GET /v1/tasks/{id} with the id or task_id from the create response until the task is completed or failed.
Completed video tasks may return video_url, video, or videos depending on the model and output count. Treat billing_transaction_id as a billing identifier, not as a task identifier.
Video result URLs are TokenLab media-result URLs that end in the file type, such as .mp4, and stay valid for 30 days. media_retention.items reports each item's saving status and expires_at; the response can omit media_retention when the saving status is not known in time, and the URL still works. Failed and in-progress tasks return empty video URL fields. Async task snapshots have a separate lifecycle. See Data retention.
Common Pitfalls
- Do not use per-modality status paths such as
/v1/videos/generations/{id}in new code; pollGET /v1/tasks/{id}. - Do not combine first-frame fields with dedicated reference-image flows unless the model details allows it.
- Do not assume
durationdescribes input reference video length; it usually controls generated output length. - Send an
Idempotency-KeywithPOST /v1/videos/generations. After a timeout, send the same request with the same key to get the original task. Without a key, check whether a task was already created before you retry.
API Reference
| Topic | Reference |
|---|---|
| Create Video | Create Video |
| Get Video Status | Get Video Status |
| Get Task Status | Get Task Status |
| Cancel Task | Cancel Task |
| Billing & Pricing | Billing & Pricing |
Hailuo H3-Max generates 5–15-second videos at 480p or 768p from text, a first frame, or first and last frames. Its speed-focused workflow is useful for quickly turning a shot idea into a short clip.
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}