Blog

Tutorial

Cómo llamar a kling-3.0-omni/transformation mediante la API de HiAPI: guía con curl y Python

Un recorrido completo por solicitudes funcionales para la conversión de estilo de video en HiAPI

Nov 12, 2026
Imagen de portada del blog de HiAPI: flechas anchas anidadas sobre un fondo azul añil oscuro avanzan en forma de escalera, con el borde delantero en color albaricoque que ilustra el flujo de señal.
En esta página

Qué hace el endpoint transformation y cuándo usarlo

kling-3.0-omni/transformation es el endpoint de conversión de estilo de video en HiAPI. Le proporcionas dos cosas: un video de origen y una instrucción de estilo en lenguaje natural. Devuelve un nuevo video en el que se conserva el contenido del video de origen, pero se presenta con el estilo visual solicitado.

Piensa en él como un paso de postproducción oculto detrás de una llamada HTTP. No necesitas entrenar modelos, mantener clústeres de GPU ni gestionar archivos de checkpoint. Describes el efecto visual deseado, apuntas a un video y el endpoint produce el resultado renderizado.

Escenarios en los que este endpoint es adecuado

  • Añadir estilo a material existente. Ya tienes una toma y quieres que se vea como animación, acuarela, grano de película, plastilina u otro efecto. El contenido y el movimiento provienen de tu video; el endpoint lo que cambia es la textura de la superficie.
  • Mantener un estilo coherente en lote. Como el estilo se expresa mediante una instrucción, puedes reutilizar el mismo prompt en muchos videos de origen y obtener un conjunto de resultados con un estilo coherente.
  • Prototipar el desarrollo de estilos. Los equipos creativos pueden iterar direcciones de estilo a bajo costo antes de comprometerse con flujos de producción más pesados.

Escenarios en los que no es adecuado

  • Necesitas generar video desde cero (texto a video es otra tarea).
  • Necesitas edición, montaje o composición precisos fotograma a fotograma. La transformación solo remodela el estilo; no edita.
  • Tu material de origen solo contiene audio o es una imagen estática.

El resto de esta guía explica paso a paso la estructura de la solicitud, una llamada curl lista para ejecutar, la versión equivalente en Python y los detalles operativos en torno a la salida 4K y las tareas de larga duración.

Análisis de la solicitud: video de origen, instrucción de estilo y opciones de salida

Una solicitud de transformación no es compleja. Antes de escribir código, divídela en tres grupos de campos: video de origen, instrucción y ajustes de salida.

Video de origen

El endpoint necesita poder acceder a tu entrada. En la práctica, pasas una URL que la plataforma pueda recuperar, o un identificador devuelto por el paso de carga de archivos de HiAPI. La regla práctica es: el archivo de origen debe ser accesible desde el servidor, no desde tu portátil. Una ruta localhost o un archivo detrás de tu VPN no funcionarán.

El formato de origen debe ser conservador: usa contenedores y códecs ampliamente compatibles. Si tu video lo generó un proceso especial y no pasa la validación, recodifícalo primero a MP4 H.264 estándar. Ese paso por sí solo resuelve una buena parte de los errores de entrada.

Instrucción de estilo

Es la descripción en lenguaje natural del efecto visual objetivo. Es el campo de mayor impacto en la solicitud y el que más merece la pena pulir.

  • Describe el tratamiento visual, no el contenido. El contenido proviene del video; decirle al modelo lo que ya hay en pantalla solo desperdicia el presupuesto del prompt.
  • Sé específico sobre el medio y la textura: «animación stop-motion en plastilina con huellas dactilares visibles» comunica mucho más que «animación».
  • Indica explícitamente qué conservar cuando sea importante: «mantén los rostros reconocibles y el movimiento de cámara sin cambios».
  • Manténlo dentro de un párrafo enfocado. Los prompts largos y contradictorios suelen promediarse en resultados insípidos.

Opciones de salida

Los ajustes de salida controlan la resolución y otros detalles de entrega. La decisión principal es solicitar 4K o resolución estándar. Una resolución más alta consume más cómputo y tarda más, así que trátala como una decisión consciente y no como la opción por defecto. Este endpoint se ejecuta generalmente como una tarea asíncrona, por lo que tu solicitud normalmente devuelve una referencia de tarea que debes consultar o esperar, en lugar de devolver directamente el archivo terminado.

Una vez que asignas tu entrada a estos tres grupos de campos, el cuerpo JSON real de la solicitud se vuelve claro.

Una solicitud curl funcional desde cero

La forma más rápida de confirmar que lo entiendes es una llamada mínima. La forma siguiente envía una URL de video de origen y una instrucción de estilo, y solicita un resultado en resolución estándar. Sustituye los valores de marcador de posición por los tuyos.

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "Convierte en animación de acuarela hecha a mano, con bordes suaves y difuminados, textura de papel visible y una paleta cálida y limitada. Conserva los rostros y el movimiento de cámara.",
    "resolution": "1080p"
  }'

