Kling Video - OrcaRouter

OrcaRouter parla Kling nativamente per la generazione video. Invii un task, fai polling dell’ID del task per il suo stato e ritiri l’MP4 renderizzato una volta che l’upstream ha completato (tipicamente 30 - 90 secondi). Questo pattern submit-then-poll asincrono è unico per il video. Chat / immagini / TTS usano tutti richiesta-risposta sincrona; Kling video no.

L’endpoint di submit POST /v1/video/generations è condiviso tra i provider video — la forma del body della richiesta è selezionata dal prefisso model. Questa pagina copre model: kling/.... Per i modelli ByteDance Seedance usa model: byteplus/... e segui Seedance Video. L’endpoint di fetch GET /v1/video/generations/{task_id} è identico per entrambi.

Modelli

Tutti i modelli supportano text-to-video e image-to-video. Le funzionalità avanzate variano:

Modello	Riferimento multi-source¹	4K	Audio nativo²	Multi-shot
`kling/kling-v2-master`
`kling/kling-v2-1-master`
`kling/kling-v2-5-turbo`
`kling/kling-v2-6`			modalità pro
`kling/kling-v3`		✓	✓	✓
`kling/kling-video-o1`	✓ (limitato)
`kling/kling-v3-omni`	✓ (completo)	✓	✓	✓

¹ Riferimento multi-source = i campi metadati image_list / video_list. Instrada all’endpoint upstream Omni-Video di Kling quando presente. kling/kling-video-o1 è un sottoinsieme vincolato (solo 5s/10s, senza multi-shot, senza audio); scegli kling/kling-v3-omni per la superficie Omni completa. ² Audio nativo = Kling auto-genera una colonna sonora abbinata al video. Costo aggiuntivo upstream. Si attiva tramite metadata.sound: "on". L’endpoint di submit è lo stesso per tutti i modelli — POST /v1/video/generations. Ciò che cambia è quali campi metadata l’upstream onora secondo la tabella sopra.

Inviare un task

Invia una POST a /v1/video/generations con model, prompt e qualsiasi parametro specifico dell’upstream sotto metadata:

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "cat playing piano in a sunny room",
    "metadata": {
      "mode": "std",
      "aspect_ratio": "16:9",
      "duration": "5"
    }
  }'

La risposta contiene l’ID del task:

{
  "id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "object": "video",
  "model": "kling/kling-v3-omni",
  "status": "queued",
  "progress": 0,
  "created_at": 1777975188
}

POST restituisce status: "queued" in minuscolo. GET restituisce un envelope incapsulato con status in maiuscolo (SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE) — vedi Polling dei risultati qui sotto.

Campi metadata comuni

Questi tre si applicano a ogni variante di endpoint:

Campo	Tipo	Note
`mode`	string	`std` (720P) / `pro` (1080P) / `4k`. `4k` solo su `kling/kling-v3` e `kling/kling-v3-omni`. Default `std` per text/image-to-video, `pro` per Omni-Video.
`aspect_ratio`	string	`16:9` / `9:16` / `1:1`. Richiesto su Omni-Video a meno che tu non fornisca un riferimento di first-frame o `video_list` (in quei casi viene inferito dall’input).
`duration`	string	Lunghezza in secondi. Default `"5"`. `kling/kling-v3-omni` e `kling/kling-v3` accettano da `"3"` a `"15"`. La famiglia v2 (`v2-master`, `v2-1-master`, `v2-5-turbo`, `v2-6`) e `kling/kling-video-o1` accettano `"5"` o `"10"`. Vedi la Mappa delle capacità Kling per l’intervallo autoritativo per modello.

Questi due funzionano solo su text-to-video e image-to-video (non Omni-Video):

Campo	Tipo	Note
`negative_prompt`	string	Elementi da evitare. Max 2500 caratteri.
`cfg_scale`	float	Intervallo `[0, 1]`, default `0.5`. Più alto = aderenza più stretta al prompt. Non supportato sui modelli v2.x (`kling-v2-master` / `v2-1-master` / `v2-5-turbo` / `v2-6`).

