Blog

Tutorial

Cómo llamar a kling-4.0-flash Reference-to-Video mediante la API de HiAPI: práctica con curl y Python

Práctica ejecutable de video a partir de múltiples imágenes de referencia, sondeo asíncrono y guía de diagnóstico

Nov 12, 2026
Imagen de portada: dos grandes bloques de color plano, uno lila claro y otro negro tinta, se encuentran a lo largo de un borde recto y definido, con una fina costura morada incrustada en el borde; la composición es contenida y serena.
Modelo
kling-4.0-flash
En esta página

Cuándo usar video a partir de imágenes de referencia en lugar de texto a video

El texto a video es la herramienta del guionista: describes una escena y el modelo lo crea todo de la nada. El video a partir de imágenes de referencia es la herramienta del director: le entregas al modelo una o varias imágenes y le pides que genere una imagen en movimiento en la que esos sujetos, estilos o composiciones sigan siendo reconocibles. En HiAPI, esta distinción se manifiesta a nivel de endpoint: kling-4.0-flash/reference-to-video es una ruta independiente de la llamada normal de texto a video; elegir el endpoint correcto desde el principio evita caer en una ingeniería de prompts que nunca logrará reproducir del todo una apariencia concreta.

Usa video a partir de imágenes de referencia cuando se cumpla cualquiera de estas condiciones:

  • La consistencia de identidad o de producto es crítica. Tienes hojas de personaje, fotos de producto o una mascota, y la salida no puede deformarse hasta convertirse en una figura genérica parecida.
  • Necesitas combinar varias fuentes. Una escena puede requerir una imagen para fijar al personaje y otra para fijar el entorno o el vestuario. Varias imágenes de referencia te permiten expresar esa composición de forma explícita en lugar de recurrir a la prosa descriptiva.
  • La transferencia de estilo es el objetivo. Quieres trasladar la tonalidad, la iluminación o el estilo de renderizado de las imágenes dadas a una imagen en movimiento.
  • Estás iterando sobre un plano. Las imágenes de referencia hacen que varias ejecuciones sean comparables, porque el anclaje visual permanece fijo y solo ajustas los parámetros relacionados con el movimiento.

Sigue usando texto a video cuando estés explorando conceptos, cuando no tengas imágenes con derechos claros que sirvan de anclaje, o cuando la necesidad sea en sí abstracta («una lenta toma aérea atravesando la niebla al amanecer») y cualquier interpretación razonable sea aceptable. Las imágenes de referencia limitan al modelo, y limitar solo resulta útil cuando realmente lo necesitas.

Una regla práctica: si te encuentras escribiendo un párrafo entero para describir el aspecto exacto de un objeto concreto, esa es la señal para cambiar a este endpoint y proporcionar la imagen directamente. Describir consume tokens y aun así se desvía; la imagen de referencia ancla.

Estructura de la solicitud: imágenes de referencia y parámetros principales

El endpoint acepta un cuerpo de solicitud JSON. Las partes con las que realmente vas a tratar se dividen en tres categorías: imágenes de referencia, prompt y parámetros que modelan la salida.

Imágenes de referencia

Las imágenes de referencia se pasan como un array, de modo que el mismo campo se amplía con naturalidad de una imagen a varias. Cada entrada es una URL que el servicio debe poder descargar. Restricciones prácticas a tener en cuenta al diseñar:

  • Usa URL HTTPS de acceso público, o URL a las que tu cuenta tenga acceso. Las rutas de archivo locales y los URI file:// no pueden descargarse desde un servicio remoto.
  • Prioriza el alojamiento estable frente a enlaces firmados que caducan a los pocos minutos: una tarea de larga duración puede intentar la descarga en un momento que no esperabas.
  • Mantén cada imagen enfocada. Una imagen limpia del sujeto resulta más útil que un collage recargado, porque el modelo necesita discernir lo que ve.
  • El orden puede influir en cómo se interpretan las imágenes de referencia, así que en el código mantén el orden del array determinista en lugar de depender del orden de iteración de un diccionario.

Prompt

Una vez proporcionadas las imágenes de referencia, el prompt debe describir movimiento, cámara y atmósfera, no la apariencia. Explica cómo se mueve el sujeto, cómo se mueve la cámara y qué sensación de ritmo tiene. Volver a describir las imágenes de referencia desperdicia presupuesto de prompt y puede entrar en conflicto con el anclaje que acabas de proporcionar.

Parámetros que modelan la salida

Además de prompt y del array de imágenes de referencia, el cuerpo de la solicitud suele incluir campos que controlan el formato de salida y el comportamiento de la generación. Trata estos campos como los últimos ajustes que tocar: primero haz que la llamada funcione con los valores predeterminados, confirma que las imágenes de referencia se respetan de verdad y, después, ajusta la configuración de salida. Los nombres de los campos y los valores permitidos están definidos en la documentación de referencia del endpoint; enviar campos no reconocidos es una causa habitual de rechazo del cuerpo de la solicitud, así que valida según el esquema de la documentación en lugar de adivinar.

El modelo mental es sencillo: las imágenes de referencia indican qué es, el prompt indica cómo se mueve y los parámetros indican qué recibes de vuelta.

Solicitud curl lista para usar

Antes de escribir código de cliente, la forma más fiable de comprobar el cuerpo de la solicitud es una llamada con curl. Define las credenciales y las entradas como variables de shell, mantén el JSON legible y envía la solicitud.

API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai"   # usa la URL base que muestra tu consola

curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "El personaje se gira hacia la ventana mientras la cámara se acerca lentamente; luz suave de mañana, ritmo tranquilo.",
    "reference_images": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/location-window.jpg"
    ]
  }'

Comprueba tres cosas antes de ejecutar:

  1. Ruta y prefijo de versión. Confirma la ruta exacta con la documentación de endpoints de tu cuenta; la ruta lleva número de versión y un prefijo obsoleto devolverá «no encontrado» en lugar de un error de validación.
  2. Cabecera de autenticación. La clave va como bearer token en la cabecera Authorization. No la pongas nunca en el cuerpo de la solicitud ni en la cadena de consulta, o se filtrará en los registros.
  3. Marcadores de posición. Todos los valores que hay que sustituir son marcadores evidentes: el comentario de la URL base, las dos URL de CDN y el prompt. Antes de declararlo listo para producción, busca example.com en la solicitud.

Un envío correcto devuelve un identificador de tarea, no el video terminado. Captura ese identificador del cuerpo de la respuesta; lo necesitarás en el siguiente paso de sondeo. Pasar la respuesta por un formateador JSON (| jq .) deja el ID de tarea a la vista, y merece la pena convertirlo en costumbre.

La misma llamada en Python

La diferencia principal de la versión Python está en cómo se construye el cuerpo de la solicitud: crea un dict, serialízalo una vez y separa la función de solicitud de la lógica de sondeo para poder probarlas por separado.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]

REFERENCE_IMAGES = [
    "https://your-cdn.example.com/refs/character-front.png",
    "https://your-cdn.example.com/refs/location-window.jpg",
]

