Video

Create video generation task

Creates an asynchronous video generation task. The response returns a canonical task ID and usually a preferred poll_url; clients should poll poll_url first, or use /v1/tasks/{id} as the fixed status endpoint.

post/v1/videos/generations

Request

  • Base URL: https://api.tokenlab.sh
  • URL: https://api.tokenlab.sh/v1/videos/generations
  • Auth: HTTP bearer

Headers

X-TokenLab-Delivery-Policy'auto' | 'verified' | 'official'

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.

Request body

promptstring

Video description

modelstring

Model to use (e.g., veo3.1, kling-v3.0)

operation'text-to-video' | 'image-to-video' | 'reference-to-video' | 'start-end-to-video' | 'video-to-video' | 'video-extension' | 'audio-to-video' | 'motion-control'

Requested video operation. If omitted, TokenLab infers the operation from the provided inputs. Explicit operation is recommended for production reliability.

imagestring

Inline image as a data URL (for example, data:image/png;base64,...). Prefer image_url for broader production compatibility. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

image_urlstring uri

Publicly reachable image URL for image-to-video generation, or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab Seedance material used as the first frame. Preferred over inline base64 in production. TokenLab verifies material ownership. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

video_urlstring uri

Publicly reachable video URL for video-to-video style flows and motion-control models.

durationinteger

Video duration in seconds. Seedance models also accept -1 to let the model choose within its supported duration range; TokenLab estimates billing conservatively for that mode.

aspect_ratio'adaptive' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9'

Canonical video aspect ratio. Seedance defaults to adaptive when omitted. The ratio alias is accepted for compatibility.

resolution'480p' | '720p' | '1080p' | '4k'

Video resolution. Seedance defaults to 720p when omitted; available values are model-dependent.

output_format'mp4' | 'mov'

Video container format for compatible models. Seedance 2.5 supports mp4 and mov; omit this field for Seedance 2.0 and other models that do not publish an output-format selector.

output_audioboolean

Audio-output selector for operations that declare it. Omission follows the model default; false requests silent output only when allowed. See the audio behavior above and the selected model detail.

fpsinteger

Frames per second

negative_promptstring

What to avoid in the video

seedinteger

Seed for reproducibility on compatible models. Compatible Seedance models use -1 for a random seed when omitted; Seedance 2.5 does not support this field.

cfg_scalenumber

Prompt adherence strength (0-20) for models that expose CFG-style control.

motion_strengthnumber

Motion intensity (0-1) for models that expose it.

start_imagestring

First frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

end_imagestring

Last frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

userstring

End-user identifier

image_urlsstring[]

Image URL array for compatible image-conditioned video flows. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 entries unless the model details specify a lower limit. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

reference_imagesstring[]

Canonical public reference-image field for reference-to-video conditioning. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 URLs or compatible data URLs unless the model details specify a lower limit. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

material_asset_idstring

TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or from a real-person group returned by GetVisualValidateResult. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image semantics explicitly, put asset://<material_asset_id> in start_image, end_image, or reference_images.

material_asset_idsstring[]

TokenLab Seedance material asset IDs returned by /v1/videos/assets or by automatic image preparation. They share the Seedance image-reference limit; the selected model must be able to use the TokenLab material library and all assets must belong to the current account and be ACTIVE.

reference_image_type'asset' | 'style'

Optional reference image role for models that distinguish between asset and style references. The camelCase alias referenceImageType is accepted for compatibility.

audio_urlstring uri

Public audio URL for an audio-driven or reference-audio operation supported by the selected model.

task_idstring

Task identifier used by some continuation, extension, or derivative flows.

extend_atinteger

Model-specific extension start offset used by some video-extension flows.

extend_timesstring

Model-specific extension multiplier or repeat count used by some video-extension flows.

secondsinteger

Alias of duration used by compatible request shapes. Seedance models also accept -1 to let the model choose within its supported duration range; duration and seconds must match when both are provided.

sizestring

Model-specific size tier for compatible video models.

watermarkboolean

Optional watermark toggle for models that expose it. Seedance defaults to false when omitted.

effect_typestring

Model-specific effect selector for specialized editing flows.

video_urlsstring[]

Compatibility array for video-conditioned flows when multiple input videos are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate video inputs; other video models retain the shared limit of 3 references unless the model details specify a lower limit.

audio_urlsstring[]

Compatibility array for audio-conditioned flows when multiple audio references are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate audio inputs and permits pure-audio reference requests without a prompt; other video models retain the shared limit of 3 references unless the model details specify a lower limit.

ratio'adaptive' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9'

Compatibility alias for aspect_ratio. If both ratio and aspect_ratio are provided, they must match.

outputAudioboolean

Compatibility alias for output_audio. If both are provided, they must match.

generate_audioboolean

Compatibility alias for output_audio. If more than one audio toggle is provided, all values must match.

execution_expires_afterinteger

Optional execution expiry window in seconds for compatible video models. Seedance defaults to 172800 seconds when omitted.

priorityinteger

Optional task priority for compatible video models. Do not combine priority with service_tier=flex.

safety_identifierstring

Optional safety/user trace identifier for compatible video models. If omitted for Seedance, TokenLab uses user when provided.

service_tier'default' | 'flex'

Optional service tier for compatible video models. service_tier=default is accepted as a compatibility no-op for Seedance 2.0 and Seedance 2.5; service_tier=flex is rejected for both models.

framesinteger

Optional frame count for compatible video models. Seedance 1.5 Pro, Seedance 2.0, and Seedance 2.5 do not support this field.

camera_fixedboolean

Optional fixed-camera selector for compatible video models. Seedance 2.0 and Seedance 2.5 do not support this field.

return_last_frameboolean

Return the last generated frame when the selected model supports it. Seedance defaults to false when omitted.

draftboolean

Seedance 1.5 Pro draft workflow flag. Only supported by Seedance models supporting drafts; draft=true creates a low-cost draft task.

draft_task_idstring

Seedance 1.5 Pro draft promotion task ID. Provide this instead of draft=true to create the final video from a previous draft task.

audioboolean

Audio-output selector for operations that declare it. Omission follows the model default; false requests silent output only when allowed. See the audio behavior above and the selected model detail.

bgmboolean

Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.

audio_typestring

Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.

voice_idstring

Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.

Response

Task created successfully

idstring required

Task ID

status'pending' | 'processing' | 'completed' | 'failed'

Task status

createdinteger

Unix timestamp

modelstring
task_idstring

Canonical async task identifier for polling. Treat this as the same identity as id when both are present.

poll_urlstring

Preferred polling URL for this task. Use this exact path when checking status.

video_urlstring

Generated video URL when the create response is already terminal or includes an immediate result.

last_frame_urlstring

Last generated frame URL when requested and supported by the selected model.

generate_audioboolean

Resolved audio output flag when returned by the adapter.

draftboolean

Whether the Seedance draft workflow was used for this task.

draft_task_idstring

Seedance draft task identifier when returned by the adapter.

Example response

{
  "media_retention": {
    "days": 30
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.