API multitoma de Kling 3.0: guía de guiones gráficos

Q: ¿kling-v3-turbo admite el modo multitoma?

No. kling-v3-turbo admite sujetos, pero no shots. Use kling-v3 o kling-v3-omni para guiones gráficos.

Q: ¿Se pueden combinar sujetos con un guion gráfico personalizado?

Sí. Ponga el sujeto en subjects, haga referencia a él una vez en el prompt de nivel superior como >> y describa la acción en cada uno de los segments con palabras simples como "he" o "the man". El personaje se mantiene consistente entre tomas. kling-v3 también necesita un elemento images[] con "usage": "reference" cuando se usan sujetos.

Q: ¿Por qué se rechazó mi guion gráfico con "sum of shot durations must equal the total duration"?

Las duraciones de los segmentos deben sumar exactamente la duration de nivel superior. Defina siempre duration de forma explícita al escribir segmentos y no dependa del valor predeterminado.

Q: ¿Se pueden usar los parámetros nativos multi_shot o element_list de Kling?

No. HopBase acepta los campos estructurados shots y subjects. Los parámetros nativos extra.multi_shot, extra.multi_prompt, extra.shot_type y extra.element_list se rechazan con un mensaje que indica el campo estructurado correspondiente.

Respuesta corta: Kling 3.0 puede generar varias tomas en un solo clip, y se controlan mediante un objeto estructurado shots en la solicitud. En HopBase, el modo multitoma funciona en kling-v3 y kling-v3-omni; ambos producen clips de 3-15 segundos en 720p, 1080p, 2K o 4K. Hay dos modos. Con "mode": "intelligence", el modelo divide el prompt en tomas por sí mismo. Con "mode": "customize", usted escribe hasta 6 segmentos numerados. Cada segmento tiene su propio prompt de hasta 512 caracteres y dura al menos 1 segundo, y la suma de las duraciones de los segmentos debe coincidir exactamente con la duration de la solicitud. Para mantener el mismo personaje en todas las tomas, cree una vez un sujeto personalizado con POST /v1/kling/subjects, lo cual es gratuito. Después, pase su ID en subjects y haga referencia a él como <<<element_1>>> en el prompt. Las tomas y los sujetos no cambian el precio por segundo. Solo influyen la resolución, el audio y un video de referencia.

Qué modelos de Kling admiten tomas y sujetos

Modelo	Duración	Tomas (multitoma)	Sujetos	Imágenes de referencia
`kling-v3-omni`	3-15 s	Sí	Sí	Imágenes de referencia + sujetos ≤ 7 (≤ 4 con un video de referencia)
`kling-v3`	3-15 s	Sí	Sí, pero requiere al menos una imagen de referencia	Hasta 6
`kling-v3-turbo`	3-15 s	No	Sí	No

Los modelos de Kling anteriores (o1, 2.6, 2.5 Turbo, 2.1, 1.6) no admiten ninguna de las dos funciones. Si se les envía shots, devuelven model ... does not support shots (multi-shot storyboard). Confirme siempre los IDs de modelo a los que puede acceder su clave con GET /v1/models.

El objeto shots

Todas las solicitudes se envían a POST https://api.hop-base.com/v1/video/generate. El modo multitoma añade un campo, shots, con estas reglas:

mode es intelligence o customize.
En el modo intelligence, omita segments. El modelo decide dónde cortar.
En el modo customize, segments es obligatorio: como máximo 6, con index numerado 1, 2, 3 y así sucesivamente, sin saltos.
El prompt de cada segmento no puede estar vacío y puede tener como máximo 512 caracteres.
La duration de cada segmento es de al menos 1 segundo, y las duraciones deben sumar exactamente la duration de nivel superior. Defina siempre duration de forma explícita cuando use segmentos.
Use el objeto estructurado shots. Los parámetros nativos de Kling extra.multi_shot, extra.shot_type y extra.multi_prompt se rechazan.

Modo intelligence: el modelo decide los cortes

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "A barista grinds coffee, pours latte art, then slides the cup across the counter to a smiling customer",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": { "mode": "intelligence" }
  }'