def submit_reference_video(prompt: str) -> str:
    payload = {
        "prompt": prompt,
        "reference_images": REFERENCE_IMAGES,
    }
    response = requests.post(
        f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

if __name__ == "__main__":
    task_id = submit_reference_video(
        "El personaje se gira hacia la ventana mientras la cámara se acerca lentamente."
    )
    print("submitted:", task_id)

Estas precauciones evitan sufrimientos innecesarios:

  • Lee la clave de una variable de entorno. Una clave escrita directamente en el código acaba en el historial de git y en las capturas de pantalla.
  • Usa json= en lugar de data=, para que el cliente establezca correctamente el tipo de contenido y escape el cuerpo de la solicitud.
  • Define un timeout explícito. La espera infinita predeterminada convierte una conexión estancada en un proceso de trabajo colgado.
  • Llama a raise_for_status() antes de analizar la respuesta, para que un cuerpo 4xx se notifique como error HTTP en lugar de provocar un confuso KeyError al leer el JSON de la respuesta.
  • Confirma en la documentación el nombre del campo de respuesta que contiene el identificador de tarea en lugar de suponer que es task_id; ajusta en consecuencia la línea de extracción.

Haz que submit_reference_video solo devuelva el ID. El sondeo es una preocupación independiente y debe ir en su propia función.

Gestionar el ciclo de vida de una tarea asíncrona

La generación de video lleva tiempo, así que este endpoint está diseñado para ser asíncrono por naturaleza. La llamada de envío devuelve rápidamente un identificador de tarea; el trabajo real ocurre después. Tu integración debe modelarlo, y el modelo correcto más sencillo tiene tres estados: pending o processing (sigue esperando), succeeded (obtén la salida), failed (lee el error y detente).

Sondea el endpoint de tareas a intervalos y fija un límite al tiempo total de espera:

import time

def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    url = f"{BASE_URL}/v1/tasks/{task_id}"
    while time.monotonic() < deadline:
        r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")

Ajusta las cadenas de estado y la ruta de tareas según lo que indique la documentación; la estructura anterior solo es un patrón, y la mayoría de los fallos en este terreno provienen de suponer una etiqueta de estado que no existe.

Etiqueta de sondeo que conviene adoptar cuanto antes:

  • Retroceso gradual. Un intervalo fijo y corto satura la API repetidamente sin aportar nada. Empieza con un valor moderado y aumenta el tiempo de espera entre intentos.
  • Limita siempre el bucle. Un while True en torno a una tarea remota es una espera a que ocurra un fallo. El plazo límite anterior lanza una excepción en lugar de colgarse.
  • Persiste el ID de tarea. Si tu proceso se cae después del envío, ese ID es la única vía para recuperar el resultado sin pagar por una segunda generación.
  • Trata failed como estado terminal. No reintentes una tarea fallida volviendo a sondearla; lee el error y, si procede, vuelve a enviar el cuerpo de solicitud corregido.
  • Gestiona la caducidad de forma explícita. Es posible que los resultados de las tareas no estén disponibles para siempre, así que descarga y almacena la salida en cuanto la tarea tenga éxito.

Errores habituales y cómo solucionarlos

La mayoría de los fallos en una primera integración encajan en unas pocas categorías. Antes de cambiar el código, asocia el síntoma con la causa.

Fallos de autenticación y autorización

Un 401 o un 403 casi siempre significa credenciales incorrectas, ausentes o con el ámbito equivocado. Comprueba que la cabecera sea exactamente Authorization: Bearer <key>, que la variable de entorno esté realmente establecida en el proceso que hace la llamada (una exportación de shell no llega a una unidad de systemd) y que la clave no haya sido rotada o revocada.

Problemas con las imágenes de referencia

Si la solicitud se rechaza por una imagen, o si la generación ignora una imagen de referencia, la sospecha está en la URL. Verifica que el enlace se resuelva desde fuera de tu máquina: un nombre de host interno o una dirección localhost no son accesibles para el servicio. Comprueba la fecha de caducidad de las URL firmadas, comprueba que el archivo sea realmente una imagen y no una página de error HTML devuelta con estado 200, y revisa los límites de tamaño y formato. Una entrada defectuosa en un array de varias imágenes puede hacer fallar toda la solicitud, así que al depurar prueba las imágenes de referencia una a una.

Cuerpo de solicitud inválido

Un 400 con mensaje de validación suele significar que el cuerpo de la solicitud está mal formado: el nivel superior es un array en lugar de un objeto, falta un campo obligatorio, reference_images se envía como cadena entrecomillada en lugar de array, o un nombre de parámetro no se reconoce. Compara tu cuerpo de solicitud campo por campo con el esquema de la documentación y registra el cuerpo exacto que envías; a menudo el defecto es una diferencia de serialización entre la ruta de pruebas y la de producción.

Error de ruta o de método

Un 404 normalmente significa que la ruta es incorrecta, no que el modelo no esté disponible. Revisa el prefijo de versión y el nombre del endpoint en la documentación, y confirma que el envío usa POST y que la consulta del estado de la tarea usa GET.

Errores de timeout y de sondeo

Si el propio envío agota el tiempo de espera, aumenta moderadamente el timeout del cliente y reintenta; pero si la tarea ya se aceptó, no la reenvíes a ciegas, o pagarás por una generación duplicada. Si el sondeo nunca termina, es probable que tu comprobación de estado esté comparando la cadena equivocada; registra el valor de estado sin procesar en los primeros sondeos para ver qué se devuelve realmente.

Límites de velocidad

Un 429 significa que hay que bajar el ritmo. Respeta el intervalo indicado en lugar de reintentar de inmediato, y aplica un retroceso exponencial con jitter para que los procesos de trabajo paralelos no reintenten sincronizados.

Lista de comprobación de producción antes de publicar

Que el código funcione en un notebook no significa que la integración sea fiable. Antes de exponer este endpoint a los usuarios, refuerza los límites operativos.

  • Configuración. Guarda la URL base y la clave de API en variables de entorno o en un gestor de secretos, nunca en el código fuente. Define la ruta del endpoint como constante, para que actualizar la versión sea un cambio de una línea.
  • Reintentos con retroceso. Ante fallos transitorios —reinicios de conexión, 429, 5xx—, reintenta con retroceso exponencial y jitter. No reintentes errores de validación 4xx; fallarán de la misma forma.
  • Disciplina de idempotencia. Registra cada ID de tarea que envíes junto con sus entradas. Al reiniciar, reanuda el sondeo de las tareas existentes en lugar de enviar otras nuevas.
  • Espera acotada. Define timeouts explícitos tanto para el cliente HTTP como para el bucle de sondeo, y encamina los timeouts a una ruta de mensajes muertos que una persona pueda revisar, en lugar de descartarlos en silencio.
  • Registro estructurado. Registra los ID de tarea, las transiciones de estado con marca de tiempo, los tiempos de envío y finalización, y el cuerpo del error cuando se produzca un fallo. Oculta las claves y trunca el prompt cuando contenga datos de usuario.
  • Gestión de la salida. En cuanto la tarea tenga éxito, descarga el medio generado a tu propio almacenamiento y valida el resultado antes de mostrárselo al usuario.
  • Visibilidad de costes. La facturación varía con el uso, así que haz seguimiento de cuántas tareas se envían por funcionalidad y por usuario. Los bucles de reintento que reenvían ante la incertidumbre son la causa más habitual de gasto inesperado.
  • Higiene de entradas. Valida antes, en tu lado, las URL de referencia y la longitud del prompt. Detectar una URL defectuosa en local es más rápido y más barato que un viaje de ida y vuelta.

Hecho esto, la integración es una capa ligera y predecible: construir el cuerpo de la solicitud, enviar, sondear, almacenar. Empieza por la documentación de referencia del endpoint, ejecuta una vez el ejemplo con curl y traslada después el mismo cuerpo de solicitud a Python: una solicitud que funciona en el shell también funcionará en tu servicio.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API