Kling Vídeo - OrcaRouter

O OrcaRouter fala Kling nativamente para geração de vídeo. Você submete uma tarefa, faz polling do ID da tarefa pelo status e pega o MP4 renderizado quando o upstream termina (tipicamente 30 - 90 segundos). Esse padrão assíncrono submeter-depois-fazer-polling é exclusivo de vídeo. Chat / imagens / TTS todos usam request-response síncronos; o vídeo Kling não.

O endpoint de submit POST /v1/video/generations é compartilhado entre provedores de vídeo — o formato do corpo da requisição é selecionado pelo prefixo do seu model. Esta página cobre model: kling/.... Para modelos ByteDance Seedance use model: byteplus/... e siga Seedance Vídeo. O endpoint de fetch GET /v1/video/generations/{task_id} é idêntico para ambos.

Modelos

Todos os modelos suportam text-to-video e image-to-video. Recursos avançados variam:

Modelo	Multi-fonte ref¹	4K	Áudio nativo²	Multi-shot
`kling/kling-v2-master`
`kling/kling-v2-1-master`
`kling/kling-v2-5-turbo`
`kling/kling-v2-6`			modo pro
`kling/kling-v3`		✓	✓	✓
`kling/kling-video-o1`	✓ (limitado)
`kling/kling-v3-omni`	✓ (completo)	✓	✓	✓

¹ Referência multi-fonte = os campos de metadados image_list / video_list. Roteia para o endpoint upstream Omni-Video do Kling quando presente. kling/kling-video-o1 é um subconjunto restrito (apenas 5s/10s, sem multi-shot, sem áudio); escolha kling/kling-v3-omni para a superfície Omni completa. ² Áudio nativo = o Kling auto-gera uma trilha sonora correspondente ao vídeo. Cobra extra no upstream. Alternar via metadata.sound: "on". O endpoint de submit é o mesmo para todos os modelos — POST /v1/video/generations. O que muda é quais campos metadata o upstream honra, conforme a tabela acima.

Submeter uma tarefa

Envie um POST para /v1/video/generations com model, prompt e quaisquer parâmetros específicos do upstream sob 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"
    }
  }'

A resposta carrega o ID da tarefa:

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

POST retorna status: "queued" em minúsculas. GET retorna um envelope envelopado com status em maiúsculas (SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE) — veja Fazer polling pelos resultados abaixo.

Campos comuns de metadata

Estes três se aplicam a toda variante de endpoint:

Campo	Tipo	Notas
`mode`	string	`std` (720P) / `pro` (1080P) / `4k`. `4k` apenas em `kling/kling-v3` e `kling/kling-v3-omni`. Padrão é `std` para text/image-to-video, `pro` para Omni-Video.
`aspect_ratio`	string	`16:9` / `9:16` / `1:1`. Obrigatório em Omni-Video a menos que você forneça uma referência de primeiro frame ou `video_list` (nesses casos é inferido do input).
`duration`	string	Duração em segundos. Padrão `"5"`. `kling/kling-v3-omni` e `kling/kling-v3` aceitam `"3"` até `"15"`. A família v2 (`v2-master`, `v2-1-master`, `v2-5-turbo`, `v2-6`) e `kling/kling-video-o1` aceitam `"5"` ou `"10"`. Veja Mapa de capacidades Kling para a faixa autoritativa por modelo.

Estes dois funcionam apenas em text-to-video e image-to-video (não em Omni-Video):

Campo	Tipo	Notas
`negative_prompt`	string	Coisas a evitar. Máx. 2500 caracteres.
`cfg_scale`	float	Faixa `[0, 1]`, padrão `0.5`. Maior = adesão mais estrita ao prompt. Não suportado em modelos v2.x (`kling-v2-master` / `v2-1-master` / `v2-5-turbo` / `v2-6`).

Fazer polling pelos resultados

Use o ID da tarefa retornado no momento do submit:

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

O formato da resposta é envelopado:

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

Valores de status (maiúsculas, estado bruto da tarefa):

Status	Significado
`NOT_START`	Linha da tarefa criada, ainda não despachada (transitório, geralmente abaixo de 2s)
`SUBMITTED`	Enviada para o upstream Kling, aguardando na fila deles
`IN_PROGRESS`	Kling está renderizando
`SUCCESS`	Concluído. `data.result_url` carrega o MP4
`FAILURE`	Falhou. `data.fail_reason` tem o motivo

O progresso volta como uma string percentual ("30%", "100%"), não um int. Faça polling a cada 5 - 10 segundos. Um clipe std típico de 5 segundos completa em 30 - 60 segundos; tarefas 4K, de 15 segundos e multi-shot levam 2 - 5 minutos. data.result_url é uma URL assinada pelo Kling (observe os parâmetros de query ksTime / ksSecret). Baixe ou rehospede prontamente se precisar de retenção longa — a assinatura tem uma expiração definida pelo upstream.

Variantes de endpoint

Todas as três variantes compartilham POST /v1/video/generations. O endpoint que o Kling realmente serve é determinado pelos campos que você fornece.

Text-to-video

Apenas model + prompt (+ metadata opcional acima). Sem entrada de imagem 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

Adicione um image de nível superior (primeiro frame) e / ou metadata.image_tail (último frame) para i2v de primeiro / último 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"}
  }'

