Blog

Tutorial

Cómo usar gemini-omni-flash/text-to-video a través de la API de HiAPI: guía con curl y Python

Nov 12, 2026
Imagen de portada: capas de papel beige dispuestas de forma escalonada, con una página de papel ocre rojizo como acento, creando un ritmo estratificado y sobrio.
En esta página

Qué hace este endpoint y cuándo usarlo

gemini-omni-flash/text-to-video es un endpoint de generación en HiAPI que convierte un prompt de texto —opcionalmente anclado a una imagen de primer fotograma— en un vídeo corto. Envías una solicitud, HiAPI devuelve una tarea que puedes sondear y, cuando la tarea finaliza, obtienes una URL de vídeo que puedes descargar o reproducir en streaming.

Este endpoint es adecuado en los siguientes escenarios:

  • Clips conceptuales rápidos. Genera avances de marketing breves, previsualizaciones de storyboard o material de transición para redes sociales directamente a partir de una o dos frases descriptivas.
  • Movimiento guiado por imagen. Ya tienes una imagen fija —una foto de producto, un diseño de personaje, una ilustración— y quieres animarla en lugar de generar desde cero.
  • Generación por lotes en una canalización. Como la generación es asíncrona, puedes enviar muchos trabajos de una vez desde un worker de backend y recoger los resultados después, sin mantener la conexión de la solicitud abierta.

No está pensado para vídeos largos, montaje fotograma a fotograma ni reproducción determinista de tomas concretas. Considéralo un borrador generativo rápido: bajo coste de iteración, suficiente para revisar y totalmente automatizable de extremo a extremo.

Todo lo que sigue usa la misma interfaz de HiAPI —una clave de API, una URL base y una estructura de solicitud—, por lo que el código que escribas aquí se traslada a otros endpoints de generación sin tener que reaprender la autenticación ni el sondeo.

Antes de enviar tu primera solicitud

Hay cuatro cosas que deben estar listas antes de que la primera llamada tenga éxito.

1. Clave de API

Crea la clave en tu cuenta de HiAPI y guárdala en una variable de entorno, no en el código fuente:

export HIAPI_API_KEY="your_key_here"

2. URL base y ruta del endpoint

Todas las solicitudes van a la URL base de HiAPI, con el identificador del modelo en la ruta. Trata la URL base como una única constante en tu código, para poder cambiarla en un solo lugar:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. Cuerpo de la solicitud JSON

La solicitud es un POST con Content-Type: application/json y el token bearer en la cabecera Authorization. A menos que proporciones una imagen de primer fotograma mediante URL, no hay codificación de formulario ni subida multipart.

4. Imagen de primer fotograma (opcional)

Si vas a guiar la generación con una imagen, asegúrate primero de que sea accesible mediante una URL HTTPS pública. Las rutas del sistema de archivos local no sirven: la API obtiene la imagen en el servidor.

Un consejo práctico sobre el coste: este endpoint factura según la salida que generas; tanto el nivel de resolución como la duración del clip cuentan. Consulta los precios actuales en el panel de precios de HiAPI y confírmalos allí antes de ampliar los trabajos por lotes. El hábito importante es: prototipa primero con la configuración mínima y, cuando el prompt produzca el efecto deseado, sube la configuración.

Construir la solicitud de generación

Una solicitud consta conceptualmente de tres partes: la ruta del modelo, el prompt (y opcionalmente la imagen) y las opciones de generación. La estructura es la siguiente:

{
  "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
  "image": "https://your-bucket.example.com/first-frame.jpg",
  "resolution": "720p",
  "duration": 5,
  "audio": false
}

Prompt

El campo prompt contiene la descripción de la toma. Escríbelo como notas de dirección: sujeto, comportamiento del movimiento de cámara, iluminación y atmósfera. Los verbos de movimiento concretos («slow dolly-in», «camera pans left», «steam curls upward») guían el resultado de forma más fiable que amontonar adjetivos.

Primer fotograma opcional

El campo image es opcional. Si lo omites, el modelo genera todo el clip a partir del texto. Si lo incluyes, el clip comienza en ese fotograma y el prompt describe lo que debe ocurrir a continuación. Esta es la palanca más potente para la consistencia: un prompt de solo texto reimagina la escena en cada ejecución, mientras que fijar el primer fotograma mantiene estable la composición entre iteraciones.

Si proporcionas ambos, asegúrate de que sean coherentes. Un primer fotograma de un paisaje desértico con un prompt sobre una calle urbana bajo la lluvia produce resultados confusos: el modelo tiene que conciliar dos instrucciones contradictorias.

Dónde van las opciones

resolution, duration y audio van en el nivel superior del mismo cuerpo JSON que prompt e image. No hay que memorizar un objeto options anidado. Mantén el cuerpo plano y legible: eso facilita mucho el registro y la comparación de solicitudes al depurar trabajos por lotes.

