Kling: API de generación de video

Kling genera video a partir de texto, imágenes, videos y sujetos, y también admite control de movimiento, avatar y sincronización labial: envíe una tarea y luego consulte el ID de tarea de HopBase para obtener el resultado.

La generación y la expansión de imágenes de Kling también son tareas asíncronas: envíe con POST /v1/images/generations y consulte GET /v1/video/tasks/{task_id}. Los modelos, parámetros, respuestas y errores están en Imágenes con Kling.

Modelos disponibles

Antes de enviar trabajo de pago, confirme los IDs exactos de modelo que devuelve su clave con GET /v1/models.

Una combinación de resolución / audio fuera de esta tabla se rechaza en el envío con 400. Los niveles de precio y las especificaciones completas de cada modelo están en su ficha, por ejemplo kling-v3, kling-v3-omni y kling-lip-sync.

• kling-v3-turbo usa el nivel de precio de voz fijo de Kling: audio no cambia el precio y los llamadores no pueden elegir una voz.
• kling-v3-omni con un video de referencia feature es solo silencioso, en 720p / 1080p / 2k.
• kling-o1 sin entradas de referencia solo admite 5 o 10 segundos.
• kling-v2-6 con audio empieza en 1080p; el 720P con audio no tiene precio.
• Una edición de video base de kling-v1-6 ignora audio.

Matriz de modelos

Entradas admitidas por modelo de video:

• "Imágenes de referencia" solo cuenta usage: reference, no los fotogramas primero/último ni la longitud total de images[].
• En kling-v3-omni, base no tiene precio, y una solicitud feature silenciosa en 4K no tiene precio.
• La edición de video base de kling-v1-6 usa el precio de multi_elements.

Parámetros de la solicitud

Todas las solicitudes usan Authorization: Bearer sk-tu-clave y Content-Type: application/json. El cuerpo se decodifica de forma estricta: solo se aceptan los campos indicados en esta página. Un campo fuera de esas listas, un campo desconocido dentro de un objeto anidado o un segundo valor JSON tras el cuerpo devuelven 400 antes de crear ninguna tarea, y no se factura nada.

• Kling comprueba la longitud de prompt durante la tarea.
• Cualquier clave de extra en un modelo de video ordinario devuelve 400.
• Defina el encuadre del video con resolution y aspect_ratio; no envíe size, response_format ni user por costumbre de OpenAI, n en una solicitud de video, ni image_url / video_url en el nivel superior.

Todos los campos de video figuran en la referencia de la API, en Enviar una tarea de video (elija Kling).

Localizadores de medios

Cada elemento de images[] o videos[] debe contener exactamente uno de url o file_id:

{ "url": "https://cdn.example.com/file.png" }

{ "file_id": "your-file-id" }

url debe ser una URL http:// o https:// absoluta y accesible públicamente. La misma regla aplica al endpoint de imágenes, la detección de rostros y el extra.sound_file del avatar. Estos casos se rechazan de forma síncrona en el envío:

• Cadenas vacías o rutas relativas.
• Esquemas que no son HTTP(S), como file:// o ftp://.
• Direcciones privadas, loopback o link-local.
• URLs con credenciales incrustadas.
• url y file_id a la vez.

Texto e imagen a video

Los modelos de video ordinarios admiten texto a video, primer/último fotograma, imágenes de referencia, video de referencia y edición de video. Ponga las imágenes en images[] y los videos en videos[]; enviar solo un prompt es texto a video.

El usage de cada imagen define su función: first_frame, last_frame o reference.

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> y <<<element_2>>> giran lentamente sobre una mesa de estudio limpia",
  "duration": 5,
  "resolution": "1080p",
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "last-frame-file-id", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" }
  ]
}

• Puede haber como máximo un primer fotograma y un último fotograma.
• Un último fotograma requiere un primer fotograma.
• No se admite un último fotograma con más de dos imágenes reference.
• Con kling-v2-1, proporcionar tanto el primer como el último fotograma restringe resolution a 1080p.
• Los límites de imágenes de referencia están en la tabla de modelos y solo cuentan usage: reference.

Hay como máximo un elemento en videos[], y debe llevar reference_type:

{
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ]
}

• feature es un video de referencia; solo lo aceptan kling-v3-omni y kling-o1.
• base es una edición de video; solo lo acepta kling-v1-6, probado y con precio.
• Un video base debe ser la única entrada de medios y no puede combinarse con imágenes o sujetos.
• keep_original_sound es un booleano que conserva la pista de audio del video de origen.

