Kling Video - OrcaRouter

OrcaRouter mówi natywnie po Klingu do generowania wideo. Wysyłasz zadanie, pollujesz task ID o jego status i odbierasz wyrenderowany MP4, gdy upstream skończy (zwykle 30 - 90 sekund). Ten asynchroniczny wzorzec submit-then-poll jest unikalny dla wideo. Chat / images / TTS używają synchronicznego request-response; wideo Kling nie.

Endpoint zgłaszania POST /v1/video/generations jest współdzielony między dostawców wideo — kształt ciała żądania jest wybierany przez prefiks model. Ta strona dotyczy model: kling/.... Dla modeli ByteDance Seedance użyj model: byteplus/... i podążaj za Seedance Video. Endpoint pobierania GET /v1/video/generations/{task_id} jest identyczny dla obu.

Modele

Wszystkie modele obsługują text-to-video i image-to-video. Zaawansowane funkcje się różnią:

Model	Multi-source ref¹	4K	Natywne audio²	Multi-shot
`kling/kling-v2-master`
`kling/kling-v2-1-master`
`kling/kling-v2-5-turbo`
`kling/kling-v2-6`			tryb pro
`kling/kling-v3`		✓	✓	✓
`kling/kling-video-o1`	✓ (ograniczone)
`kling/kling-v3-omni`	✓ (pełne)	✓	✓	✓

¹ Multi-source reference = pola metadanych image_list / video_list. Routuje do endpointu Omni-Video Kling, gdy są obecne. kling/kling-video-o1 to ograniczony podzbiór (tylko 5s/10s, bez multi-shot, bez audio); wybierz kling/kling-v3-omni, aby uzyskać pełną powierzchnię Omni. ² Natywne audio = Kling auto-generuje ścieżkę dźwiękową pasującą do wideo. Rozlicza dodatkowo upstream. Przełącz przez metadata.sound: "on". Endpoint zgłaszania jest taki sam dla wszystkich modeli — POST /v1/video/generations. Zmienia się to, które pola metadata upstream honoruje, zgodnie z tabelą powyżej.

Wyślij zadanie

Wyślij POST na /v1/video/generations z model, prompt i dowolnymi upstream-specyficznymi parametrami pod 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"
    }
  }'

Odpowiedź niesie task ID:

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

POST zwraca małymi literami status: "queued". GET zwraca opakowaną kopertę z statusem dużymi literami (SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE) — zobacz poniżej “Polluj po wyniki”.

Wspólne pola metadanych

Te trzy obowiązują w każdym wariancie endpointu:

Pole	Typ	Uwagi
`mode`	string	`std` (720P) / `pro` (1080P) / `4k`. `4k` tylko na `kling/kling-v3` i `kling/kling-v3-omni`. Domyślnie `std` dla text/image-to-video, `pro` dla Omni-Video.
`aspect_ratio`	string	`16:9` / `9:16` / `1:1`. Wymagane na Omni-Video, chyba że dostarczysz referencję pierwszej klatki lub `video_list` (w tych przypadkach wnioskowane z wejścia).
`duration`	string	Długość w sekundach. Domyślnie `"5"`. `kling/kling-v3-omni` i `kling/kling-v3` akceptują `"3"` do `"15"`. Rodzina v2 (`v2-master`, `v2-1-master`, `v2-5-turbo`, `v2-6`) oraz `kling/kling-video-o1` akceptują `"5"` lub `"10"`. Zobacz Kling Capability Map dla autorytatywnego zakresu per-model.

Te dwa działają tylko na text-to-video i image-to-video (nie Omni-Video):

Pole	Typ	Uwagi
`negative_prompt`	string	Rzeczy do uniknięcia. Max 2500 znaków.
`cfg_scale`	float	Zakres `[0, 1]`, domyślnie `0.5`. Wyższy = ściślejsza zgodność z promptem. Nieobsługiwane na modelach v2.x (`kling-v2-master` / `v2-1-master` / `v2-5-turbo` / `v2-6`).

Polluj po wyniki

Użyj task ID zwróconego przy zgłaszaniu:

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

Kształt odpowiedzi jest opakowany:

{
  "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": ""
  }
}

Wartości statusu (duże litery, surowy stan zadania):

Status	Znaczenie
`NOT_START`	Wiersz zadania utworzony, jeszcze nie wysłany (przejściowo, zwykle pod 2s)
`SUBMITTED`	Wysłany do upstreamu Kling, czeka w ich kolejce
`IN_PROGRESS`	Kling renderuje
`SUCCESS`	Zrobione. `data.result_url` niesie MP4
`FAILURE`	Awaria. `data.fail_reason` ma powód

Postęp wraca jako procentowy string ("30%", "100%"), nie int. Polluj co 5 - 10 sekund. Typowy klip std 5-sekundowy kończy się w 30 - 60 sekund; zadania 4K, 15-sekundowe i multi-shot trwają 2 - 5 minut. data.result_url to URL podpisany przez Kling (zauważ parametry query ksTime / ksSecret). Pobierz lub przehostuj szybko, jeśli potrzebujesz długiej retencji — sygnatura ma wygaśnięcie zdefiniowane przez upstream.

Warianty endpointów

Wszystkie trzy warianty współdzielą POST /v1/video/generations. Endpoint, który Kling faktycznie obsługuje, jest określony przez to, jakie pola dostarczysz.

Text-to-video

Tylko model + prompt (+ opcjonalne metadane powyżej). Brak wejścia obrazu oznacza 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

Dodaj na poziomie głównym image (pierwsza klatka) i / lub metadata.image_tail (ostatnia klatka) dla first / last frame i2v:

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"}
  }'

