Cómo usar la API de Creatify Boreal: generar vídeo a partir de texto, imagen y audio

creatify-boreal es un modelo de vídeo en hiapi que devuelve un clip final con la voz y el sonido ya mezclados. Un solo id de modelo cubre tres puntos de partida: solo prompt, prompt más una imagen de referencia, o prompt más tu propio audio de narración. Esta guía muestra las solicitudes, el bucle de sondeo y el resultado de una generación real que ejecuté.

Necesitas una clave de API del panel de hiapi. Todas las llamadas pasan por el endpoint unificado de tareas POST /v1/tasks.

Campos de entrada

Estos campos se verificaron con la página del modelo en vivo y enviando valores deliberadamente no válidos a /v1/tasks; los valores no válidos devuelven 400 y no se facturan.

Campo	Obligatorio	Valores aceptados
prompt	Sí	Texto, máximo 5000 caracteres
image_url	No	JPG/PNG/WebP, 10 MB; define el sujeto y la composición
audio_url	No	MP3/WAV/M4A, 15 MB; solo se usan los primeros duration segundos
negative_prompt	No	Máximo 2000 caracteres
resolution	No	720p, 1080p, 2k
aspect_ratio	No	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	No	Segundos enteros, de 1 a 20

Estos tres modos no son ids de modelo independientes. Para texto a vídeo, omite image_url y audio_url; para imagen a vídeo, añade image_url; añade audio_url (normalmente junto con una imagen) para que la persona en pantalla siga tu narración.

Solicitud mínima funcional

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "Vídeo UGC estilo selfi vertical: una mujer joven en un dormitorio luminoso levanta un pintalabios rosa suave hacia la cámara y dice: \"Vale, este es el único pintalabios que me ha durado todo el invierno.\" Sonido ambiente natural de la habitación.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

La respuesta devuelve un id de tarea:

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python: enviar y sondear

import os, time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # Error de red transitorio: sigue sondeando el mismo id
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "Vídeo UGC estilo selfi vertical: una mujer joven levanta un pintalabios rosa suave hacia la cámara y dice: \"Vale, este es el único pintalabios que me ha durado todo el invierno.\" Sonido ambiente natural de la habitación.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

El estado pasa por handling, archiving y luego success. La URL del vídeo está en data.output[0].url.

Modos de imagen y audio

La imagen a vídeo añade un campo:

{"model": "creatify-boreal",
 "input": {"prompt": "Esta mujer sonríe y habla a cámara en una cocina: \"He cambiado mi café por esta bebida de avena tipo latte.\" Sonido ambiente natural de la cocina.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

El modo guiado por audio añade audio_url apuntando a un archivo de narración. La página del modelo lo describe como: la narración se conserva en el vídeo, los labios siguen el movimiento de la narración, y solo se usan los primeros duration segundos del audio, así que ajusta duration a la longitud de clip que quieras. El ejemplo de audio de la página del modelo combina audio con una imagen de referencia; yo no ejecuté personalmente una generación de imagen más audio, así que esa combinación queda documentada pero no verificada en este artículo.

Así se ve una ejecución real

Ejecuté la solicitud anterior (solo texto, 720p, 9:16, 4 segundos).

• Tiempo de generación: la tarea estuvo unos 283 segundos en estado handling y luego unos 10 segundos en archiving. Incluso para un clip de 4 segundos, planifica en minutos, no en segundos. Sondea cada 10 segundos o usa un callback, en lugar de timeouts cortos.
• Archivo de salida: MP4 de 720x1280, vídeo H.264 a 24 fps más pista de audio AAC, duración 4,04 segundos. Aunque la solicitud no incluía campo de audio, el audio está presente, lo que encaja con el diseño de sonido nativo del modelo.
• URL temporal: la URL de salida está en temp.hiapi.ai, con un expireAt que caduca en unos 7 días. Descarga el archivo y guárdalo tú mismo, en lugar de enlazarlo desde la página.
• Forma del coste: se factura por segundo y depende de resolution (consulta la página de precios), así que la forma más barata de iterar prompts es 720p con un duration corto, y luego volver a renderizar la versión final en 1080p o 2k.

Problemas que encontré

• Los valores erróneos fallan rápido y gratis. Enviar aspect_ratio: "7:5", duration: 25 o resolution: "4k" devuelve HTTP 400 INVALID_REQUEST, con un mensaje que enumera los valores permitidos ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', máximo 20, y '720p', '1080p', '2k'). Aprovecha esto para validar tus propios formularios antes de enviar.
• Las URL de medios incorrectas fallan más tarde, al sondear. Envié audio_url: "https://example.com/a.mp3" (no era un archivo de audio real). La llamada de creación devolvió HTTP 200 y un id de tarea, y unos 15 segundos después la tarea terminó con status: "fail" y error.code: "INVALID_REQUEST". Por tanto, que la creación devuelva 200 no significa que tu medio esté disponible; comprueba siempre el estado final y lee data.error. En este caso, el fallo se presenta dentro de una respuesta de sondeo HTTP 200, no como un error HTTP.
• El fallo es status: "fail", no un estado HTTP. La solicitud de sondeo en sí devuelve 200, así que revisa data.status.

Páginas relacionadas

• Página del modelo Creatify Boreal: Playground, precios en vivo y clips de ejemplo
• Precios de hiapi
• Documentación de hiapi
• Cómo usar la API de OmniHuman 1.5: otro modelo de vídeo con persona en pantalla
• API de imagen a vídeo Ray 3.2
• Guía de la API de vídeo Wan 3.0

Preguntas frecuentes

¿Se necesitan ids de modelo separados para entradas de texto, imagen y audio? No. Los tres usan creatify-boreal; los campos que incluyas en input determinan el modo.

¿Cuánto puede durar como máximo el clip? Segundos enteros de 1 a 20. El valor 25 se rechaza con HTTP 400.

¿La salida incluye sonido? Sí. El clip de prueba de 4 segundos tenía pista de audio AAC aunque no se proporcionó entrada de audio.

¿Qué resoluciones hay disponibles? 720p, 1080p y 2k. La facturación varía según la resolución; consulta la página de precios.

¿Cuánto debo esperar? Mi prueba de 4 segundos en 720p tardó unos cinco minutos de principio a fin. Usa sondeo o callbacks con un límite holgado.