Video & Materials
Create Video
Start a video generation task
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-Keyheader 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, 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.
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
veo3.1Video 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.0also takesvideo-to-video - Audio selector: Do not send
output_audio
Text description of the video, up to 10,000 characters. Most operations need one; the model details say which do not.
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.
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.
Inline image as a data URL (for example, data:image/jpeg;base64,...). Only some models accept it; image_url works on more.
Image URLs for models that list this field. See reference_images for the count limits.
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, andseedance-2.0-mini: up to 9 image references in total, including material assets. More returns400 too_many_seedance_reference_images.seedance-2.5: up to 30 image inputs in total acrossimage_urlsandreference_images.grok-imagine-video: up to 7, anddurationis capped at 10 seconds.grok-imagine-video-1.5andgrok-imagine-video-1.5-previewtake 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.
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.
Last-frame image for start-end-to-video. Accepts the same inputs as start_image.
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.
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.
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.
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.
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.
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.
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.
Second of the source video where a video-extension starts. Required by grok-imagine-video.
Seconds to add in a video-extension, on models that list this field. grok-imagine-video takes 6 or 10.
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.
Compatibility alias for duration. If both are sent, they must be identical.
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.
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.
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.
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.
Also return the last generated frame as last_frame_url. Seedance models only.
Watermark toggle for models that list this field (Seedance models).
What to avoid in the generated video, up to 5,000 characters, for models that list this field.
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.
Frames per second (1-120), for models that list this field.
Frame count, for models that list this field. Seedance models do not accept it.
Seconds the task may wait in the queue before it expires (3600 to 259200), for Seedance models.
Task priority from 0 to 9, for Seedance models. Do not combine it with service_tier=flex.
default is accepted as a compatibility no-op on Seedance 2.0 and 2.5 models. flex is rejected on those models.
End-user safety identifier (up to 128 characters), for Seedance models. If omitted, TokenLab uses user when provided.
Tools the model may use while generating, for Seedance 2.0 and 2.5 models. The supported tool is {"type": "web_search"}.
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, andreference_images. - For compatibility, TokenLab also accepts
ratio,generate_audio,outputAudio,seconds, andreferenceImages. - If a primary field and its alias are both sent, their values must match. A mismatch returns
400withconflicting_audio_selector,conflicting_duration, orconflicting_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 models | seedance-2.5 | |
|---|---|---|
| Resolution | seedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast and seedance-2.0-mini: 480p, 720p | 480p, 720p |
| Duration | -1, 4 to 15 seconds | -1, 4 to 30 seconds |
| Aspect ratio | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | Same 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 format | mp4 | mp4 or mov |
seed | Accepted | Not accepted |
| Reference inputs | 9 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 -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.
Task ID. Identical to task_id.
Task ID to poll with GET /v1/tasks/{id}.
Status URL for this task, /v1/tasks/{id}. Call it with your API key.
Task status: pending, processing, completed, failed. A new task is normally pending.
Unix timestamp when the task was created.
Model used.
Billing transaction ID when settlement already completed. It is separate from the task ID.
Video URL, present only when the create response already carries the result. Normally you read it from the status response.
Error message or structured error object when the task fails.
Errors
| Status and code | Meaning |
|---|---|
400 invalid_request | A 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_long | The request does not match what the model accepts for the operation. The error usually lists the accepted values. |
400 invalid_parameter | An input does not fit the operation, for example an image sent with text-to-video. |
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratio | An alias and its primary field disagree. |
400 unpriceable_selection | The selected combination has no price. Change resolution, duration, aspect_ratio, or the audio setting. |
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_model | Too many image references for a Seedance 2.0 model, or a material sent to another model. |
402 | Insufficient balance. |
403 task_not_owned | The task_id belongs to another workspace. |
409 seedance_material_preparing, seedance_material_route_unavailable | A material is not ACTIVE yet, or the selected model cannot use the provided materials. |
429 | Rate 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
{
"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 API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
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"
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.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json