Sujetos y tomas

subjects[] usa IDs de sujeto fijos. Los sujetos solo son compatibles con kling-v3-turbo, kling-v3 y kling-v3-omni.

{
  "subjects": [
    { "id": "subject-92951593344", "name": "gato" },
    { "id": "subject-92951593345", "name": "perro" }
  ]
}

• Cada elemento requiere un id no vacío; name es opcional.
• Los elementos son posicionales: subjects[0] es <<<element_1>>>, y así sucesivamente.
• Todo sujeto proporcionado debe referenciarse en el prompt.
• El prompt no debe referenciar un <<<element_N>>> que no exista.
• Para kling-v3, los sujetos también requieren al menos un elemento de images[] con usage: "reference".

Las tomas solo son compatibles con kling-v3 y kling-v3-omni:

{
  "model": "kling-v3-omni",
  "prompt": "Una breve historia de producto en dos tomas",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "La caja se abre", "duration": 2 },
      { "index": 2, "prompt": "El producto se revela", "duration": 3 }
    ]
  }
}

• mode es intelligence o customize.
• El modo intelligence debe omitir segments; el modo customize los requiere.
• Puede haber como máximo 6 segmentos personalizados, numerados consecutivamente desde 1.
• El prompt de cada segmento no puede estar vacío y tiene como máximo 512 caracteres.
• Cada segmento dura al menos un segundo, y las duraciones deben sumar exactamente la duración de la solicitud.
• Use shots estructurado; extra.multi_shot, extra.shot_type y extra.multi_prompt en bruto se rechazan.

Crear un sujeto personalizado

POST /v1/kling/subjects crea un sujeto personalizado cuyo ID puede usar en subjects[].id. GET en la misma ruta lista los sujetos existentes.

• image_refer crea el sujeto a partir de imágenes; video_refer, a partir de un video.
• Todas las URL deben ser URL HTTP(S) públicas según las reglas de «Localizadores de medios».
• reference_image_urls no puede repetir la imagen frontal ni repetirse entre sí.
• video_refer no admite campos de imagen, e image_refer no admite video_url.
• tag_ids clasifica el sujeto; cada etiqueta no puede estar vacía y debe ser única.

La creación es una tarea asíncrona: el envío devuelve 202 con un id (object es kling.subject.task); consúltela con GET /v1/video/tasks/{task_id}. El resultado completado incluye element_ids y elements.

Control de movimiento

El control de movimiento hace que una imagen de persona siga el movimiento de un video. Requiere exactamente un video y una imagen de persona, y la duración proviene de los medios de entrada, por lo que debe omitir duration.

