Skip to main content
POST
Video Generations
Async endpoint. The request returns immediately with the job’s id; the actual generation runs in the background and is charged on success only. Billed per second of generated footage.

Request body

string
required
veo-3.1-fast (Google, 720p with native audio, 4/6/8s), kling-3-pro (Kuaishou Kling 3 Pro, silent, 3–15s) or kling-avatar-v2-pro (Kuaishou Kling AI Avatar v2 Pro: one portrait + one PCM WAV voice or song track → a lip-synced clip as long as the audio). Other video ids are paused and return 404 model_not_found. See Video Generation.
string
required
Text prompt describing the desired video. Maximum 4000 characters.
number
Clip length in seconds. Each model accepts its own set of lengths; a value it does not accept is snapped to one it does, not refused. When omitted, the model’s shortest length is used. Each second is billed at the model’s per-second rate.For kling-avatar-v2-pro it is required and means something else: the length of your audio in seconds, rounded up (5 to 60). The clip runs as long as the audio and you are charged for the clip’s real length; duration_s caps that charge. Audio longer than duration_s is cut at duration_s before generation.
string
Aspect ratio of the clip, for example "16:9" or "9:16".
string
HTTPS URL of a starting frame. When present, the image becomes the first frame and the prompt drives the motion. Optional, except on kling-avatar-v2-pro, where it is required and is the face to animate.
string
kling-avatar-v2-pro only, and required there: HTTPS URL of the speech or song to lip-sync, as an uncompressed PCM WAV file (WAV PCM only for now: MP3, M4A, AAC and OGG are refused), at least 5 seconds. The clip plays this audio unchanged. Any other model refuses it with 400 invalid_parameter.
string
Client-supplied key to make the request safe to retry. Also accepted as an Idempotency-Key header; keys longer than 128 characters are cut to 128. The key is scoped to your account: repeated POSTs with the same key return the same job — no duplicate charge, no duplicate generation.
object
Model-specific parameters. On kling-3-pro only cfg_scale (a number from 0 to 1) is forwarded and every other field is ignored, so multi-shot prompts, reference elements, end frames and voices cannot change what a job costs or bypass prompt moderation. On other models it is a pass-through (e.g. seed), except the fields your price is based on or that are moderated (prompt, image count, size, duration, reference images): those always come from the top-level parameters, and provider quality tiers that are not priced separately run at the priced tier.

Response

202 Accepted for new jobs, 200 OK if the same idempotency_key is replayed.
string
Job ID. Use it to poll GET /v1/jobs/{id}.
string
One of: pending, processing, succeeded, failed, refunded, expired.
number
Hold amount placed at submit time (USD) — per_second_usd × duration_s. Refunded if the job fails.
number | null
Final billed amount once the job succeeds. null until then.
number | null
The part of the hold returned to your balance once it is released (USD). null until then.

Poll for the result

Same response shape. Poll every 2–5 seconds until status is succeeded, failed, refunded, or expired. Most clips complete within 1–3 minutes; the runner times out at 10 minutes.
The output.url is a Kyma-hosted URL. The clip is copied there so the link keeps working after the model’s own temporary link expires.

Errors

When status becomes failed or refunded, no charge is made and the held funds are returned to your balance via a hold_release ledger entry.

Examples

Talking-head with native audio

Cinematic hero clip

Image-to-video

Idempotent retry

Replaying this exact request returns the same job — no new charge.