Modo customize: escriba usted mismo el guion gráfico

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "A 10-second product story for a pair of trail running shoes",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": {
      "mode": "customize",
      "segments": [
        { "index": 1, "prompt": "Wide shot: a runner laces up the shoes at a misty trailhead at dawn", "duration": 3 },
        { "index": 2, "prompt": "Low tracking shot: the shoes hit wet rocks, water splashes in slow motion", "duration": 3 },
        { "index": 3, "prompt": "Close-up: the runner stops on a ridge, sunlight on the shoe logo", "duration": 4 }
      ]
    }
  }'

3 + 3 + 4 = 10, que coincide con duration. Si los números no coinciden, la solicitud se rechaza antes de crear la tarea, con sum of shot durations (9 s) must equal the total duration (10 s), y no se le cobra.

Mantener un mismo personaje en todas las tomas con sujetos personalizados

Cuando una historia corta entre tomas, lo difícil es que el personaje se vea igual en cada una. Kling lo resuelve con sujetos (subjects): un personaje u objeto guardado que se crea una vez a partir de material de referencia y luego se reutiliza por su ID.

Paso 1: crear el sujeto (gratuito, asíncrono)

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Luna mascot",
    "description": "Orange fox mascot wearing a blue hoodie",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/luna-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/luna-side.png",
      "https://cdn.example.com/luna-back.png"
    ]
  }'

image_refer requiere una imagen frontal más 1-3 imágenes de referencia adicionales. No deben repetir la imagen frontal ni repetirse entre sí.
video_refer crea el sujeto a partir de un único video_url y, opcionalmente, puede asociar un voice_id. Los dos métodos no pueden combinarse en una misma solicitud.
name admite hasta 20 caracteres y description hasta 100. Todas las URL deben ser direcciones http(s) públicas.

La llamada devuelve 202 con un id (su object es kling.subject.task). Consúltelo como cualquier tarea de video con GET /v1/video/tasks/{task_id}. Al completarse, el resultado incluye element_ids: esos son los IDs de sus sujetos. GET /v1/kling/subjects lista todos los sujetos que ha creado. Actualmente, crear un sujeto es gratuito.

Paso 2: usar el sujeto en una solicitud multitoma

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "Medium shot: <<<element_1>>> sits on a sofa holding a red gift box. Then a close-up: <<<element_1>>> lifts the lid and its eyes light up",
    "duration": 8,
    "resolution": "1080p",
    "subjects": [{ "id": "subject-92951593344", "name": "luna" }],
    "shots": { "mode": "intelligence" }
  }'

Cómo funcionan las referencias a sujetos:

Los sujetos se asocian por posición. subjects[0] es <<<element_1>>>, subjects[1] es <<<element_2>>>, y así sucesivamente.
Cada sujeto que envíe debe estar referenciado en el prompt de nivel superior. De lo contrario, recibirá subjects[0] is not referenced in prompt as <<<element_1>>>.
Hacer referencia a un sujeto que no se envió, como <<<element_3>>> cuando solo se enviaron dos, también se rechaza.
En kling-v3, una solicitud con sujetos también necesita al menos un elemento images[] con "usage": "reference". Sin él, se rechaza al enviarla, antes de que la solicitud llegue a Kling.
El ejemplo usa el modo intelligence porque en ese caso el prompt de nivel superior es el guion de todas las tomas, de modo que el token del sujeto queda donde el modelo lo lee. Los sujetos también funcionan con los segments del modo customize. En nuestra prueba con kling-v3-omni, el prompt de nivel superior hacía referencia a <<<element_1>>> una vez y cada segmento solo decía "the man"; ambas tomas mostraron el mismo sujeto, con el mismo rostro, lentes, bata de laboratorio y corbata roja. La referencia debe estar en el prompt de nivel superior: ponerla solo en segments se rechaza al enviar con subjects[0] is not referenced in prompt as <<<element_1>>>. En una prueba comparativa, repetir <<<element_1>>> en cada segmento colocó dos copias del personaje en la primera toma (una caminando y otra ya sentada en el banco), mientras que la versión con descripciones simples en los segmentos no lo hizo. Haga referencia al sujeto una vez en el nivel superior, descríbalo con palabras simples en cada segmento y genere una prueba corta en 720p antes de escalar.

Consulta del estado y resultados

Todas estas operaciones son asíncronas. El envío devuelve 202 con un ID de tarea como kt57x… y un billing_bucket, y se consulta GET /v1/video/tasks/{task_id} hasta que status sea completed o failed:

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Una tarea completada incluye outputs, una URL firmada en api.hop-base.com válida durante 24 horas desde su finalización, y usage con billed_seconds y cost_usd (el importe efectivamente descontado). Una tarea fallida tiene un error.code estable, como input_sensitive, invalid_request, generation_failed o timeout, y nunca se cobra. Las tareas que no terminan en 2 horas se marcan automáticamente como fallidas. Referencia completa de campos: documentación de la API de video de Kling.