{
  "model": "kling-v3-motion-control",
  "prompt": "Sigue el movimiento del bailarín",
  "resolution": "1080p",
  "images": [{ "file_id": "person-image-file-id" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

• La escena fija la función de cada entrada, por lo que la imagen no lleva usage y el video no lleva reference_type.
• videos[].keep_original_sound es un booleano y se mapea al indicador keep_original_sound de Kling.
• El único parámetro adicional actualmente verificado es extra.character_orientation (image o video).
• La salida es temporal.

Avatar

Avatar (kling-avatar) hace que una imagen de persona hable una pista de audio. La duración proviene del audio de entrada, por lo que debe omitir duration.

• Requiere de 1 a 5 imágenes de persona y no acepta videos.
• Requiere exactamente uno de extra.sound_file (una URL de audio HTTP(S)) o extra.audio_id.

Sincronización labial

La sincronización labial (kling-lip-sync) da nuevos movimientos de boca a un rostro de un video y no acepta imágenes ni videos. Tiene dos pasos: detectar los rostros y luego enviar la tarea.

Primero, llame a la detección de rostros con uno o más localizadores de medios. El cuerpo solo acepta un arreglo videos, cada elemento con exactamente uno de url / file_id según las reglas de «Localizadores de medios».

curl https://api.hop-base.com/v1/kling/faces \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"source-video-file-id"}]}'

Luego envíe la sesión devuelta con un elemento face_choose:

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

• face_choose debe contener exactamente un elemento con un face_id y un sound_file no vacíos.
• El audio/video de origen determina la duración, por lo que debe omitir duration.
• voice_ids y extra.voice_list en bruto siguen sin estar disponibles hasta que se confirme una capacidad de Kling correspondiente.

Respuesta

Los campos de la tarea de Kling van en el nivel superior de la respuesta; no van envueltos en task como en Seedance.

Respuesta del envío

Un envío exitoso devuelve 202 con el ID de tarea en id, con la forma kt57x<task-id>. Las tareas de imagen de Kling también devuelven 202 con un id de la misma forma, y ambas se consultan igual.

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "720p_silent_noref"
}

Campos de la consulta

Trate cualquier valor distinto de completed y failed como en curso. No envíe un encabezado de facturación al consultar.

Cuando la tarea termina, el objeto usage de la raíz de la consulta también incluye cost_usd —el importe en USD realmente descontado de su saldo por esta tarea, 0 si falló sin cargo—, cost (el mismo cargo en CNY) y currency (siempre CNY); consulte Resumen de video. En la lista de tareas (GET /v1/video/tasks), cada tarea finalizada lleva los mismos cost, cost_usd y currency en su usage.

En curso

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "processing",
  "created": 1790000000
}

Completada

Una tarea completada incluye las URL de salida en outputs:

{
  "id": "ktEXAMPLE",
  "status": "completed",
  "outputs": [
    "https://api.hop-base.com/example-signed-image.png"
  ],
  "usage": { "bucket": "720p_silent_noref", "billed_seconds": 5, "cost": 2.55, "cost_usd": 0.375, "currency": "CNY" }
}

Las URL se sirven desde api.hop-base.com y son enlaces firmados válidos por 24 horas desde el momento en que la tarea se completa. Consultar de nuevo devuelve la misma URL sin extenderla, y un enlace vencido devuelve 410, así que descargue los resultados dentro de esa ventana.

Fallida

Una tarea fallida sigue respondiendo a la consulta con HTTP 200 y status failed. error.code es un código de error estable, y error.message lo explica con una redacción fija en inglés.

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "failed",
  "created": 1790000000,
  "error": {
    "code": "timeout",
    "message": "task did not reach a billable terminal state within 2 hours; polling stopped"
  }
}

Decida el éxito o el fallo por status, ramifique su lógica por error.code y muestre error.message. Las tareas que fallaron hace tiempo pueden no tener error.code.

Ejemplo mínimo

Esto envía una tarea de texto a video de 5 segundos en 720p y la consulta hasta que termina.

# 1. Enviar
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "Una pelota roja rueda sobre una mesa blanca",
    "duration": 5,
    "resolution": "720p"
  }'

# 2. Consultar con el id devuelto
curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-tu-clave"

Notas

• Una tarea de Kling, incluidas las de imagen, que sigue sin terminar 2 horas después de crearse se marca como fallida y no se factura.
• Las tareas no se pueden cancelar; para las demás reglas comunes a todas las familias de video, consulte Resumen de video.
• Los enlaces de resultado son válidos 24 horas desde que se completa la tarea y no se extienden.
• Control de movimiento, avatar y sincronización labial toman la duración de los medios de entrada, por lo que debe omitir duration.

Reserva de saldo

La falta de saldo lleva code insufficient_balance, y la estimación se libera automáticamente al finalizar la tarea. La sincronización labial (kling-lip-sync) no se puede estimar de antemano y no reserva nada.

Errores comunes y soluciones

Un error en el envío no crea ninguna tarea ni factura nada; error.message explica el motivo. Un 400 tiene type invalid_request_error; un 402 tiene code insufficient_balance.

El error exacto cuando se envía un campo como size (el endpoint de detección de rostros devuelve el mismo):

{
  "error": {
    "message": "request body does not match the JSON contract: json: unknown field \"size\"",
    "type": "invalid_request_error"
  }
}

El error.message literal de los demás casos:

# Un modelo de imagen enviado al endpoint de video (400)
model "<ID de modelo>" is an image model; use /v1/images/generations

# ID de modelo de video fuera del catálogo (404)
model "<ID de modelo>" is not in the Kling catalog

# ID de modelo de imagen fuera del catálogo (404)
model "<ID de modelo>" is not an image model in this catalog

Medios y parámetros comunes

# Medio sin url / file_id o con ambos
<images o videos>[<índice>] must provide exactly one of url or file_id

# url que no es una dirección http(s) pública y absoluta
<images o videos>[<índice>].url must be a publicly accessible absolute http(s) URL

# Sin prompt ni medios (salvo sincronización labial)
prompt and input media cannot both be empty

# duration negativa
duration cannot be negative

# duration fuera del rango del modelo
model <ID de modelo> supports <mín> to <máx> seconds, got <valor>

# kling-o1 sin entradas de referencia y una duración distinta de 5 o 10
Kling O1 without reference media only supports duration 5 or 10 seconds

# kling-v2-6 con una duración distinta de 5 o 10
model kling-v2-6 only supports a duration of 5 or 10 seconds, got <valor>

# aspect_ratio distinto de 16:9 / 9:16 / 1:1
aspect_ratio="<valor>" is invalid; allowed values: 16:9 / 9:16 / 1:1

# Sin nivel de precio para la combinación de resolución / audio / video de referencia
model "<ID de modelo>" does not support billing bucket "<nivel>" for this request

# voice_ids no vacío (el mensaje empieza así)
voice_ids is not available yet

# Una clave de extra que el modelo no acepta
extra.<clave> is not in the verified parameter contract of model <ID de modelo>

# duration en un modelo cuya duración viene de la entrada
duration of model <ID de modelo> is determined by the input media; do not pass duration

Primer/último fotograma, imágenes de referencia y video de referencia

# usage ausente o no válido
images[<índice>].usage is required for standard Kling video requests
images[<índice>].usage="<valor>" is invalid; allowed values: first_frame / last_frame / reference

# Reglas de primer y último fotograma
at most 1 first-frame image is allowed
at most 1 last-frame image is allowed
a last frame requires a first frame with usage=first_frame
Kling 2.1 first/last-frame generation only supports 1080p
a last frame is not supported with more than 2 reference images (got <cantidad>)

# Número de imágenes de referencia
with a reference video, reference images + subjects cannot exceed 4, got <total> (<imágenes> images + <sujetos> subjects)
without a reference video, reference images + subjects cannot exceed 7, got <total> (<imágenes> images + <sujetos> subjects)
model <ID de modelo> supports at most <máx> reference images, got <cantidad>
model <ID de modelo> does not support reference-based generation

# reference_type ausente o no válido, o más de 1 video
videos[0].reference_type is required for standard Kling video requests; allowed values: feature / base
videos[<índice>].reference_type="<valor>" is invalid; allowed values: feature / base
standard Kling video requests accept at most 1 videos input

# Tipo de video de referencia no admitido por el modelo, o base combinado con imágenes / sujetos
model <ID de modelo> has no confirmed feature reference-video capability or price tier
model <ID de modelo> has no confirmed base video-edit price tier
base video edit cannot be combined with images or subjects; only a single video to edit is accepted

# Parámetro de sonido original dentro de extra
extra.keep_original_sound cannot be passed through; use videos[].keep_original_sound

# Sujetos
subjects[<índice>].id is required (Kling fixed subjects must carry an Id)
model <ID de modelo> does not support subjects (fixed subjects)
model <ID de modelo> requires at least 1 image with usage=reference when subjects are used
prompt references "<<<element_N>>>" but no subjects were provided
prompt references "<<<element_N>>>" but subjects only has <cantidad> items
subjects[<índice>] is not referenced in prompt as <<<element_<N>>>>

# Tomas
model <ID de modelo> does not support shots (multi-shot storyboard)
shots.mode="<valor>" is invalid; allowed values: intelligence / customize
shots.mode=customize requires segments
shots.mode=intelligence does not accept segments; shots are generated by the model
at most 6 shot segments are allowed, got <cantidad>
shots.segments[<índice>].index must be numbered consecutively from 1, got <valor>
shots.segments[<índice>].prompt cannot be empty
shots.segments[<índice>].prompt exceeds 512 characters
shots.segments[<índice>].duration must be at least 1 seconds
sum of shot durations (<suma> s) must equal the total duration (<total> s)

# Parámetros de tomas o sujetos dentro de extra
extra.<clave> cannot be passed through; use the structured shots parameter
extra.element_list cannot be passed through; use the structured subjects parameter

Control de movimiento, avatar y sincronización labial

# Control de movimiento
motion control requires exactly 1 motion video and 1 character image
motion control images[<índice>] does not accept usage; the character image role is fixed by the scene
motion control videos[<índice>] does not accept reference_type; the motion video role is fixed by the scene
extra.character_orientation must be image or video

# Avatar
Kling avatar requires at least 1 character image
model <ID de modelo> supports at most 5 character images, got <cantidad>
Kling avatar does not accept videos input
Kling avatar requires exactly one of extra.sound_file or extra.audio_id
extra.sound_file must be a non-empty string
extra.audio_id must be a non-empty string
extra.sound_file must be a publicly accessible http(s) audio URL

# Detección de rostros: JSON no válido o cualquier otro campo
request body does not match the JSON contract: …

# Detección de rostros: videos ausente o vacío
videos is required and must contain at least one item

# Sincronización labial
Kling lip-sync does not accept images or videos; use extra.session_id and extra.face_choose
Kling lip-sync requires a non-empty extra.session_id
Kling lip-sync requires an extra.face_choose array with exactly 1 item
extra.face_choose[0].<clave> is not part of the lip-sync contract
extra.face_choose[0].face_id must be a non-empty string or a non-negative integer
extra.face_choose[0].sound_file must be a non-empty string
extra.face_choose[0].sound_file must be a publicly accessible http(s) audio URL
extra.voice_list is reserved; use voice_ids instead (voice selection is not available yet)

Tareas fallidas

Las causas habituales son medios que no cumplen las especificaciones oficiales de Kling (resolución, formato, tamaño, duración) o un rechazo de la moderación de contenido. Cada mensaje indica qué hacer a continuación; tras cualquiera de los dos tiempos agotados de 2 horas, vuelva a enviarla. Una tarea fallida nunca se factura.

A continuación, los valores literales de error.message de las tareas de video. Las tareas de imagen dicen image generation y reference image; los sujetos personalizados, subject creation.

# input_sensitive: prompt rechazado por la moderación
the prompt was rejected by content moderation; rephrase it and submit again

# input_sensitive: medios de referencia rechazados por la moderación
the reference media was rejected by content moderation; replace it and submit again

# input_sensitive: moderación sin indicar el origen
the prompt or reference media was rejected by content moderation; revise it and submit again

# output_video_sensitive / safety_rejected: resultado bloqueado por la moderación
the generated result was blocked by content moderation; adjust the prompt or reference media and submit again

# rate_limited: techo de concurrencia alcanzado
this model is at its concurrency limit right now; please retry shortly

# unsupported_model: versión del modelo retirada
this model version is no longer available; switch to another model and submit again

# invalid_request: prompt demasiado largo
the prompt is too long for this model (at most 2500 characters); shorten it and submit again

# invalid_request: parámetros o medios rechazados
the request was rejected as invalid by the model; check the parameters and media against the documented limits, then submit again

# reference_input_invalid: medios de referencia ilegibles
a reference image or video is missing or could not be read; make sure every URL is publicly reachable and points to a supported file, then submit again

# generation_failed: fallo de generación (otros)
video generation failed; please retry, and contact support with the task ID if it keeps failing

# generation_failed: detenida antes de terminar
video generation was stopped before it finished; please retry, and contact support with the task ID if it keeps failing

# generation_failed: no se pudo seguir la tarea (termina así)
… contact support with the task ID

# timeout: sin terminar 2 horas después de crearse
task did not reach a billable terminal state within 2 hours; polling stopped

# timeout: sujeto personalizado sin terminar tras 2 horas
subject task did not reach a terminal state within 2 hours; polling stopped

# no_output: la tarea terminó sin salida
video generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing

# no_output: el sujeto personalizado terminó sin ID de sujeto
subject creation finished without returning a subject ID; check the media and create it again

Facturación

Kling factura la generación de video por segundo de video de salida, a la tarifa de la resolución del modelo y de su variante sin audio / con audio / con video de referencia, no por token de video. Solo se factura una tarea que se completa correctamente; una tarea fallida nunca se factura.

• La detección de rostros (POST /v1/kling/faces) se factura por llamada.
• Crear un sujeto personalizado es gratuito por ahora.
• Para la facturación de imágenes, consulte Imágenes con Kling.

Los precios de lista oficiales están en la página de precios. Su tarifa es la que aparece en el catálogo de modelos con la sesión iniciada, y el cargo real de cada solicitud está en su registro de uso.

Próximos pasos

• Resumen de video: compare las familias de video y el flujo de tareas que comparten
• Imágenes con Kling: generación y expansión de imágenes de Kling
• Estudio creativo: genere imágenes y video sin escribir código
• Modelos disponibles: consulte los ID de modelo disponibles para una clave
• Solución de problemas: busque un mensaje de error