Referência multi-fonte (Omni-Video)

image_list e video_list roteiam a requisição para o endpoint Omni-Video do Kling. Disponível apenas em kling/kling-video-o1 e kling/kling-v3-omni. image_list — referência multi-imagem:

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

image_url (obrigatório): URL ou base64 bruto (sem o prefixo data:).
type (opcional): first_frame / end_frame. Omita a menos que a imagem seja destinada a uma âncora de frame. Apenas end não é suportado (sempre combine com uma imagem de primeiro frame).

video_list — referência de vídeo (máx. 1 vídeo, MP4/MOV, ≤200MB):

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

refer_type: base (edição de vídeo — o vídeo de entrada é editado; padrão) ou feature (referência de estilo/composição — gerar próximo/anterior shot).
keep_original_sound: yes / no.
Em kling/kling-v3-omni, a referência de vídeo é suportada apenas em duração 3-10s, modo std/pro (não 4K).

Quando video_list está definido, metadata.sound deve ser "off" — o Kling rejeita a combinação caso contrário.

Referencie imagens / vídeos / elementos dentro do prompt com a sintaxe <<<>>>: <<<image_1>>>, <<<video_1>>>, <<<element_1>>>. Apenas Omni. O índice combina com a ordem do 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"
    }
  }'

Recursos avançados

Esses recursos funcionam em endpoints text-to-video, image-to-video e Omni-Video — o suporte por modelo varia. Passe-os via metadata.

Multi-shot

Gere um vídeo composto por múltiplos shots sequenciais, cada um com seu próprio prompt e duração. Disponível em kling/kling-v3 e kling/kling-v3-omni.

Campo	Tipo	Propósito
`multi_shot`	bool	Defina como `true` para habilitar. O `prompt` de nível superior e as entradas first/end-frame são então ignorados.
`shot_type`	string	`customize` (usar `multi_prompt` literalmente) ou `intelligence` (o Kling auto-segmenta). Obrigatório quando `multi_shot=true`.
`multi_prompt`	array	`[{index, prompt, duration}]`. 1 - 6 storyboards. `duration` de cada shot ≥ 1s; a soma deve ser igual à `duration` total da tarefa. Cada `prompt` ≤ 512 caracteres.

Áudio nativo

O Kling auto-gera uma trilha sonora correspondente ao vídeo. Cobra extra no upstream. Alternar via metadata.sound: "on" (padrão "off"). Suporte por modelo:

kling/kling-v3 e kling/kling-v3-omni: qualquer modo (std / pro / 4K)
kling/kling-v2-6: apenas modo pro
Todos os outros modelos: não suportado

Marca d’água

Passe metadata.watermark_info: {enabled: true} para imprimir a marca d’água do Kling no vídeo renderizado. O padrão é sem marca d’água.

Faturamento

O vídeo Kling cobra por tarefa. O OrcaRouter cobra exatamente o que o Kling cobra — o final_unit_deduction do upstream se torna o débito da carteira, sem margem. O custo final corresponde ao tarifário publicado pelo Kling. Uma pequena reserva de pré-consumo é feita no momento do submit para cobrir o maior custo plausível para sua requisição (ex.: 4K + áudio); a diferença é reembolsada assim que a tarefa é bem-sucedida. Veja o histórico da sua carteira no console para o gasto real por tarefa.

Usando o SDK do Kling diretamente

Se você já tem código escrito contra o SDK oficial do Kling, o OrcaRouter também fala o formato de fio nativo do Kling em /kling/v1/videos/.... Os campos do corpo permanecem planos (model_name, mode, etc.) — apenas a base URL, o cabeçalho Authorization e o valor de model_name mudam:

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 usar a identidade de modelo do lado do OrcaRouter (o mesmo nome que você usaria em /v1/video/generations), não o nome puro do modelo do Kling. O OrcaRouter o resolve através do mapeamento de modelo do canal antes de encaminhar para o Kling.

O caminho de fetch correspondente é GET /kling/v1/videos/omni-video/{task_id} (ou text2video, image2video). Escolha o formato de fio que combina com seu código existente. Ambos cobram igualmente.

Veja também

Referência da API / Video — esquema completo com teste ao vivo (escolha a variante Kling video request no dropdown de esquema de corpo)
Seedance Vídeo — o mesmo endpoint, com modelos Seedance 1.0 / 1.5 / 2.0 e um corpo de requisição em formato content[]
Operações / Faturamento e uso
Operações / Erros

​Modelos

​Submeter uma tarefa

​Campos comuns de metadata

​Fazer polling pelos resultados

​Variantes de endpoint

​Text-to-video

​Image-to-video

​Referência multi-fonte (Omni-Video)

​Recursos avançados

​Multi-shot

​Áudio nativo

​Marca d’água

​Faturamento

​Usando o SDK do Kling diretamente

​Veja também

Modelos

Submeter uma tarefa

Campos comuns de metadata

Fazer polling pelos resultados

Variantes de endpoint

Text-to-video

Image-to-video

Referência multi-fonte (Omni-Video)

Recursos avançados

Multi-shot

Áudio nativo

Marca d’água

Faturamento

Usando o SDK do Kling diretamente

Veja também