Tutorial
Cómo generar vídeos con gemini-omni-flash a través de la API de HiAPI
Rutas de solicitud y selección de modelo para texto a vídeo e imagen a vídeo, además de una lista de comprobación de integración funcional
En esta página
Por qué gemini-omni-flash tiene dos endpoints de vídeo
Antes de escribir la primera línea de código, la decisión más importante es: cuál de los dos endpoints de vídeo necesitas realmente. gemini-omni-flash se ofrece en HiAPI como dos modelos independientes, no como un único endpoint con una marca de modo:
gemini-omni-flash/text-to-video: genera vídeo únicamente a partir de un prompt de texto.gemini-omni-flash/image-to-video: usa la imagen de origen proporcionada como ancla visual y genera vídeo guiado por un prompt de texto.
La razón de esta separación es que ambas tareas tienen entradas distintas, reglas de validación distintas y modos de fallo distintos. El texto a vídeo solo necesita validar una cadena de prompt. El imagen a vídeo también debe recuperar y decodificar tu imagen de origen, lo que añade una categoría de errores que no aparece en la ruta de texto (URL inaccesible, formato no compatible, recurso demasiado grande).
Regla general: si ya tienes una imagen estática (una foto de producto, un fotograma de storyboard, una fotografía), usa imagen a vídeo, porque el modelo parte de tu contenido visual en lugar de crear desde cero. Si solo tienes una idea y ningún material de referencia, usa texto a vídeo.
Distingue ambos ID de modelo en tu base de código desde el primer día. Tratarlos como un único concepto de «vídeo» y añadir después un indicador if has_image es precisamente lo que acaba provocando cargas útiles confusas y errores difíciles de entender en las integraciones.
Qué se mantiene igual
Ambos endpoints comparten el mismo esquema de autenticación, la misma URL base, las mismas convenciones generales de solicitud/respuesta y el mismo modelo de facturación (el vídeo se factura por la salida generada, no por el número de solicitudes). Precisamente estas partes compartidas hacen viable un único constructor de solicitudes, como se detalla más adelante.
Qué es diferente
Solo cambian la estructura de la carga útil y la validación de entradas. La diferencia es lo bastante pequeña como para admitir ambos endpoints sin duplicar todo el código de integración.
Requisitos previos y configuración de la API
Antes de la primera llamada necesitas tres cosas.
1. Clave de API
Crea una clave en tu cuenta de HiAPI y guárdala como variable de entorno en lugar de codificarla directamente:
export HIAPI_API_KEY="your_key_here"
Cada solicitud se autentica mediante un token bearer en la cabecera Authorization. No hay un paso de firma independiente ni un nonce por solicitud.
2. URL base y convención de nombres de modelos
Todas las llamadas van a la misma URL base de HiAPI y el modelo se selecciona mediante el campo model del cuerpo de la solicitud. Los ID de modelo siguen el patrón family/variant, por lo que los modelos de vídeo se escriben gemini-omni-flash/text-to-video y gemini-omni-flash/image-to-video. Para cambiar de endpoint solo cambias una cadena, no el host.
3. Herramientas para realizar solicitudes
curl basta para verificar la conectividad y Python (con requests) basta para construir una integración real. Ninguno de los dos requiere un SDK específico del proveedor: la API es JSON normal sobre HTTPS.
Comprobación de conectividad
Antes de generar cualquier vídeo, accede a un endpoint ligero (por ejemplo, listar los modelos disponibles) para confirmar que la clave funciona y que la ruta de red es correcta. Si ese paso falla, estás depurando credenciales o conectividad, no la generación de vídeo; saber cuál de las dos cosas es te ahorra mucho tiempo.
Lista de comprobación rápida:
- La clave está exportada en el shell donde se ejecutará la solicitud.
- La URL base está anotada y se usa de forma consistente en todas partes (evita que la barra final varíe entre scripts).
- Cada POST incluye
Content-Type: application/json. - Tienes una forma de ver la respuesta JSON sin truncarla.
Realizar una solicitud de texto a vídeo
Empieza con la solicitud más pequeña que tenga posibilidades de funcionar. No rellenes todos los parámetros opcionales de entrada: si la solicitud mínima falla, sabes que el problema es estructural; si funciona, cada parámetro que añadas después es un cambio atribuible por separado.
Estructura mínima
Una solicitud de texto a vídeo envía el ID de modelo y el prompt:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Toma de avance lento por una calle de neón mojada por la lluvia de noche, reflejos en el asfalto húmedo, aspecto cinematográfico"
}
Esa es la carga útil completa. Envíala, confirma que recibes un objeto de respuesta correcto y solo entonces empieza a enriquecer el contenido.
Evolucionar la solicitud paso a paso
Una vez que la llamada mínima funciona, añade un parámetro cada vez y vuelve a validar tras cada adición. Adiciones típicas en la ruta de texto:
- Detalle del prompt: sujeto, movimiento, comportamiento de cámara, iluminación y ambiente. Los prompts vagos producen movimientos vagos; describe qué se mueve y cómo se mueve la cámara.
- Duración / longitud de salida: el vídeo se factura por la salida generada, así que la longitud afecta directamente al coste. Fíjala explícitamente en lugar de confiar en un valor predeterminado que no has verificado.
- Relación de aspecto o resolución (si el modelo lo admite), para coincidir con el reproductor de destino o el formato de redes sociales.
Claves para escribir prompts que realmente importan
La calidad del texto a vídeo depende principalmente de la concreción del prompt. Tres buenos hábitos:
- Describe el movimiento, no solo el contenido. «Un barco de papel bajando flotando por un desagüe» da al modelo algo que animar; «un barco de papel» no.
- Especifica la cámara. Fija, panorámica, avance, en mano: el lenguaje de cámara elimina mucha ambigüedad.
- Limítate a una sola escena. Describir varios planos en un único clip corto suele producir resultados embarullados.
Cuando el resultado de texto a vídeo sea deficiente, cambia primero el prompt y después toca cualquier parámetro técnico.
Realizar una solicitud de imagen a vídeo
La ruta de imagen es estructuralmente igual que la de texto, con una sola cosa más: la imagen de origen. El método de prueba de «mínimo primero» que aprendiste también se aplica aquí.
Estructura mínima
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "Deriva suave en mano, el sujeto gira ligeramente hacia la cámara, luz de ventana suave",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
En este caso el prompt describe el movimiento y el comportamiento de cámara respecto a la imagen, no el contenido de la escena: la imagen ya proporciona el contenido. Este es el error conceptual más común: la gente escribe una descripción completa de la escena y luego se pregunta por qué la salida ignora su fotograma de origen.
Cómo proporcionar la imagen de origen
La imagen se pasa como referencia y el servicio debe poder recuperarla. Dos consecuencias prácticas:
- El recurso debe ser accesible públicamente por el servicio, no puede estar detrás de tu localhost, una VPN o un bucket con autenticación. Una URL firmada de caducidad corta sirve, siempre que siga siendo válida cuando se ejecute la solicitud.
- El formato y el tamaño deben ser compatibles. Usa formatos web comunes y tamaños razonables. Un TIFF de 40 MB es una sesión de depuración esperando a ocurrir.
Si tus imágenes están en almacenamiento privado, genera una URL firmada de corta duración en el momento de la solicitud en lugar de intentar hacer público el bucket.
Diferencias prácticas con la ruta de texto
- El papel del prompt pasa de describir la escena a describir el movimiento.
- La validación añade un paso de recuperación del recurso, por lo que aparece toda una nueva categoría de fallos (véase la sección de depuración).
- La composición de salida está condicionada por la relación de aspecto de la imagen de origen, lo que afecta a cómo planificas el diseño posterior.
Prueba primero la URL de la imagen en el navegador. Si a ti tampoco te carga limpiamente, al servicio le pasará lo mismo.
Llamar a la API con curl y Python
Haz que la misma solicitud funcione en dos sitios: en la terminal (para iteración rápida y visibilidad del contenido sin procesar) y en tu base de código (para el uso real).
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Toma de avance lento por una calle de neón mojada por la lluvia de noche, aspecto cinematográfico"
}'
Cambia la cadena de model por gemini-omni-flash/image-to-video y añade el campo image para alcanzar el otro endpoint; no hace falta cambiar nada más.
Usa -sS para que los errores no se traguen silenciosamente; al inspeccionar la respuesta, pásala por una herramienta de formateo JSON para que los campos anidados sean legibles.
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "Toma de avance lento por una calle de neón mojada por la lluvia de noche, aspecto cinematográfico",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
Dos detalles que merece la pena copiar tal cual: leer la clave desde una variable de entorno y establecer un tiempo de espera suficientemente amplio. La generación de vídeo no es una solicitud instantánea: un tiempo de espera predeterminado de 10 segundos produce fallos falsos que parecen errores de la API cuando en realidad tu cliente se rindió antes de tiempo.
Para imagen a vídeo, añade una línea:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
Cuando recibas un código de estado no 2xx, imprime o registra siempre el cuerpo de respuesta sin procesar antes de lanzar una excepción. El texto del error suele indicar directamente el campo problemático.
Organizar el código de tu integración
Una vez que ambas rutas funcionan por separado, es tentador dejar en la base de código dos funciones casi idénticas. Una estructura ligeramente mejor cuesta casi nada y se amortiza en el momento en que añadas un segundo modelo de vídeo.
Dos componentes compartidos
Un constructor de solicitudes. Una función que recibe parámetros a nivel de intención y devuelve un diccionario de carga útil:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
La selección de endpoint pasa a ser el resultado de «¿tengo una imagen?», lo que coincide con la decisión real de producto. Quien llama nunca toca directamente los ID de modelo.
Un procesador de respuestas. Una función que trata por separado los errores de transporte, los errores de carga útil y los fallos a nivel de modelo, y devuelve un objeto de resultado normalizado (estado, referencia del vídeo, cuerpo de respuesta sin procesar para los registros). Todos los llamadores pasan por él, de modo que la semántica de errores de ambos endpoints se mantiene coherente.
Por qué merece la pena hacerlo así
- Los ID de modelo se cambian en un solo sitio. Cuando migres a un modelo de vídeo distinto, solo editas el constructor, no quince puntos de llamada.
- Tratamiento de errores coherente. Un fallo de recuperación de imagen y un fallo de validación de prompt se presentan de la misma forma en tu UI.
- Pruebas sin red. El constructor es una función pura; puedes hacer pruebas unitarias de la estructura de la carga útil con bajo coste.
- Visibilidad de la facturación. Como el vídeo se factura por la salida generada, un único procesador es el lugar natural para registrar la duración y el tamaño de salida y hacer seguimiento de los costes.
Mantén el constructor ligero. La lógica de negocio sobre qué generar corresponde a quien llama; el constructor solo necesita saber cómo expresar esa intención con la forma de la API.
Depurar los fallos de solicitud habituales
Casi todos los fallos tempranos caen en una de tres categorías. Primero identifica la categoría y después corrige.
Categoría 1: estructura de la solicitud
Síntoma: un 4xx inmediato, un mensaje de error que menciona un campo ausente o desconocido, o una queja sobre un JSON mal formado.
Comprueba en orden:
- ¿Es válido el JSON? Pega el cuerpo de la solicitud en un linter. Una coma final que quedó al editar la carga útil a mano es el problema clásico.
- ¿Coincide exactamente el ID de modelo?
gemini-omni-flash/text-to-videoygemini-omni-flash-text-to-videono son la misma cadena. Un error tipográfico aquí produce un error de «modelo no encontrado» que se lee como un problema de autenticación. - ¿Están completas las cabeceras? Tanto
AuthorizationcomoContent-Type: application/jsonestán establecidas. - ¿Coinciden el modelo y el endpoint? Enviar el campo
imageal endpoint de texto no dará el resultado que quieres: el campo se rechazará o se ignorará, y en cualquiera de los dos casos obtendrás un resultado incorrecto.
Categoría 2: recurso de entrada (solo ruta de imagen)
Síntoma: la solicitud se acepta pero falla durante el procesamiento, o el error menciona la recuperación o decodificación de la imagen.
Comprueba:
- Abre la URL de la imagen en una ventana de navegador privada sin cookies. Si no carga ahí, el servicio tampoco podrá cargarla.
- Confirma que la URL no es una dirección de localhost, un host de red privada ni un enlace firmado caducado.
- Confirma que el formato es un formato web común y que el tamaño de archivo es razonable.
- Confirma que la respuesta es realmente una imagen: una CDN que devuelve un estado 200 pero cuyo contenido es una página de error HTML es una trampa sorprendentemente habitual.
Categoría 3: la propia llamada al modelo
Síntoma: la solicitud es válida y el recurso es accesible, pero la generación falla o se rechaza, normalmente por políticas de contenido o capacidad.
Comprueba:
- Reduce al prompt mínimo y vuelve a intentarlo. Si funciona, tu prompt era la variable.
- Comprueba si el tiempo de espera del cliente es suficientemente largo: en los registros, un tiempo de espera del cliente parece exactamente un fallo del servidor salvo que compruebes si llegó a recibirse alguna respuesta.
- Activa el registro completo de solicitudes/respuestas (con las claves enmascaradas) para poder distinguir las tres categorías de un vistazo.
Un orden de depuración eficaz
Carga útil mínima → validar → añadir imagen → validar → añadir parámetros opcionales uno a uno → validar. Cuando algo se rompe, el último cambio que hiciste es el culpable. Si te limitas a depurar una sola variable a la vez, la mayor parte del sufrimiento de las integraciones desaparece.
Empieza por la llamada mínima funcional de cada endpoint, envuélvela con el constructor y el procesador compartidos y después amplía paso a paso: ese camino mantiene tanto el texto a vídeo como el imagen a vídeo predecibles a medida que crece la integración.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio