Tutorial
Cómo llamar a gpt-image-2.6-sunburst/text-to-image a través de la API de HiAPI: guía de curl y Python
Autenticación, estructura de la solicitud, ejemplos ejecutables de curl y Python, y solución de problemas
En esta página
Así se ve esta integración de extremo a extremo
Cada llamada de texto a imagen en HiAPI sigue el mismo ciclo de vida, y vale la pena entenderlo antes de escribir cualquier código. Tu aplicación construye un JSON que describe la imagen objetivo, lo envía junto con las credenciales de la API al endpoint de HiAPI correspondiente a gpt-image-2.6-sunburst/text-to-image y recibe una respuesta que contiene los datos de la imagen generada o una URL desde la que obtenerla. Una vez comprendidas estas tres fases, el resto de esta guía solo añade detalles.
Desglose de las fases:
- Autenticación: adjunta tu clave de API de HiAPI a la solicitud, normalmente como encabezado HTTP. No hace falta negociar un token en cada llamada.
- Construcción de la solicitud: arma un cuerpo JSON que contenga tu prompt y, opcionalmente, parámetros como el tamaño o el número de imágenes.
- Transporte: envía el cuerpo mediante POST al endpoint. La llamada es síncrona, por lo que el cliente espera a que finalice la generación de la imagen.
- Procesamiento de la respuesta: la API devuelve JSON estructurado. Según la configuración del endpoint, los datos de la imagen llegan como URL o como contenido de imagen codificado, que debes decodificar y escribir en disco.
Hay un detalle que conviene tener en cuenta desde el principio: el identificador del modelo gpt-image-2.6-sunburst/text-to-image contiene una barra inclinada. Trátalo como una cadena opaca. No intentes dividirlo en nombre de proveedor y nombre de modelo, ni lo codifiques o normalices por tu cuenta. Cópialo exactamente como aparece en la documentación y colócalo en un solo lugar del código para no tener que buscarlo más adelante.
Las secciones siguientes recorren cada fase en orden. Las partes de curl y Python usan deliberadamente la misma carga útil para que puedas compararlas línea por línea; la sección de solución de problemas asigna los errores más probables al campo concreto de la solicitud que hay que corregir.
Autenticar solicitudes a HiAPI
HiAPI utiliza un esquema de autenticación basado en clave de API. Obtienes la clave desde el panel de tu cuenta y la envías en cada solicitud. La forma estándar es un encabezado HTTP en la solicitud:
Authorization: Bearer YOUR_API_KEY
Algunos clientes prefieren enviar la clave en un encabezado dedicado, pero, salvo que la documentación de tu cuenta indique lo contrario, usa la forma Authorization: Bearer, ya que coincide de forma inmediata con la mayoría de las herramientas HTTP.
Mantener la clave fuera del código fuente
El error de seguridad más común en una primera integración es codificar la clave directamente en el script y confirmarlo en el repositorio. Evítalo desde el primer día:
- Lee la clave desde una variable de entorno, por ejemplo
HIAPI_API_KEY, y falla rápido al arrancar si la variable no existe. - Añade el archivo
.envlocal a.gitignoreantes de crearlo. - En CI o producción, inyecta la clave desde el almacén de secretos de la plataforma en lugar de leerla de un archivo confirmado.
Una pequeña función auxiliar que lea la clave una vez y lance un error claro si falta te ahorrará una sesión de depuración confusa más adelante:
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
Tratar la clave también como secreto en las solicitudes
Al depurar llamadas fallidas, no cedas a la tentación de imprimir el objeto de solicitud completo con sus encabezados. Registra en el log el endpoint, el identificador del modelo y el código de estado. Si necesitas capturar encabezados para depurar, enmascara primero el valor de Authorization. Una clave filtrada en un agregador de logs está tan expuesta como una clave confirmada en un repositorio de código.
Si rotas la clave, la anterior deja de funcionar en cuanto se completa la rotación, así que planifica la rotación como una operación periódica y no como una operación de emergencia.
Anatomía de una solicitud de texto a imagen
El cuerpo de la solicitud es un objeto JSON. Para gpt-image-2.6-sunburst/text-to-image, el número de campos esenciales es reducido, y por eso conviene entender exactamente qué hace cada uno en lugar de copiar la carga útil a ciegas.
El campo model
"model": "gpt-image-2.6-sunburst/text-to-image"
Este campo selecciona el modelo y es obligatorio. Mantén la cadena idéntica byte a byte al identificador de la documentación. Si falta la barra inclinada, hay un espacio de más o cambias las mayúsculas y minúsculas, la solicitud se rechazará por modelo desconocido.
El campo prompt
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"
Es la descripción en lenguaje natural de la imagen y es obligatorio. Consejos prácticos sobre el prompt en sí:
- Escribe primero el sujeto, después la escena y por último las indicaciones de estilo o iluminación.
- Prefiere sustantivos concretos a conceptos abstractos; "una taza de cerámica roja sobre una mesa de madera" funciona mejor que "una buena escena de taza".
- Si necesitas resultados coherentes entre varias llamadas, mantén estable la redacción de la parte invariable y sustituye solo la parte variable mediante código.
Parámetros opcionales
Según el endpoint, también puedes enviar parámetros que controlan la forma y la cantidad de la salida, los más habituales son:
- size: el tamaño de salida, expresado en el formato que indica la documentación, por ejemplo
1024x1024. Si lo omites, se aplica el valor por defecto; si envías un valor no admitido, espera un error de validación. - n: el número de imágenes que se generan para un prompt. Cada imagen generada se factura por separado, así que mantén este valor en el mínimo necesario para tu flujo de trabajo.
Envía solo los parámetros que realmente necesites. Los campos desconocidos pueden provocar errores de validación estrictos que apunten a un campo que no tenías intención de enviar.
Ejemplo de cuerpo de solicitud completo
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}
Ese es todo el contrato. El resto de esta guía gira en torno al transporte de esta carga útil, el tratamiento de errores y la gestión del ciclo de vida.
Enviar una solicitud funcional con curl
Antes de construir un cliente en Python, confirma con curl que el endpoint y las credenciales funcionan. Así separas los problemas de autenticación de los problemas de código.
El comando de llamada
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}'
Algunas notas sobre estos indicadores:
-sSmantiene la salida limpia y a la vez muestra los errores de transporte.-X POSTespecifica el método; el cuerpo se pasa mediante-d.- Las comillas simples alrededor del cuerpo JSON evitan que el shell lo altere. En
cmdde Windows, las reglas de comillas para JSON son distintas, así que usacurl.execon comillas dobles y escapa las comillas internas, o ejecuta la llamada desde un script de shell o desde Python.
Si tu cuenta usa una ruta de endpoint distinta a la de su documentación, sustitúyela aquí; la forma de la solicitud no cambia.
Inspeccionar la respuesta sin procesar
Cuando algo falla, necesitas el código de estado y el cuerpo de la respuesta. Añade -i para incluir los encabezados de respuesta, o añade -w "\nHTTP %{http_code}\n" para imprimir el estado al final:
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
Vale la pena guardar la carga útil en payload.json y referenciarla con @payload.json: evitas errores de comillas del shell y puedes editar el prompt sin reescribir el comando. Si el prompt contiene texto sensible, excluye ese archivo del control de versiones.
Hacer la misma llamada con Python
La versión en Python mantiene el cuerpo JSON idéntico byte a byte. Solo cambia el transporte. Usar requests añade una dependencia, pero mantiene el código legible; vale la pena instalarla para cualquier uso que vaya más allá de un script puntual.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
Por qué usar json=payload en lugar de data=json.dumps(payload): pasar un dict al parámetro de palabra clave json lo serializa y establece automáticamente el encabezado Content-Type. Pasar una cadena a data también funciona, pero es fácil olvidar establecer el encabezado, lo que más adelante se manifiesta como un error de validación confuso.
Si prefieres usar la biblioteca estándar
Para evitar dependencias, puedes usar urllib.request de la biblioteca estándar. El diccionario de la carga útil no cambia:
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
En cualquier caso, la generación de imágenes es más lenta que una llamada típica a una API JSON. Configura un tiempo de espera holgado; de lo contrario, agotarás el tiempo de espera en una solicitud que estaba a punto de tener éxito y la pagarás dos veces al reintentarla.
Procesar la respuesta y guardar la imagen
Una respuesta correcta es JSON. La salida de la imagen llega normalmente como URL (que debes obtener por separado) o como contenido de imagen codificado en la carga útil. Consulta la documentación del endpoint para confirmar cuál de las dos formas aplica y, después, maneja ambas de forma defensiva, ya que la forma exacta puede variar según los parámetros.
Leer la estructura de la respuesta
La respuesta es un objeto JSON que contiene la salida generada y metadatos. Inspecciónala una vez de forma interactiva antes de escribir el código de análisis:
print(json.dumps(data, indent=2)[:2000])
Localiza dónde está la imagen. Si ves un campo de URL, descárgala. Si ves contenido base64, decodifícalo. Evita suponer que la URL es permanente: trátala como de vigencia limitada y copia los bytes a tu propio almacenamiento de inmediato.
Guardar resultados basados en URL
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
Guardar resultados codificados
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
En cargas de trabajo reales, usa un nombre de archivo distinto para cada llamada: una marca de tiempo, el ID de la solicitud o un slug derivado del prompt. Si tienes previsto regenerar o auditar resultados más adelante, guarda el prompt junto con la imagen en un archivo JSON sidecar.
Gestionar las respuestas correctas en un solo lugar
Encapsula el análisis de la respuesta en una función que devuelva una lista de cadenas de bytes, una por imagen. Así cada llamador solo tiene que escribir o subir los bytes, sin saber si proceden de una URL o de contenido codificado. Esta abstracción compensa cuando cambies de modelo más adelante.
Diagnosticar errores comunes
La mayoría de los fallos en una primera integración pertenecen a unas pocas categorías. Antes de cambiar cualquier otra cosa, relaciona el código de estado y el mensaje con la solución correspondiente a continuación.
Fallos de autenticación
Que la solicitud se rechace por credenciales ausentes o inválidas significa que el encabezado Authorization falta, tiene un formato incorrecto o lleva una clave revocada. Comprueba en este orden:
- Confirma el nombre del encabezado y el formato del valor, incluida la palabra literal
Bearerseguida de un espacio. - Confirma que la variable de entorno está realmente definida en el shell o el proceso que ejecuta la llamada; una clave definida en una terminal no existe en otra.
- Confirma que la clave no se ha rotado ni truncado al copiarla.
Errores de validación del cuerpo de la solicitud
La API rechaza cuerpos de solicitud a los que les faltan campos obligatorios o que contienen valores no válidos. El mensaje suele señalar el campo problemático:
- Falta model o prompt: ambos son obligatorios. Envíalos explícitamente en cada llamada en lugar de confiar en los valores por defecto.
- Modelo desconocido: vuelve a comprobar el identificador
gpt-image-2.6-sunburst/text-to-image, incluida la barra inclinada y las mayúsculas y minúsculas. No insertes caracteres de espacio alrededor. - Tamaño no válido: usa una cadena de tamaño admitida con el formato de la documentación. Si omites intencionadamente size, elimínalo en lugar de enviar
null. - JSON mal formado: normalmente es un problema de comillas del shell en curl o de codificación de cadenas en Python. Valida con
json.dumps(payload)antes de enviar y comprueba lo que se transmite realmente.
Límites de tasa y cuotas
Si recibes una respuesta de limitación, retrocede y reintenta con jitter en lugar de reintentar de inmediato. Si el mensaje indica un problema de cuota, revisa el plan y el panel de uso de la cuenta, no el cuerpo de la solicitud; lo más probable es que la carga útil sea correcta.
Errores del servidor
Un 5xx durante la generación suele ser transitorio. Reintenta una o dos veces con retroceso exponencial. Si persiste con distintos prompts y cargas útiles, el problema no está de tu lado; captura el cuerpo de la respuesta y contacta con soporte indicando la hora de la solicitud y el identificador del modelo.
Errores de tipo de contenido
Enviar un cuerpo de solicitud sin establecer Content-Type: application/json puede producir errores de validación confusos, porque el servidor no puede analizar la carga útil. En curl, establece el encabezado explícitamente; en Python, deja que lo establezca el parámetro json=.
Preparar la integración para producción
La primera llamada correcta es la parte fácil. Los siguientes ajustes mantienen baja la integración tanto en coste de ejecución como en coste de cambio.
Externalizar el identificador del modelo
Guarda el identificador del modelo en una constante o en un valor de configuración controlado por el entorno, nunca en línea en varios puntos de llamada. Cuando más adelante evalúes distintos modelos, solo tendrás que cambiar un valor y volver a ejecutar las pruebas. Conserva el valor usado en cada solicitud en los logs, de modo que quede registrado qué modelo generó cada imagen y puedas comparar la calidad al cambiar de modelo sin volver a ejecutarlo todo.
Reintentar con criterio
Reintenta con retroceso exponencial y jitter los errores de red, los tiempos de espera agotados y las respuestas 5xx. Nunca reintentes errores de validación o autenticación: la solicitud fallará igual y solo desperdiciarás límite de tasa. Limita el número de intentos y registra el número de intento y el estado final de cada uno.
Elegir tiempos de espera acordes a la carga de trabajo
La generación de imágenes es lenta. Un tiempo de espera demasiado corto hace fallar solicitudes que habrían tenido éxito y, si reintentas, puede que pagues por una generación ya completada. Configura un tiempo de espera holgado por solicitud y trata los tiempos agotados que superen el umbral como una señal para investigar la latencia, no como un motivo para reintentar de forma agresiva.
Dividir el cliente en capas
Mantén separadas las tres partes: un constructor de carga útil que convierte las entradas de la aplicación en el diccionario de la solicitud; una función de transporte que ejecuta la llamada HTTP; y un procesador que decodifica la respuesta a bytes. Probar el constructor sin llamadas de red es muy fácil; sustituir el transporte por un mock también es muy fácil. Esta división también hace que cambiar de modelo sea editar un solo archivo en lugar de buscar por todo el código.
Registrar la información que necesitarás en un incidente
Registra el timestamp, el endpoint, el identificador del modelo, el estado HTTP, un hash o una forma truncada del prompt y la duración de la solicitud. Nunca registres la clave de API ni los encabezados completos. Si almacenas las imágenes generadas, organiza la ruta de almacenamiento por ID de solicitud para que los tickets de soporte puedan rastrearse hasta la llamada real.
Con la autenticación gestionada por variables de entorno y la carga útil aislada en una función constructora, el patrón que has practicado con gpt-image-2.6-sunburst/text-to-image se traslada directamente a cualquier otro modelo de imagen en el mismo endpoint de HiAPI.
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