Cuánto cuesta el modo multitoma

Kling cobra por segundo de salida según la tarifa del modelo, la resolución y si el clip es sin audio, con audio o usa un video de referencia. Las tomas, los sujetos y las imágenes de referencia no aumentan el precio. Algunos precios oficiales de lista según las fichas de los modelos:

Modelo · nivel	720p	1080p	2K
`kling-v3` · sin audio	$0.0882 / s	$0.1176 / s	$0.1471 / s
`kling-v3` · con audio	$0.1324 / s	$0.1765 / s	$0.2206 / s
`kling-v3-omni` · sin audio, sin video de referencia	$0.0882 / s	$0.1176 / s	$0.1471 / s
`kling-v3-omni` · con audio, sin video de referencia	$0.1176 / s	$0.1471 / s	$0.1765 / s

Así, el ejemplo de 10 segundos en modo customize anterior (kling-v3-omni, 1080p, con audio) cuesta 10 × $0.1471, unos $1.47 a precio de lista. Los niveles 4K y los niveles con video de referencia figuran en las fichas de los modelos kling-v3 y kling-v3-omni. La página de precios muestra los mismos niveles en CNY, por ejemplo kling-v3 1080p con audio a ¥1.20 por segundo. Su tarifa real depende de su grupo.

Consejos para mejores guiones gráficos

Escriba cada segmento como una entrada de una lista de tomas. Empiece por el encuadre ("Wide shot", "Close-up", "Low tracking shot") y luego la acción. Funciona mejor una sola acción por segmento.
Dé al menos 2 segundos a los momentos breves. El mínimo es 1 segundo, pero los segmentos muy cortos dejan poco margen para el movimiento.
Haga prototipos en modo intelligence a 720p y, cuando la historia funcione, pase al modo customize y a una resolución mayor. El costo crece con los segundos × el nivel de resolución.
Active el audio solo cuando lo necesite. En kling-v3 a 1080p, el audio eleva la tarifa de $0.1176 a $0.1765 por segundo.

Preguntas frecuentes

¿Cuántas tomas puede tener un clip de Kling 3.0?

Hasta 6 segmentos personalizados en el modo customize, dentro de una duración total del clip de 3-15 segundos. En el modo intelligence, el modelo decide por sí mismo el número de tomas.

¿kling-v3-turbo admite el modo multitoma?

No. kling-v3-turbo admite sujetos, pero no shots. Use kling-v3 o kling-v3-omni para guiones gráficos.

¿Las tomas o los sujetos tienen un costo adicional?

No. El precio por segundo depende del modelo, la resolución, el audio y de si hay un video de referencia. Actualmente, crear un sujeto personalizado es gratuito.

¿Se pueden combinar sujetos con un guion gráfico personalizado?

Sí. Ponga el sujeto en subjects, haga referencia a él una vez en el prompt de nivel superior como <<<element_1>>> y describa la acción en cada uno de los segments con palabras simples como "he" o "the man". El personaje se mantiene consistente entre tomas. kling-v3 también necesita un elemento images[] con "usage": "reference" cuando se usan sujetos.

¿Por qué se rechazó mi guion gráfico con "sum of shot durations must equal the total duration"?

Las duraciones de los segmentos deben sumar exactamente la duration de nivel superior. Defina siempre duration de forma explícita al escribir segmentos y no dependa del valor predeterminado.

¿Se pueden usar los parámetros nativos multi_shot o element_list de Kling?

No. HopBase acepta los campos estructurados shots y subjects. Los parámetros nativos extra.multi_shot, extra.multi_prompt, extra.shot_type y extra.element_list se rechazan con un mensaje que indica el campo estructurado correspondiente.

¿Cómo empezar?

Cree una clave en la consola de HopBase con un grupo que incluya los modelos de Kling, compruebe en GET /v1/models que aparecen kling-v3 o kling-v3-omni y empiece con el ejemplo del modo intelligence anterior. Para otro tipo de control, en el que una persona reproduce el movimiento de un video, consulte nuestra guía de la API de control de movimiento de Kling.