Video

Create video generation (async)

Generate video from a text prompt, optionally conditioned on a starting frame (image-to-video). Asynchronous - returns 202 with a job_id immediately; poll GET /v1/jobs/{id} for the result. Billed per generation; failures are refunded in full.

post/videos/generations

Request

  • Base URL: https://kymaapi.com/v1
  • URL: https://kymaapi.com/v1/videos/generations
  • Auth: HTTP bearer

Request body

modelstring required

Video model ID (output modality includes video). See GET /v1/models for the live catalogue; a model that is not being served returns 404 model_not_found.

promptstring required

Natural-language description of the video to generate.

duration_sinteger

Requested clip length in seconds. Allowed values are model-dependent; out-of-range values snap to the nearest supported duration. For kling-avatar-v2-pro it is required and is the length of your audio, rounded up (5 to 60): the clip follows the audio, you are charged for the clip's real length, and duration_s caps that charge. Audio longer than duration_s is cut at duration_s.

aspect_ratiostring

Output aspect ratio (e.g. 16:9, 9:16, 1:1). Model-dependent; unsupported values fall back to the model default.

image_urlstring

Optional HTTPS URL of a starting frame for image-to-video models. Omit for pure text-to-video. Required by kling-avatar-v2-pro, where it is the face to animate.

audio_urlstring

kling-avatar-v2-pro only: 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 s. The clip runs as long as this audio and plays it unchanged. Any other model refuses it with 400 invalid_parameter.

idempotency_keystring

Deduplication key. Resending the same body with the same key within the retention window returns the existing job (200 with the original VideoJob), not a new charge. Also accepted via the Idempotency-Key header.

extraobject

Pass-through to the underlying model. Validated upstream. Never changes a priced field; ignored by kling-avatar-v2-pro.

Response

Idempotent replay - same idempotency_key returns the existing job

idstring
object'video.job'
status'pending' | 'processing' | 'succeeded' | 'failed' | 'refunded' | 'expired'
modelstring
created_atstring date-time
completed_atstring date-time nullable
estimated_costnumber nullable

Hold amount placed at submit time (USD), as the ledger holds it. null while the job is queued and nothing is held yet.

charged_amountnumber nullable

Final billed amount (USD) once the hold is released: what a successful job cost, 0 for a failed or refunded one. null until then.

refunded_amountnumber nullable

The part of the hold returned to your balance (USD) once it is released. null until then.

Changes

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