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

Request body

model
string
required
Kuaishou Kling: kling-2.5-pro, kling-3-pro, kling-3-pro-audio. ByteDance Seedance: seedance-2-pro, seedance-2-fast. MiniMax Hailuo: hailuo-02-512p, hailuo-02-768p, hailuo-02-1080p. Google Veo: veo-3-fast, veo-3 (720p silent / 1080p+audio). See Video Generation.
Veo video SKUs (veo-3-*) also accept the same model id on POST /v1/genmedia/jobs — same billing, same response shape. /v1/videos/generations is the OpenAI-style alias.
prompt
string
required
Text prompt describing the desired video. Maximum 4000 characters.
duration
number
default:"5"
Clip length in seconds. Range 1–10. Each second is billed at the model’s per-second rate.
image_url
string
HTTPS URL of a starting frame. When present, Kyma routes the request to the model’s image-to-video variant — the image becomes the first frame and the prompt drives the motion. Optional; all five models accept it.
idempotency_key
string
Client-supplied key (≤128 chars) to make the request safe to retry. Repeated POSTs with the same (api_key, idempotency_key) pair return the same job — no duplicate charge, no duplicate generation.
extra
object
Pass-through model-specific parameters (e.g. seed, aspect_ratio). Forwarded to the underlying provider unchanged.

Response

202 Accepted for new jobs, 200 OK if the same idempotency_key is replayed.
id
string
Job ID. Use it to poll GET /v1/jobs/{id}.
status
string
One of: pending, processing, succeeded, failed, refunded, expired.
estimated_cost
number
Hold amount placed at submit time (USD) — per_second_usd × duration. Refunded if the job fails.
charged_amount
number | null
Final billed amount once the job succeeds. 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 points to a Vercel Blob URL hosted by Kyma — the original upstream URL is rehosted so it remains stable after the upstream TTL 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

Cinematic hero clip

Talking-head with native audio

Image-to-video

Idempotent retry

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