Kling Vídeo - OrcaRouter

OrcaRouter habla Kling de forma nativa para generación de vídeo. Envías una tarea, consultas el ID de tarea para su estado y recoges el MP4 renderizado una vez que el upstream termina (típicamente 30 - 90 segundos). Este patrón asíncrono enviar-luego-consultar es único del vídeo. Chat / imágenes / TTS usan todos solicitud-respuesta síncrona; el vídeo Kling no.

El endpoint de envío POST /v1/video/generations se comparte entre proveedores de vídeo — la forma del cuerpo de solicitud se selecciona por tu prefijo model. Esta página cubre model: kling/.... Para modelos ByteDance Seedance usa model: byteplus/... y sigue Seedance Vídeo. El endpoint de obtención GET /v1/video/generations/{task_id} es idéntico para ambos.

Modelos

Todos los modelos soportan texto-a-vídeo e imagen-a-vídeo. Las funciones avanzadas varían:

Modelo	Ref. multi-fuente¹	4K	Audio nativo²	Multi-plano
`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)	✓	✓	✓

¹ Referencia multi-fuente = los campos de metadatos image_list / video_list. Enruta al endpoint upstream Omni-Video de Kling cuando está presente. kling/kling-video-o1 es un subconjunto restringido (solo 5s/10s, sin multi-plano, sin audio); elige kling/kling-v3-omni para la superficie Omni completa. ² Audio nativo = Kling auto-genera una banda sonora que coincide con el vídeo. Se factura extra en upstream. Activa vía metadata.sound: "on". El endpoint de envío es el mismo para todos los modelos — POST /v1/video/generations. Lo que cambia es qué campos metadata honra el upstream según la tabla anterior.

Enviar una tarea

Envía un POST a /v1/video/generations con model, prompt y cualquier parámetro específico del upstream bajo 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 respuesta lleva el ID de tarea:

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

POST devuelve status: "queued" en minúsculas. GET devuelve una envoltura con estado en mayúsculas (SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE) — ver “Consultar resultados” abajo.

Campos de metadatos comunes

Estos tres se aplican a cada variante de endpoint:

Campo	Tipo	Notas
`mode`	string	`std` (720P) / `pro` (1080P) / `4k`. `4k` solo en `kling/kling-v3` y `kling/kling-v3-omni`. Por defecto `std` para texto/imagen-a-vídeo, `pro` para Omni-Video.
`aspect_ratio`	string	`16:9` / `9:16` / `1:1`. Requerido en Omni-Video a menos que proporciones una referencia de primer fotograma o `video_list` (en esos casos se infiere de la entrada).
`duration`	string	Longitud en segundos. Por defecto `"5"`. `kling/kling-v3-omni` y `kling/kling-v3` aceptan `"3"` a `"15"`. La familia v2 (`v2-master`, `v2-1-master`, `v2-5-turbo`, `v2-6`) y `kling/kling-video-o1` aceptan `"5"` o `"10"`. Ver Mapa de capacidades Kling para el rango autorizado por modelo.

Estos dos funcionan solo en texto-a-vídeo e imagen-a-vídeo (no Omni-Video):

Campo	Tipo	Notas
`negative_prompt`	string	Cosas a evitar. Máx 2500 caracteres.
`cfg_scale`	float	Rango `[0, 1]`, por defecto `0.5`. Mayor = adherencia más estricta al prompt. No soportado en modelos v2.x (`kling-v2-master` / `v2-1-master` / `v2-5-turbo` / `v2-6`).

Consultar resultados

Usa el ID de tarea devuelto al enviar:

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

La forma de respuesta está envuelta:

{
  "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 estado (mayúsculas, estado de tarea crudo):

Estado	Significado
`NOT_START`	Fila de tarea creada, aún no despachada (transitorio, usualmente menos de 2s)
`SUBMITTED`	Enviado al upstream Kling, esperando en su cola
`IN_PROGRESS`	Kling está renderizando
`SUCCESS`	Hecho. `data.result_url` lleva el MP4
`FAILURE`	Fallido. `data.fail_reason` tiene la razón

El progreso vuelve como una cadena de porcentaje ("30%", "100%"), no un entero. Consulta cada 5 - 10 segundos. Un clip típico std de 5 segundos se completa en 30 - 60 segundos; las tareas 4K, 15 segundos y multi-plano tardan 2 - 5 minutos. data.result_url es una URL firmada por Kling (nota los parámetros de consulta ksTime / ksSecret). Descarga o re-aloja rápidamente si necesitas retención larga — la firma tiene una expiración definida por el upstream.

Variantes de endpoint

Las tres variantes comparten POST /v1/video/generations. El endpoint que Kling realmente sirve se determina por qué campos proporcionas.

Texto-a-vídeo

Solo model + prompt (+ metadatos opcionales arriba). Sin entrada de imagen significa texto-a-vídeo:

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

Imagen-a-vídeo

Añade una image de nivel superior (primer fotograma) y/o metadata.image_tail (último fotograma) para i2v primer/último fotograma:

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

Referencia multi-fuente (Omni-Video)

image_list y video_list enrutan la solicitud al endpoint Omni-Video de Kling. Disponible solo en kling/kling-video-o1 y kling/kling-v3-omni. image_list — referencia multi-imagen:

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

image_url (requerido): URL o base64 crudo (sin prefijo data:).
type (opcional): first_frame / end_frame. Omitir a menos que la imagen esté destinada como ancla de fotograma. Solo-final no está soportado (siempre emparejar con una imagen de primer fotograma).

video_list — referencia 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 (edición de vídeo — el vídeo de entrada se edita; por defecto) o feature (referencia de estilo/composición — generar siguiente/anterior plano).
keep_original_sound: yes / no.
En kling/kling-v3-omni, la referencia de vídeo solo se soporta en duración 3-10s, modo std/pro (no 4K).

Cuando video_list está configurado, metadata.sound debe ser "off" — Kling rechaza la combinación de lo contrario.

Referencia imágenes / vídeos / elementos dentro del prompt con la sintaxis <<<>>>: <<<image_1>>>, <<<video_1>>>, <<<element_1>>>. Solo Omni. El índice coincide con el orden del array (base 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"
    }
  }'

Funciones avanzadas

Estas funciones trabajan en los endpoints texto-a-vídeo, imagen-a-vídeo y Omni-Video — el soporte del modelo varía. Pásalos vía metadata.

Multi-plano

Genera un vídeo compuesto por múltiples planos secuenciales, cada uno con su propio prompt y duración. Disponible en kling/kling-v3 y kling/kling-v3-omni.

Campo	Tipo	Propósito
`multi_shot`	bool	Configurar a `true` para activar. El `prompt` de nivel superior y las entradas de primer/último fotograma se ignoran entonces.
`shot_type`	string	`customize` (usar `multi_prompt` literalmente) o `intelligence` (Kling auto-segmenta). Requerido cuando `multi_shot=true`.
`multi_prompt`	array	`[{index, prompt, duration}]`. 1 - 6 guiones gráficos. La `duration` de cada plano ≥ 1s; la suma debe igualar la `duration` total de la tarea. Cada `prompt` ≤ 512 caracteres.

Audio nativo

Kling auto-genera una banda sonora que coincide con el vídeo. Se factura extra en upstream. Activa vía metadata.sound: "on" (por defecto "off"). Soporte de modelo:

kling/kling-v3 y kling/kling-v3-omni: cualquier modo (std / pro / 4K)
kling/kling-v2-6: modo pro solo
Todos los demás modelos: no soportado

Marca de agua

Pasa metadata.watermark_info: {enabled: true} para imprimir la marca de agua de Kling en el vídeo renderizado. Por defecto sin marca de agua.

Facturación

El vídeo Kling se factura por tarea. OrcaRouter cobra exactamente lo que Kling cobra — la final_unit_deduction upstream se convierte en el débito de la cartera, sin recargo. El coste final coincide con la tarjeta de tarifas publicada de Kling. Una pequeña reserva de pre-consumo se reserva al enviar para cubrir el coste más plausible para tu solicitud (p. ej. 4K + audio); la diferencia se reembolsa tan pronto como la tarea tiene éxito. Consulta el historial de tu cartera en la consola para el gasto real por tarea.

Usar el SDK Kling directamente

Si ya tienes código escrito contra el SDK oficial de Kling, OrcaRouter también habla el formato de cable nativo de Kling en /kling/v1/videos/.... Los campos del cuerpo permanecen planos (model_name, mode, etc.) — solo cambian la URL base, la cabecera Authorization y el valor 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 debe usar la identidad del modelo del lado de OrcaRouter (el mismo nombre que usarías en /v1/video/generations), no el nombre de modelo desnudo de Kling. OrcaRouter lo resuelve a través del model_mapping del canal antes de reenviar a Kling.

El camino de obtención correspondiente es GET /kling/v1/videos/omni-video/{task_id} (o text2video, image2video). Elige el formato de cable que coincida con tu código existente. Ambos facturan idénticamente.

Véase también

Referencia API / Video — esquema completo con prueba en vivo (elige la variante Kling video request desde el desplegable de esquema del cuerpo)
Seedance Vídeo — el mismo endpoint, con modelos Seedance 1.0 / 1.5 / 2.0 y un cuerpo de solicitud en forma content[]
Operaciones / Facturación y uso
Operaciones / Errores

​Modelos

​Enviar una tarea

​Campos de metadatos comunes

​Consultar resultados

​Variantes de endpoint

​Texto-a-vídeo

​Imagen-a-vídeo

​Referencia multi-fuente (Omni-Video)

​Funciones avanzadas

​Multi-plano

​Audio nativo

​Marca de agua

​Facturación

​Usar el SDK Kling directamente

​Véase también

Modelos

Enviar una tarea

Campos de metadatos comunes

Consultar resultados

Variantes de endpoint

Texto-a-vídeo

Imagen-a-vídeo

Referencia multi-fuente (Omni-Video)

Funciones avanzadas

Multi-plano

Audio nativo

Marca de agua

Facturación

Usar el SDK Kling directamente

Véase también