Qué hace cada parte

  • La ruta de la URL especifica el endpoint. Debe ser exacta; un error tipográfico aquí devuelve un error de enrutamiento, no un error de validación.
  • La cabecera Authorization lleva tu clave de HiAPI. Expórtala como variable de entorno en lugar de pegarla en el historial del shell.
  • video_url es el video de origen. Debe poder ser recuperado por el servidor.
  • prompt es la instrucción de estilo. Es el campo que más modificarás.
  • resolution es el ajuste de salida. Empieza con baja resolución al iterar y súbela cuando el efecto esté definido.

Interpretar la respuesta

Una respuesta correcta te devuelve un objeto de tarea. Registra el identificador de la tarea y cualquier campo de estado:

{
  "id": "job_abc123",
  "status": "queued"
}

Los nombres exactos de los campos deben leerse de la respuesta real, no suponerse. El hábito importante es el mismo en cualquier lenguaje: analiza el JSON, extrae el id de la tarea y trata el video terminado como algo que llegará más tarde. No escribas código que asuma que la primera respuesta contiene un archivo reproducible.

La misma solicitud en Python

La versión en Python es la llamada curl expresando el cuerpo JSON como un diccionario. Usar requests mantiene la legibilidad y las dependencias ligeras.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "Convierte en animación de acuarela hecha a mano, con bordes suaves y difuminados, "
        "textura de papel visible y una paleta cálida y limitada. Conserva los rostros y el movimiento de cámara."
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))

Consultar hasta que la tarea termine

Como el renderizado es asíncrono, envuelve la espera en un bucle con un número limitado de intentos y un tiempo de espera entre comprobaciones. Espera lo suficiente para no saturar la API y fija un tiempo máximo de espera total para que una tarea atascada no bloquee tu proceso de trabajo.

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

Hacerlo apto para producción

  • Lee la ruta del endpoint y la ruta de consulta de la documentación de respuestas de la API, en lugar de codificar de forma rígida suposiciones que pueden cambiar.
  • Registra el id de la tarea al enviarla. Si algo falla aguas abajo, es tu único punto de apoyo.
  • Trata failed y los tiempos de espera agotados como resultados distintos. Una tarea fallida suele ser un problema de parámetros; un tiempo de espera agotado suele ser un problema de capacidad o de duración.

Manejar la salida 4K y las tareas de larga duración

Dos variables dominan el comportamiento operativo de este endpoint: la resolución de salida y la duración de la entrada. Planifica ambas de forma explícita.

Salida 4K

4K es una decisión de entrega, no un valor por defecto. Cada píxel de salida consume cómputo, y el salto relativo de la resolución estándar a 4K es grande. Un flujo de trabajo razonable:

  1. Itera la instrucción de estilo a menor resolución. La calidad del prompt es independiente de la resolución, así que primero ajusta bien el efecto a bajo costo.
  2. Fija el prompt y el video de origen.
  3. Vuelve a ejecutar una vez en 4K para la entrega.

Evita generar variantes en 4K en un bucle cerrado mientras ajustas la redacción: es la forma más común de desperdiciar presupuesto en renderizados que acabarás descartando.

Tareas de larga duración

Los videos de origen más largos tardan más en transformarse, y el endpoint devuelve una referencia de tarea en lugar de un archivo terminado. Construye tu cliente en torno a esa realidad:

  • Nunca dejes que una solicitud web se bloquee esperando el renderizado. Envía, almacena el id de la tarea y devuelve el control a quien llama de inmediato.
  • Separa el envío de la obtención. Un proceso de trabajo con cola y consulta es más robusto que esperar en línea y sobrevive a reinicios del proceso.
  • Persiste el estado de la tarea. Si el proceso de trabajo muere a mitad de la consulta, la tarea no desaparece; puedes reanudarla a partir del id almacenado.
  • Usa webhooks si tu cuenta los admite, y mantén la consulta como vía de reserva.
  • Fija un presupuesto total de espera que refleje la duración máxima de video que esperas, no un número arbitrario.

Un patrón práctico

Divide los videos de origen que superen la duración típica en segmentos, transfórmalos uno a uno y luego une los resultados. Esto acorta cada espera individual, te permite reintentar solo un segmento en lugar de todo el renderizado y hace que los fallos sean baratos. Asegúrate de que los cortes entre segmentos no atraviesen movimientos rápidos, o las uniones se notarán.

Diagnosticar fallos comunes

La mayoría de los fallos entran en tres categorías: el video de origen no se puede leer, los parámetros se rechazan o la tarea nunca termina. Aísla la categoría del problema antes de cambiar nada.

Errores de carga y de acceso al origen