Polling dei risultati

Usa l’ID del task restituito al momento del submit:

curl https://api.orcarouter.ai/v1/video/generations/task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw \
  -H "Authorization: Bearer sk-orca-..."

La forma della risposta è incapsulata:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://v16-kling-fdl.klingai.com/.../video.mp4?...",
    "action": "omniVideo",
    "submit_time": 1777975188,
    "start_time": 1777975241,
    "finish_time": 1777975277,
    "fail_reason": ""
  }
}

Valori di status (maiuscolo, stato grezzo del task):

Status	Significato
`NOT_START`	Riga del task creata, non ancora inviata (transitorio, di solito sotto i 2s)
`SUBMITTED`	Inviato all’upstream Kling, in attesa nella loro coda
`IN_PROGRESS`	Kling sta renderizzando
`SUCCESS`	Fatto. `data.result_url` contiene l’MP4
`FAILURE`	Fallito. `data.fail_reason` ha la ragione

Il progresso torna come stringa percentuale ("30%", "100%"), non come int. Fai polling ogni 5 - 10 secondi. Una clip std di 5 secondi tipica si completa in 30 - 60 secondi; i task 4K, 15 secondi e multi-shot richiedono 2 - 5 minuti. data.result_url è un URL firmato Kling (nota i query param ksTime / ksSecret). Scarica o riospita prontamente se hai bisogno di una retention lunga — la firma ha una scadenza definita upstream.

Varianti di endpoint

Tutte e tre le varianti condividono POST /v1/video/generations. L’endpoint che Kling serve effettivamente è determinato da quali campi fornisci.

Text-to-video

Solo model + prompt (+ metadata opzionali sopra). Nessun input immagine significa text-to-video:

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-6",
    "prompt": "ocean waves at sunset, cinematic",
    "metadata": {"mode": "pro", "duration": "5"}
  }'

Image-to-video

Aggiungi un image di livello superiore (primo frame) e/o metadata.image_tail (ultimo frame) per i2v primo / ultimo frame:

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-master",
    "prompt": "the cat starts dancing",
    "image": "https://example.com/cat.png",
    "metadata": {"mode": "std", "duration": "5"}
  }'

Riferimento multi-source (Omni-Video)

image_list e video_list instradano la richiesta all’endpoint Omni-Video di Kling. Disponibile solo su kling/kling-video-o1 e kling/kling-v3-omni. image_list — riferimento multi-immagine:

{ "image_list": [{ "image_url": "...", "type": "first_frame" }] }

image_url (obbligatorio): URL o base64 grezzo (senza prefisso data:).
type (opzionale): first_frame / end_frame. Ometti a meno che l’immagine sia intesa come ancoraggio di frame. Solo end-frame non è supportato (accoppia sempre con un’immagine first-frame).

video_list — riferimento video (max 1 video, MP4/MOV, ≤200MB):

{ "video_list": [{ "video_url": "...", "refer_type": "base", "keep_original_sound": "yes" }] }

refer_type: base (editing video — il video di input viene modificato; default) o feature (riferimento di stile/composizione — genera lo shot successivo/precedente).
keep_original_sound: yes / no.
Su kling/kling-v3-omni, il riferimento video è supportato solo a durata 3-10s, modalità std/pro (non 4K).

Quando video_list è impostato, metadata.sound deve essere "off" — Kling rifiuta la combinazione altrimenti.

Fai riferimento a immagini / video / elementi all’interno del prompt con la sintassi <<<>>>: <<<image_1>>>, <<<video_1>>>, <<<element_1>>>. Solo Omni. L’indice corrisponde all’ordine dell’array (1-based).

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "<<<image_1>>> waves at the camera, then walks toward the ocean",
    "metadata": {
      "image_list": [{"image_url": "https://example.com/person.jpg"}],
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": "5",
      "sound": "on"
    }
  }'

Funzionalità avanzate

