Tutorial
Cómo llamar a gemini-omni-1.1-flash mediante la API de HiAPI: guía con curl y Python
En esta página
Qué necesitas antes de la primera solicitud
Antes de escribir cualquier código, confirma cuatro cosas. Cada una te ahorra una ronda de depuración.
Una clave de API
Cada solicitud a HiAPI debe autenticarse con una clave de API. Genera una en la consola de tu cuenta y asegúrate de que no entre en el control de versiones. Los ejemplos siguientes la leen de una variable de entorno, de modo que la clave no aparezca en el historial del shell ni en archivos confirmados:
export HIAPI_API_KEY="your_key_here"
URL base y ruta del endpoint
La URL base es la misma para todos los modelos de HiAPI; solo cambia el identificador del modelo. La ruta del endpoint y el método de la solicitud tómalos de la documentación de referencia de la API, no de artículos de blog, porque las rutas están versionadas y pueden cambiar. Guarda la URL base como una constante en el cliente, para que un cambio futuro requiera editar una sola línea.
El identificador del modelo
gemini-omni-1.1-flash se pasa como una cadena en el cuerpo de la solicitud. Cópialo con exactitud: los guiones y el sufijo de versión importan. Si lo escribes mal, el error suele ser un fallo de validación y no de enrutamiento, lo que resulta confuso; consulta la sección de depuración más adelante.
Guarda la página del modelo
La página del modelo gemini-omni-1.1-flash es la fuente autoritativa para saber qué parámetros existen, qué valores aceptan y cómo es la estructura de la respuesta. Consúltala antes de cada cambio, en lugar de leerla una vez y darla por zanjada.
Con estos cuatro puntos listos, ya puedes iniciar la llamada.
Enviar una solicitud mínima con curl
Empieza con la solicitud más pequeña posible. Su propósito no es producir buenos resultados, sino demostrar que tu clave, tu endpoint y la estructura del cuerpo concuerdan. Una vez que funcione, cada cambio posterior será incremental.
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "La cámara se acerca lentamente a una taza de cerámica sobre una mesa de madera, con una suave luz matutina"
}
}'
El significado de cada parte es el siguiente:
- Método y URL: la llamada es un
POSTdirigido a la ruta del endpoint obtenida de la documentación de referencia de la API, precedida por tu URL base. - Encabezado
Authorization: transporta el token bearer. Que la variable falte o esté vacía es la causa más común de un 401. - Encabezado
Content-Type: debe serapplication/json. Sin él, es posible que el servidor ni siquiera analice el cuerpo de la solicitud. model: la cadena exacta del identificador del modelo.input: un objeto que contiene los parámetros de generación. El prompt va aquí; la resolución y la duración también se añaden aquí, como se detalla más abajo.
Si la llamada devuelve un identificador de tarea o una respuesta de estado aceptado en lugar del resultado final, es normal: la generación es asíncrona. Guarda ese identificador; lo necesitarás en el paso de sondeo.
Portar la misma llamada a Python
La versión en Python debe enviar exactamente el mismo cuerpo JSON. Mantener el cuerpo idéntico hace creíble esta migración: si curl funciona y Python no, el problema está en tu código de Python, no en tu comprensión de la API.
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "La cámara se acerca lentamente a una taza de cerámica sobre una mesa de madera, con una suave luz matutina"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
Hay algunos hábitos que conviene adoptar de inmediato:
- Construye la URL con constantes, en lugar de dispersar concatenaciones de cadenas por todo el código.
- Establece un tiempo de espera explícito. Sin él, una solicitud bloqueada puede dejar un proceso de trabajo colgado indefinidamente.
- Llama a
raise_for_status(), para que las respuestas de error se manifiesten como excepciones en lugar de analizarse silenciosamente como si fueran respuestas correctas. - Serializa con
json.dumps, no confíes en la codificación de formulario, que no puede generar correctamente el objetoinputanidado.
Una vez que funcione, tendrás una estructura de solicitud reutilizable. Las dos secciones siguientes añaden los parámetros que realmente controlan la salida.
Configurar la resolución y la duración en la solicitud
La resolución y la duración son campos normales dentro del objeto input, junto al prompt. Conceptualmente, el cuerpo es así:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
Regla clave: no codifiques estos valores de memoria ni a partir de un tutorial que leíste hace meses. Los valores admitidos cambian con las actualizaciones del modelo, y pasar un valor no admitido produce errores de validación que parecen errores del cuerpo. Antes de configurarlos, confirma siempre los valores aceptados actualmente en la página del modelo.
Un patrón práctico
Coloca los valores en la configuración, no en el código:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
Esto aporta tres beneficios. Puedes ajustar la calidad de la salida sin cambiar la lógica. Puedes ejecutar pruebas de bajo coste y baja resolución durante el desarrollo y aumentar la calidad solo en el renderizado final. Cuando la plataforma añada nuevos valores admitidos, solo tendrás que cambiar un campo de configuración en lugar de recorrer todo el código base.
Hay dos trampas más sutiles que conviene señalar. Primera: la resolución y la duración suelen estar relacionadas con el coste; la facturación normalmente va ligada a la salida, así que los clips más largos y de mayor resolución no son gratuitos. Segunda: si un campo es opcional, omítelo en lugar de enviar una cadena vacía o null; algunos validadores rechazan un null explícito aunque el campo en sí sea opcional.
Gestionar la generación asíncrona: primero enviar, luego sondear
La generación lleva tiempo, así que la API emplea un patrón de primero enviar y luego sondear. Tu cliente debe tratar ambas operaciones como dos operaciones independientes con semánticas de reintento distintas.
Paso 1: enviar
La llamada de envío es la solicitud que ya construiste. Devuelve el identificador de la tarea; según el endpoint, puede ser un task ID, un job ID o un campo similar. Analízalo de forma defensiva:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
Paso 2: sondear
Después, usa ese identificador para consultar el endpoint de estado hasta que la tarea alcance un estado terminal. Un bucle robusto tiene cuatro características: tiempo máximo de espera, retroceso, comprobación de estados terminales y comprobación de fallos.
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
Por qué importan estos detalles
- El retroceso exponencial evita martillear el endpoint de estado en una tarea que necesita un minuto de renderizado y sigue en cola.
- Un plazo límite estricto evita que una tarea bloqueada bloquee el proceso de trabajo para siempre. Al agotarse el tiempo, registra el ID de la tarea para revisarla manualmente.
- Los estados terminales explícitos significan que nunca entrarás en un bucle infinito ante un estado no previsto. Trata los estados desconocidos como «seguir esperando», pero registra una entrada en el log.
- Estrategias de reintento separadas: reintentar la llamada de envío es más arriesgado que reintentar la llamada de estado, porque puede crear tareas duplicadas. Puedes reintentar el sondeo con tranquilidad; reintenta el envío solo ante errores de transporte claros.
Solucionar los modos de fallo comunes
La mayoría de los fallos se agrupan en unas pocas categorías. Investígalos en este orden, porque los síntomas posteriores suelen deberse a problemas anteriores.
Errores de autenticación
Síntoma: 401 o 403.
Qué comprobar primero: ¿la clave existe realmente en el entorno en que se ejecuta el proceso? Imprimir len(API_KEY) detecta el caso clásico de variable no definida que deja el token bearer vacío. Después, confirma que el formato del encabezado es Bearer <key>, con un solo espacio en medio, y que la clave no ha sido revocada ni está restringida a otro proyecto.
Formato incorrecto del cuerpo
Síntoma: 400 con queja sobre el cuerpo de la solicitud o sobre un campo faltante.
Qué comprobar primero: compara tu cuerpo con la solicitud curl que funciona. Las causas comunes incluyen la falta del encabezado Content-Type: application/json, enviar datos codificados como formulario en lugar de JSON, que el objeto input esté plano cuando la API espera anidamiento (o al revés), y conversiones de tipo accidentales: una duración numérica enviada como cadena entre comillas puede fallar la validación.
Valores de parámetro no admitidos
Síntoma: 400 o 422 que nombran un campo concreto, como resolution o duration.
Qué comprobar primero: la página del modelo, donde se enumeran los valores admitidos actualmente. Casi siempre se trata de un valor codificado obsoleto, no de un defecto del código. Si un valor que antes funcionaba ahora falla, supón primero que el modelo se actualizó y vuelve a leer la documentación, antes de suponer un fallo del servicio.
Error tipográfico en el identificador del modelo
Síntoma: error de validación o de no encontrado, sin mención de tu prompt.
Qué comprobar primero: imprime la cadena model y compárala carácter por carácter con la documentación. Un espacio extra al final o un número de versión invertido son fáciles de pasar por alto.
Tiempos de espera y fallos transitorios
Síntoma: tiempos de espera de conexión, respuestas 429 o 5xx. Qué comprobar primero: ¿has configurado un tiempo de espera? Añádelo y luego agrega reintentos acotados con retroceso solo para 429 y 5xx; no reintentes errores 4xx distintos de 429, porque la solicitud fallará igual cada vez. Para tareas largas, recuerda que el resultado final se obtiene mediante sondeo; que la llamada de envío agote el tiempo de espera no significa que la generación haya fallado.
Técnicamente válido pero resultado incorrecto
La solicitud tiene éxito pero la salida no cumple lo esperado. Esto es un problema del prompt, no de la API. Haz que el prompt sea concreto respecto al sujeto, el movimiento de cámara, la iluminación y el ritmo, y cambia solo una variable a la vez para poder atribuir las diferencias.
Encapsular en una función de cliente reutilizable
El objetivo del encapsulamiento es simple: tu lógica de negocio no debe contener identificadores de modelo, nombres de parámetros ni bucles de sondeo. Todos los detalles relacionados con el modelo se concentran en un solo lugar.
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
Qué te aporta esto
- Cambiar de modelo requiere una sola línea. Cuando llegue un modelo más nuevo, cambias la constante y los parámetros por defecto; los puntos de llamada no se ven afectados.
- Los parámetros opcionales se gestionan correctamente. Los valores omitidos no se envían, lo que evita el problema de rechazo de null descrito antes.
- El sondeo queda invisible para quien llama. Quien llama obtiene el resultado o una excepción, nunca un ID de tarea que deba gestionar por su cuenta.
- Las pruebas se vuelven fáciles. Puedes simular
post_jsonywait_for_jobpor separado para probar de forma aislada la construcción del cuerpo y la lógica de sondeo.
Organizar por capas
Mantén la estructura plana y explícita: capa de transporte (HTTP, encabezados, tiempos de espera, reintentos), capa de modelo (construcción del cuerpo para gemini-omni-1.1-flash) y capa de tarea (envío y sondeo). Una única función generate_video las combina, y cada capa es lo bastante pequeña para razonar sobre ella cuando algo falla.
Empieza con curl para confirmar la configuración de la conexión, pasa a Python para el trabajo real, lee la página del modelo siempre que cambien los parámetros, y coloca el bucle de sondeo detrás de una interfaz para que nunca se filtre al código de la aplicación.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Casos prácticos de aplicación de kling-image-4.0: 5 usos de alto valor y puntos clave de integración
-
Tutorial
Cómo usar qwen-image-2.0-pro a través de la API de HiAPI: curl, Python y una solicitud que funciona
Ejercicio práctico de integración para desarrolladores: primera llamada exitosa, anatomía de la estructura de la solicitud y diagnóstico de fallos
-
Tutorial
Cómo llamar a la API de texto a video veo-3.1: ejemplos con curl y Python
Guía práctica de integración para desarrolladores