Generate video (POST /video/generate)

Creates a video task on the model you name. There is no auto and no count: one request renders one video. A render takes minutes, so plan for a webhook rather than holding a request open.

Resolution, duration, audio, and frame inputs are checked against the model at create. Video models lists what each model accepts, and generate video covers the result.

Request body

modelstringrequired

"bytedance/seedance-2.0-mini""google/gemini-omni-flash-1.1""prunaai/p-video""xai/grok-imagine-video-1.5"

promptstringrequired

Positive prompt.

e.g. "A cat surfing a wave at sunset"≥ 1 characters≤ 8192 characters

negative_promptstring

≤ 8192 characters

durationnumber

Video duration in seconds. Defaults to the model's default duration.

≥ 1≤ 60

sizeobject | string

Aspect ratio and resolution tier. The aspect ratio is best effort: the closest one the model supports. With image inputs the first frame sets the shape. Defaults to "auto".

"auto""square""portrait""landscape""portrait_tall""landscape_wide""1:1""2:3"

type"auto"required
resolutionstring: Resolution tier. Each model supports a subset, and a tier it does not support is rejected. Defaults to the model's default tier.
"480p""720p""1080p""4k"

audioboolean

Enable model-native generated audio. Only supported by models with audio capability.

inputs(string | object)[]

≤ 5 items

type"image"required

asstring

"auto""first_frame""last_frame""reference"

sourceobjectrequired

type"url"required
urlstringrequired: format: uri

generate_public_access_tokenboolean

Return a short-lived public access token as public_access_token, for polling this task from browser code without your API key. Defaults to false.

webhookobject

registeredboolean

Set to false to skip the webhooks registered on the account for this task. Custom webhooks in custom are still sent.

customobject[]

≥ 1 items≤ 5 items

urlstringrequired: Receives this task's events, unsigned. Use https and a public host, and put a secret token in the query string to verify deliveries: only scheme://host is ever shown back.
e.g. "https://example.com/hooks/mynth?token=your-secret-token"

metadataobject

Response

Video generation task created

dataobjectrequired

task_idstringrequired: Task ID
e.g. "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP"
estimated_coststringrequired: Estimated cost in USD reserved for this task. Work that fails is refunded, so the final cost may be lower.
e.g. "0.03"
public_access_tokenstring: Short-lived public access token for polling this task's status and result.
Safe to hand to browser code instead of your API key. Returned only when the request set generate_public_access_token: true.
e.g. "pat_eyJhbGciOi..."

Errors

A failed call names what went wrong in code, with a sentence in message. The codes, which of them are worth retrying, and how to read a validation failure are on Errors.