Multi-source reference (Omni-Video)

image_list i video_list routują żądanie do endpointu Omni-Video Kling. Dostępne tylko na kling/kling-video-o1 i kling/kling-v3-omni. image_list — referencja wieloobrazowa:

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

image_url (wymagane): URL lub surowy base64 (bez prefiksu data:).
type (opcjonalne): first_frame / end_frame. Pomiń, chyba że obraz ma być kotwicą klatki. End-only nie jest obsługiwane (zawsze parami z obrazem first-frame).

video_list — referencja wideo (max 1 wideo, MP4/MOV, ≤200MB):

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

refer_type: base (edycja wideo — wejściowe wideo jest edytowane; domyślne) lub feature (referencja stylu/kompozycji — wygeneruj następne/poprzednie ujęcie).
keep_original_sound: yes / no.
Na kling/kling-v3-omni referencja wideo jest obsługiwana tylko przy czasie trwania 3-10s, w trybie std/pro (nie 4K).

Gdy ustawione jest video_list, metadata.sound musi być "off" — Kling odrzuci kombinację w przeciwnym razie.

Odwołuj się do obrazów / wideo / elementów wewnątrz promptu składnią <<<>>>: <<<image_1>>>, <<<video_1>>>, <<<element_1>>>. Tylko Omni. Indeks odpowiada kolejności tablicy (od 1).

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"
    }
  }'

Zaawansowane funkcje

Te funkcje działają między endpointami text-to-video, image-to-video i Omni-Video — wsparcie modelu się różni. Przekaż je przez metadata.

Multi-shot

Wygeneruj wideo złożone z wielu sekwencyjnych ujęć, każde z własnym promptem i czasem trwania. Dostępne na kling/kling-v3 i kling/kling-v3-omni.

Pole	Typ	Cel
`multi_shot`	bool	Ustaw `true`, aby włączyć. Główny `prompt` oraz wejścia first/end-frame są wtedy ignorowane.
`shot_type`	string	`customize` (użyj `multi_prompt` dosłownie) lub `intelligence` (Kling auto-segmentuje). Wymagane przy `multi_shot=true`.
`multi_prompt`	array	`[{index, prompt, duration}]`. 1 - 6 storyboardów. `duration` każdego ujęcia ≥ 1s; suma musi równać się łącznemu `duration` zadania. Każdy `prompt` ≤ 512 znaków.

Natywne audio

Kling auto-generuje ścieżkę dźwiękową pasującą do wideo. Rozlicza dodatkowo upstream. Przełącz przez metadata.sound: "on" (domyślnie "off"). Wsparcie modelu:

kling/kling-v3 i kling/kling-v3-omni: dowolny tryb (std / pro / 4K)
kling/kling-v2-6: tylko tryb pro
Wszystkie inne modele: nieobsługiwane

Watermark

Przekaż metadata.watermark_info: {enabled: true}, aby odcisnąć watermark Kling na wyrenderowanym wideo. Domyślnie bez watermarka.

Rozliczenia

Wideo Kling jest rozliczane per zadanie. OrcaRouter pobiera dokładnie tyle, co Kling — upstreamowe final_unit_deduction staje się obciążeniem portfela, bez narzutu. Końcowy koszt odpowiada opublikowanej karcie cen Kling. Niewielka pre-konsumowana rezerwa jest blokowana przy zgłaszaniu, aby pokryć najwyższy prawdopodobny koszt dla Twojego żądania (np. 4K + audio); różnica jest zwracana zaraz po sukcesie zadania. Zobacz historię portfela w konsoli, aby poznać faktyczne wydatki per-zadanie.

Używanie SDK Kling bezpośrednio

Jeśli masz już kod napisany przeciwko oficjalnemu SDK Kling, OrcaRouter mówi też w natywnym formacie wire Kling na /kling/v1/videos/.... Pola ciała pozostają płaskie (model_name, mode itd.) — zmieniają się tylko bazowy URL, nagłówek Authorization i wartość 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 musi używać tożsamości modelu po stronie OrcaRouter (tę samą nazwę, której użyłbyś na /v1/video/generations), nie samej upstreamowej nazwy Kling. OrcaRouter rozwiązuje ją przez mapowanie modelu kanału przed przekazaniem do Kling.

Odpowiadająca ścieżka pobierania to GET /kling/v1/videos/omni-video/{task_id} (lub text2video, image2video). Wybierz format wire pasujący do Twojego istniejącego kodu. Oba są rozliczane identycznie.

Zobacz także

Dokumentacja API / Video — pełny schemat z try-it (wybierz wariant Kling video request z dropdownu schematu ciała)
Seedance Video — ten sam endpoint, z modelami Seedance 1.0 / 1.5 / 2.0 i ciałem żądania w kształcie content[]
Operacje / Rozliczenia i zużycie
Operacje / Błędy

​Modele

​Wyślij zadanie

​Wspólne pola metadanych

​Polluj po wyniki

​Warianty endpointów

​Text-to-video

​Image-to-video

​Multi-source reference (Omni-Video)

​Zaawansowane funkcje

​Multi-shot

​Natywne audio

​Watermark

​Rozliczenia

​Używanie SDK Kling bezpośrednio

​Zobacz także

Modele

Wyślij zadanie

Wspólne pola metadanych

Polluj po wyniki

Warianty endpointów

Text-to-video

Image-to-video

Multi-source reference (Omni-Video)

Zaawansowane funkcje

Multi-shot

Natywne audio

Watermark

Rozliczenia

Używanie SDK Kling bezpośrednio

Zobacz także