Síntoma: el envío falla, o la tarea falla casi de inmediato por un error de entrada.

  • La URL no es accesible públicamente. Pruébala desde una máquina fuera de tu red. Que una URL firmada caduque entre el envío y la recuperación es el culpable típico.
  • Formato no compatible. Vuelve a codificar a MP4 H.264 estándar y reintenta.
  • Archivo truncado o dañado. Descárgalo tú mismo y reprodúcelo de principio a fin.
  • Solicitud demasiado grande. Si envías los bytes del archivo en línea en lugar de una URL, usa el flujo de carga y pasa el identificador devuelto.

Errores de parámetros

Síntoma: una respuesta 4xx al enviar.

  • JSON mal formado. Revisa el cuerpo de la solicitud con una herramienta de lint. Las comas finales y las comillas sin escapar son errores comunes en las llamadas curl escritas a mano.
  • Nombre de campo o tipo incorrecto. Contrasta con el esquema de solicitud actual; pasar la resolución como número cuando se espera una cadena fallará.
  • Prompt vacío o contradictorio. Si la instrucción no describe nada, o pide estilos mutuamente excluyentes, la salida será débil o se rechazará. Reescríbela en torno a una dirección visual clara.
  • Clave de API ausente o no válida. Comprueba el valor de la cabecera y si la clave es válida para este endpoint.

Tiempos de espera agotados y tareas atascadas

Síntoma: la tarea sigue en cola o en ejecución después de tu presupuesto de espera, o tu cliente se rinde.

  • Distingue entre un tiempo de espera del cliente y un fallo de la tarea. Un tiempo de espera HTTP corto al enviar no significa que la tarea no haya comenzado; comprueba si hay un id de tarea antes de reenviar, o podrías renderizar dos veces.
  • Las entradas largas y la salida 4K alargan el tiempo de ejecución. Si se agota el tiempo de forma recurrente, baja la resolución o acorta el video para confirmar que el flujo funciona y luego vuelve a subir gradualmente.
  • Si la tarea informa failed, lee el mensaje de error antes de reintentar. Reintentar a ciegas errores deterministas de parámetros solo multiplica el costo.

Un orden de depuración eficaz

Empieza con la solicitud más pequeña posible: un video corto en resolución estándar y una sola frase de prompt. Si funciona, vuelve a introducir uno a uno el prompt real, la duración real y por último 4K, cambiando solo una variable cada vez. El paso que falla te indica qué variable es la causa.

Compromisos de costo y latencia que debes planificar

Una vez que la solicitud funciona, las decisiones restantes son operativas. Tres palancas afectan a la vez al costo y a la latencia, y además interactúan entre sí.

Resolución

La resolución de salida es la palanca individual más importante. La facturación está ligada al trabajo que ejecuta el renderizado, y una salida de mayor resolución implica más trabajo. Regla práctica: iterar en baja resolución, entregar en alta resolución. Nunca dejes que los experimentos de estilo se ejecuten en 4K.

Duración de la entrada

Un video de origen más largo implica más fotogramas que transformar, lo que implica más cómputo y más tiempo real. Si tu caso de uso lo permite, transforma un clip resumen más corto en lugar del montaje completo, o divide el material largo y transforma solo las partes que necesitas procesar.

Reintentos

Salvo que el fallo ocurra antes de que empiece la tarea, cada reintento es un renderizado completo. Por eso importa el orden de depuración: valida los parámetros a bajo costo antes de gastar en renderizados. Evita envíos duplicados registrando el id de la tarea y comprobándolo antes de reenviar tras un tiempo de espera agotado en el cliente.

Procesamiento por lotes y en paralelo

Las tareas en paralelo reducen el tiempo real pero no el costo total, y pueden alcanzar los límites de concurrencia. Para trabajos por lotes, una cola moderada con paralelismo controlado suele ser mejor que un despliegue masivo. Te mantiene por debajo de los límites de tasa, hace que los fallos se puedan reintentar de forma individual y te da una curva de gasto predecible.

Lista de verificación presupuestaria

  • Fija el prompt en baja resolución antes de cualquier renderizado de entrega.
  • Almacena en caché las salidas completadas; no vuelvas a renderizar las mismas entradas.
  • Establece expectativas de gasto por tarea y por lote, y recibe alertas cuando un lote las supere.
  • Registra la relación entre la duración de la tarea, la resolución y la duración de la entrada, para predecir trabajos nuevos a partir de ejecuciones anteriores.
  • Trata 4K como el último paso del flujo, no como un modo interactivo.

Los precios de este endpoint se publican en el sitio web de HiAPI, así que consulta allí las tarifas vigentes antes de planificar el tamaño de un lote. Primero haz funcionar la solicitud mínima y luego escala la resolución y la duración de forma consciente; ese orden mantiene predecibles tanto tu latencia como tu factura.

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