Elegir resolución y duración

Dos parámetros dominan tanto el aspecto de la salida como el coste de la tarea: el nivel de resolución y la duración del clip.

Niveles de resolución

HiAPI expone este endpoint con varios niveles de resolución. Los niveles más bajos son el valor predeterminado adecuado durante el desarrollo del prompt: renderizan más rápido y te permiten iterar la redacción sin pagar por detalles que vas a descartar. Cuando el prompt produzca de forma fiable la composición deseada, sube de nivel para el render final.

Un flujo de trabajo práctico:

  1. Redacta el prompt en el nivel más bajo.
  2. Genera dos o tres variantes y compáralas.
  3. Fija el prompt y vuelve a renderizar en un nivel superior.

Duración del clip

La duración se especifica en segundos y este endpoint está diseñado para clips cortos. Mantén duraciones moderadas: los clips cortos hacen que cada tarea sea más rápida, que reintentar tras un fallo cueste menos y que, si más adelante necesitas una secuencia más larga, puedas unir varios clips. Si una toma necesita ocho segundos en pantalla, dos generaciones de cuatro segundos suelen ser más fáciles de controlar que una sola generación larga.

Cómo se traduce en presupuesto

Este endpoint factura según la salida que produces: una resolución mayor y una duración más larga aumentan la salida facturable de cada tarea. Como los precios se calculan por unidad de generación y los niveles cambian con el tiempo, lee las cifras vigentes en el panel de precios de HiAPI en lugar de codificar expectativas fijas. La regla de planificación que se mantiene ante cualquier cambio de precio: multiplica el número previsto de tareas por el tamaño de la salida, prototipa con la configuración mínima y escala la resolución al final.

Controlar el audio nativo

El indicador audio determina si el vídeo devuelto incluye una pista de audio nativa generada junto con la imagen.

{
  "prompt": "Rain hammering a tin roof, a door creaks open slowly",
  "audio": true
}

Qué cambia al activarlo

Con audio: true, el modelo genera sonidos acordes con la escena descrita en el prompt: ambiente, texturas del entorno y eventos sonoros sugeridos por la acción. El vídeo de salida incluye una pista de audio, así que el archivo que descargas ya está completo y no necesitas un procesamiento de efectos de sonido por separado.

Qué cambia al desactivarlo

Con audio: false, obtienes un vídeo sin sonido. Esto conviene cuando:

  • Vas a superponer tu propia música o narración al clip en el editor.
  • El clip es un elemento de fondo dentro de una composición mayor.
  • Solo estás iterando la imagen y no quieres que la generación de audio entre en el bucle.

Escribir prompts para el audio

Si activas el audio, describe el paisaje sonoro igual que describes la imagen. Las pistas sonoras del prompt —lluvia, pasos, sonidos mecánicos, una atmósfera concreta de la habitación— dan base al modelo de audio. Un prompt puramente visual seguirá produciendo audio, pero será un ambiente genérico en lugar de sonidos acordes con la toma.

Una advertencia que conviene probar pronto: el audio cambia notablemente el carácter del clip. Genera el mismo prompt una vez con el indicador activado y otra desactivado, mira ambos resultados y decide qué modo necesita realmente el proyecto antes de construir trabajos por lotes en torno a él.

Gestionar el ciclo de vida de las tareas asíncronas

La generación de vídeo tarda más de lo que debería permanecer abierta una solicitud HTTP típica, por lo que este endpoint es asíncrono. Cada llamada sigue el mismo ciclo de tres pasos.

Paso 1: enviar

Envía el cuerpo JSON con POST al endpoint. Un envío correcto devuelve inmediatamente un identificador de tarea —normalmente el id de la tarea— y un estado que indica que la tarea está en cola o en proceso. En ese momento aún no se ha renderizado nada.

Paso 2: sondear

Con el id de la tarea, consulta el endpoint de estado de la tarea a intervalos regulares. Cada sondeo devuelve el estado actual: queued, processing, completed o failed. Debes gestionar los cuatro estados. Un retroceso exponencial sencillo —empezando por unos dos segundos y con un límite de intervalo— evita saturar la API en tareas largas y, al mismo tiempo, captura rápidamente las tareas cortas.

Paso 3: obtener

Cuando el estado informa de que ha finalizado, la respuesta incluye la URL del vídeo completado y los metadatos de la tarea. Descárgalo, guárdalo o pasa la URL al frontend. Si el estado informa de un fallo, captura la información de error de la respuesta y decide si reintentar tras modificar el prompt o exponer el fallo.