Queste funzionalità lavorano attraverso gli endpoint text-to-video, image-to-video e Omni-Video — il supporto per modello varia. Passale tramite metadata.

Multi-shot

Genera un video composto da più shot sequenziali, ciascuno con il proprio prompt e durata. Disponibile su kling/kling-v3 e kling/kling-v3-omni.

Campo	Tipo	Scopo
`multi_shot`	bool	Imposta `true` per abilitare. Il `prompt` di livello superiore e gli input di primo/ultimo frame sono quindi ignorati.
`shot_type`	string	`customize` (usa `multi_prompt` letteralmente) o `intelligence` (Kling auto-segmenta). Richiesto quando `multi_shot=true`.
`multi_prompt`	array	`[{index, prompt, duration}]`. Da 1 a 6 storyboard. La `duration` di ogni shot ≥ 1s; la somma deve uguagliare la `duration` totale del task. Ogni `prompt` ≤ 512 caratteri.

Audio nativo

Kling auto-genera una colonna sonora abbinata al video. Costo aggiuntivo upstream. Si attiva tramite metadata.sound: "on" (default "off"). Supporto per modello:

kling/kling-v3 e kling/kling-v3-omni: qualsiasi modalità (std / pro / 4K)
kling/kling-v2-6: solo modalità pro
Tutti gli altri modelli: non supportato

Watermark

Passa metadata.watermark_info: {enabled: true} per imprimere il watermark di Kling sul video renderizzato. Il default è nessun watermark.

Fatturazione

Il video Kling fattura per task. OrcaRouter addebita esattamente ciò che addebita Kling — il final_unit_deduction dell’upstream diventa il debito del wallet, senza ricarico. Il costo finale corrisponde al listino pubblicato da Kling. Un piccolo pre-consumo viene riservato al momento del submit per coprire il costo più alto plausibile per la tua richiesta (es. 4K + audio); la differenza viene rimborsata non appena il task ha successo. Consulta la cronologia del wallet nella console per la spesa effettiva per task.

Usare direttamente l’SDK Kling

Se hai già codice scritto contro l’SDK ufficiale di Kling, OrcaRouter parla anche il formato wire nativo di Kling su /kling/v1/videos/.... I campi del body restano piatti (model_name, mode, ecc.) — cambiano solo il base URL, l’header Authorization e il valore di model_name:

curl https://api.orcarouter.ai/kling/v1/videos/omni-video \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling/kling-v3-omni",
    "prompt": "cat playing piano",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "5",
    "sound": "on"
  }'

model_name deve usare l’identità del modello lato OrcaRouter (lo stesso nome che useresti su /v1/video/generations), non il nome bare del modello Kling. OrcaRouter lo risolve attraverso il mapping dei modelli del canale prima di inoltrare a Kling.

Il path di fetch corrispondente è GET /kling/v1/videos/omni-video/{task_id} (o text2video, image2video). Scegli il formato wire che meglio si adatta al tuo codice esistente. Entrambi fatturano in modo identico.

Vedi anche

API Reference / Video — schema completo con try-it (scegli la variante Kling video request dal menu a tendina dello schema del body)
Seedance Video — lo stesso endpoint, con i modelli Seedance 1.0 / 1.5 / 2.0 e un body di richiesta a forma di content[]
Operazioni / Fatturazione e utilizzo
Operazioni / Errori

​Modelli

​Inviare un task

​Campi metadata comuni

​Polling dei risultati

​Varianti di endpoint

​Text-to-video

​Image-to-video

​Riferimento multi-source (Omni-Video)

​Funzionalità avanzate

​Multi-shot

​Audio nativo

​Watermark

​Fatturazione

​Usare direttamente l’SDK Kling

​Vedi anche

Modelli

Inviare un task

Campi metadata comuni

Polling dei risultati

Varianti di endpoint

Text-to-video

Image-to-video

Riferimento multi-source (Omni-Video)

Funzionalità avanzate

Multi-shot

Audio nativo

Watermark

Fatturazione

Usare direttamente l’SDK Kling

Vedi anche