Protecciones que deberías incorporar

  • Límite de tiempo de espera. Limita el tiempo total de sondeo (por ejemplo, unos minutos) y marca la tarea como fallida en tu propio código en lugar de entrar en un bucle infinito.
  • Número máximo de sondeos. Evita bucles descontrolados cuando el estado nunca queda claro.
  • Persistir el id de la tarea. Guárdalo en la base de datos o en el registro en cuanto lo recibas. Si el proceso se cae durante el sondeo, puedes recuperarte en lugar de regenerar y pagar dos veces.
  • Envío idempotente. No reenvíes por una fluctuación de red antes de confirmar que la primera solicitud ha fallado; las tareas duplicadas consumen salida real.

Si haces bien este ciclo una vez, te servirá para todos los endpoints asíncronos de HiAPI.

Ejemplos ejecutables de curl y Python

curl: enviar, sondear, obtener

Configura la clave y la URL base desde variables de entorno y luego envía:

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
    "image": "https://your-bucket.example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 5,
    "audio": false
  }'

La respuesta incluye el id de la tarea. Obtén el endpoint de estado de la respuesta y sondea:

curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Repite hasta que el estado sea completed y luego toma la URL del vídeo del cuerpo de la respuesta y descárgala:

curl -sS -o clip.mp4 "<VIDEO_URL>"

Python: el mismo ciclo, encapsulado

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def generate_video(prompt, image_url=None, resolution="720p",
                   duration=5, audio=False, timeout=300):
    payload = {
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio": audio,
    }
    if image_url:
        payload["image"] = image_url

    resp = requests.post(
        f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
        headers=HEADERS, json=payload, timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["id"]
    print(f"submitted: {task_id}")

    deadline = time.time() + timeout
    interval = 2
    while time.time() < deadline:
        status_resp = requests.get(
            f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = data.get("status")

        if state == "completed":
            return data["video_url"]
        if state == "failed":
            raise RuntimeError(f"job failed: {data}")

        time.sleep(interval)
        interval = min(interval * 1.5, 10)

    raise TimeoutError(f"job {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    url = generate_video(
        "A slow dolly-in on a glass coffee cup as steam curls upward, "
        "morning light, shallow depth of field",
    )
    print("video ready:", url)

Este script envía una tarea de solo texto, sondea con retroceso, impone un límite de tiempo de espera y devuelve la URL finalizada. Pasa image_url= para anclar la generación a un primer fotograma, o configura audio=True para incluir sonido nativo. A partir de aquí, puedes colocar generate_video en una cola de workers, en una ruta de FastAPI o en un bucle por lotes: la función es autocontenida y no tiene estado más allá del id de tarea que crea.

Puntos de fallo habituales y cómo evitarlos

La mayoría de las integraciones fallidas tropiezan con uno de los cinco problemas siguientes.

Rechazo al enviar por parámetros no válidos

La causa más frecuente es que la API no puede analizar el cuerpo de la solicitud: falta prompt, la duración está fuera del rango admitido o la cadena de resolución no es compatible. Consulta la referencia del endpoint para conocer los valores aceptables y valida localmente primero. Una pequeña utilidad que compruebe los valores permitidos antes de la llamada ahorra un viaje de ida y vuelta y un error confuso.

Imagen de primer fotograma inaccesible

La API obtiene image en el servidor, por lo que una URL que funciona en el navegador puede seguir fallando: los buckets privados, los enlaces firmados que caducan y la protección contra hotlinking causan este problema. Usa una URL HTTPS de lectura pública y verifica antes de enviar que se resuelve desde fuera de tu red.

Abandonar el sondeo

Dos variantes del mismo error: rendirse ante la primera respuesta processing y asumir un fallo, o sondear de forma demasiado agresiva y alcanzar el límite de velocidad. El bucle con retroceso y límite mostrado arriba resuelve ambos: sondea según lo previsto, trata los estados no terminales como normales y lanza una excepción solo ante un fallo explícito o un tiempo de espera agotado.

Perder el id de la tarea

Si el proceso muere después de enviar y antes de guardar el resultado, la tarea ya está pagada pero es inaccesible. Escribe el id de la tarea en un almacenamiento persistente inmediatamente después del envío y, al arrancar, comprueba si todavía hay ids en curso antes de enviar tareas nuevas.

Salida excesiva a escala

Generar lotes grandes con alta resolución y duraciones largas multiplica rápidamente el volumen de salida, y los archivos generados cuestan caro de almacenar y son lentos de servir. Prototipa a pequeña escala, renderiza en alta calidad una sola vez y mantén reglas de ciclo de vida del almacenamiento. Como la facturación está ligada a la salida generada, la solución más barata casi siempre es un ciclo de iteración de prototipos más pequeño.

Recorre esta lista en un entorno de preproducción y tu ruta a producción será fluida.

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