Cómo usar la API de GPT Image 2: guía de texto a imagen e imagen a imagen

Qué ofrece la API de GPT Image 2 a los desarrolladores

La API de GPT Image 2 te ofrece una interfaz unificada y consistente para generar imágenes a partir de indicaciones. No necesitas combinar varios proveedores ni mantener múltiples SDK: basta con enviar una solicitud HTTP a HiAPI.ai para recibir los datos de la imagen. Esto es importante cuando creas funcionalidades como generadores de materiales de marketing, ilustraciones de incorporación en aplicaciones o herramientas creativas orientadas al usuario, porque la latencia, el tiempo de actividad y una estructura de solicitud predecible son fundamentales.

Usarás dos modos de generación:

• Texto a imagen: proporcionas una indicación y el tamaño objetivo, y el modelo genera la imagen desde cero.
• Imagen a imagen: proporcionas una indicación además de una o varias imágenes de referencia, y el modelo genera la imagen guiándose por esas referencias.

Ambos modos comparten la misma autenticación y estructura de respuesta, así que una vez que tengas una llamada funcional, el segundo modo supone solo un pequeño ajuste, no una integración completamente nueva. Esta guía explica en orden cómo elegir entre las dos variantes, una solicitud curl mínima, el manejo de imágenes de referencia, cómo solicitar salida en 4K, la adaptación a Python y los patrones de manejo de errores que evitan fallos silenciosos en una canalización de imágenes en producción.

Si estás creando cualquier funcionalidad que requiera generación de imágenes con un contrato de API estable, el resto de este artículo es la ruta más corta desde cero hasta una solicitud funcional.

Texto a imagen frente a imagen a imagen: elegir la variante

Antes de escribir código, determina cuál variante necesita realmente tu producto. Esta elección depende principalmente del grado de control que quieras sobre la salida y de cuánto contenido esperas que proporcionen los usuarios.

Cuándo usar texto a imagen

Texto a imagen es la opción predeterminada adecuada en los siguientes casos:

• Los usuarios describen con texto lo que quieren y no tienen material de origen.
• Vas a generar imágenes de marcador de posición, imágenes principales o variaciones basadas en una plantilla de indicación fija.
• Quieres el cuerpo de solicitud más sencillo posible —una indicación y un tamaño— para mantener el volumen de la solicitud pequeño y la latencia predecible.

Cuándo usar imagen a imagen

Imagen a imagen es la elección correcta cuando la salida debe mantenerse fiel a algo que ya existe:

• Rediseñar o volver a renderizar con un estilo una foto de producto subida.
• Aplicar un tratamiento visual consistente sobre un conjunto de materiales de referencia.
• Guiar la composición, la paleta de colores o el sujeto para que el resultado coincida con una marca o escena existente.

Regla práctica

Si la indicación por sí sola determina completamente la salida, usa texto a imagen. Si parte de la intención reside en la imagen y no en el texto —y describirla con una indicación resultaría perjudicial, prolijo o poco fiable— usa imagen a imagen y pasa las imágenes de referencia.

Un error habitual es recurrir a imagen a imagen cuando una mejor indicación resolvería el problema. Las imágenes de referencia añaden sobrecarga de carga y más posibilidades de fallo en la validación de la solicitud. Empieza con texto a imagen y cambia a la variante con referencias solo cuando puedas señalar un atributo visual concreto que la indicación no logre capturar.

Envía tu primera solicitud de texto a imagen con curl

Empieza con curl. Elimina la variable del comportamiento del SDK, de modo que cuando algo falle puedas determinar que el problema está en la autenticación o en la estructura del cuerpo de la solicitud, no en la biblioteca cliente.

Primero define la clave de API como variable de entorno, para que no acabe en el historial del shell ni en el control de código fuente:

export HIAPI_API_KEY="your_api_key_here"

Después envía una solicitud mínima:

curl -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",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

Qué debes comprobar en la respuesta:

1. Código de estado HTTP. 200 significa que la solicitud se aceptó y procesó. Para cualquier otro código, lee primero el cuerpo de la respuesta de error antes de cambiar nada.
2. Autenticación. 401 casi siempre indica que la clave falta, tiene un formato incorrecto o ha caducado: confirma que la cabecera Authorization tiene el formato Bearer seguido de la clave.
3. Cuerpo de la solicitud. 400 normalmente apunta a un campo concreto: un parámetro mal escrito, una cadena de tamaño que el modelo no acepta o una indicación que no supera la validación.
4. Carga de la imagen. Según el modo de respuesta, obtendrás una URL que puedes descargar o datos de imagen en base64. Maneja ambos casos para que tu cliente no se vea sorprendido más adelante.

Cuando esta llamada funciona, has verificado tres cosas a la vez: la clave es válida, la ruta del endpoint es correcta y la estructura JSON es aceptable. Cada modificación posterior de esta guía parte de esta base que ya sabes que funciona.

Guiar la salida con imágenes de referencia

Las solicitudes de imagen a imagen mantienen el mismo envoltorio de solicitud que las de texto a imagen y añaden una entrada de imagen de referencia. La indicación sigue llevando las instrucciones; las imágenes de referencia aportan el contexto visual.

El cambio en el cuerpo de la solicitud es que ahora proporcionas datos de imagen además de la indicación. En la práctica, esto significa proporcionar una URL que el servicio pueda descargar o una imagen codificada en base64 en línea, según la forma que admita tu integración. Ten en cuenta estas reglas:

• La indicación y la imagen de referencia deben ser coherentes. Si la indicación describe un producto rojo y la referencia es azul, el modelo recibe señales contradictorias. Redacta la indicación como una instrucción sobre la referencia («vuelve a pintar esta escena con estilo de acuarela»), no como una descripción que la contradiga.
• Envía solo lo necesario. Una referencia sólida suele ser mejor que varias débiles. Varias referencias aumentan el volumen de carga y dificultan determinar cuál impulsó la salida.
• Vigila el tamaño de la solicitud. Las imágenes codificadas en base64 inflan considerablemente el payload de la solicitud. Si subes fotos grandes, este es el primer lugar que debes revisar cuando la solicitud se vuelve lenta o se rechaza.
• Valida antes de enviar. Comprueba que la imagen tenga un formato admitido y que se decodifique correctamente. Una cadena base64 mal formada produce fallos difíciles de entender y lentos de diagnosticar.

La estructura de solicitud utilizable es la siguiente:

curl -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",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

Como el envoltorio de la solicitud no cambia, la llamada curl que ya validaste sigue siendo tu herramienta de depuración: sustituye el cuerpo, conserva las cabeceras y compara la respuesta campo por campo.

Solicitar salida en 4K

La resolución de salida se especifica en la solicitud, no la asume el modelo. Si necesitas salida de alta resolución, debes indicarla explícitamente con el parámetro size; no esperes que el valor predeterminado sea grande.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

Al pasar a resoluciones más altas, hay varias cosas que debes verificar:

• Cadenas de tamaño admitidas. Los valores de tamaño se validan según el rango que acepta el modelo. Un tamaño rechazado devuelve 400 en lugar de degradarse en silencio, así que confirma la cadena de tamaño exacta que requiere la solicitud en vez de adivinar un valor parecido pero erróneo.
• Volumen de respuesta. Los datos de imagen en 4K son mucho mayores que los resultados en 1K. Si tu respuesta transporta base64 o una URL que descargarás de inmediato, reserva presupuesto para ello en la memoria y en la configuración de tiempos de espera.
• Latencia. La generación en mayor resolución tarda más. Configura tiempos de espera del cliente generosos en lugar de dejar que una solicitud lenta pero exitosa agote el tiempo de espera por tu lado.
• Modelo de costes. La facturación depende del tamaño y la cantidad de salida que solicites, así que elige con criterio: genera con la resolución que realmente necesita la funcionalidad y, si la interfaz de usuario no necesita resolución completa, reduce la escala en tu propia canalización. Consulta el panel de precios del sitio web para los precios actuales.
• Amplía con cautela. Si necesitas una salida mayor que la que produce el modelo, ampliarla después de generarla es un paso independiente con sus propias contrapartidas de calidad. Decide conscientemente qué ruta quieres seguir.

Antes de conectar 4K a tareas por lotes, prueba 4K con una indicación que ya sabes que funciona, para que los fallos relacionados con la resolución no se confundan con problemas de autenticación o del cuerpo de la solicitud.

Adaptar la solicitud a Python

No reescribas la solicitud desde cero en Python. Adapta el mismo cuerpo de solicitud exacto que ya validaste con curl y luego confirma por separado el manejo de la respuesta.

import os
import base64
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Notas sobre la adaptación:

• Mantén la clave en una variable de entorno, exactamente igual que con curl. Nunca la incluyas en línea.
• Configura tiempos de espera explícitos. La generación de imágenes es más lenta que una llamada típica a una API JSON; usar el tiempo de espera corto predeterminado es una causa habitual de fallos falsos.
• Maneja ambos modos de respuesta. Ramificar según b64_json o url hace que el código funcione independientemente de cómo se configure la respuesta.
• Reutiliza funciones. Encapsula esta parte en una pequeña función auxiliar generate_image(prompt, size) para que texto a imagen e imagen a imagen solo difieran en el campo opcional image del payload.

Como el diccionario del payload es el mismo objeto que probaste con curl, cualquier cambio de comportamiento que observes en Python provendrá casi con certeza del lado del cliente —cabeceras, codificación o tiempos de espera—, lo que reduce mucho el ámbito de depuración.

Manejar errores y validar respuestas

La generación de imágenes es por naturaleza una llamada propensa a fallos: es más lenta que la mayoría de los endpoints de API, transporta payloads grandes y depende de la disponibilidad del modelo. Trátala como una operación que falla ocasionalmente y requiere reintentos, no como una operación única.

Lista de comprobación de la respuesta

1. Comprueba el estado antes de analizar. Llama a raise_for_status() o comprueba el código de estado, y lee el cuerpo de la respuesta de error: normalmente indica el campo problemático.
2. Valida la estructura. Confirma que data existe y no está vacío antes de indexar. No des por hecho que data[0] exista.
3. Verifica los bytes de la imagen. Tras decodificar, comprueba que la salida no esté vacía y empiece con una firma de imagen válida. Un archivo de cero bytes es un fallo silencioso que se manifiesta mucho después.
4. Registra el ID de la solicitud. Conserva el identificador de solicitud de la respuesta en los registros, para que una generación fallida se pueda rastrear sin reproducirla.

Estrategia de reintentos

• Reintenta solo fallos transitorios. Los tiempos de espera, los reinicios de conexión y las respuestas 5xx merecen reintento. 401 o 400 fallarán de la misma forma cada vez: corrige la solicitud en lugar de reintentarla.
• Usa retroceso exponencial con jitter. Empieza con un retardo corto y auméntalo gradualmente; el jitter evita que un grupo de procesos trabajadores reintenten sincronizadamente.
• Limita el número de intentos. Normalmente dos o tres reintentos son suficientes. A partir de ahí, expón el error al usuario o deriva la tarea a una ruta de mensajes fallidos.
• Hazlo idempotente. Como los reintentos pueden producir generaciones duplicadas, asocia el resultado al ID de la tarea original, de modo que un reintento nunca vuelva a cobrar por una operación visible para el usuario.

Adáptalo a asíncrono

La generación en alta resolución tarda mucho, así que, si tu arquitectura lo permite, no mantengas ocupado el hilo de la solicitud. Coloca la tarea en una cola, devuelve un ID de tarea al llamador y deja que un proceso trabajador ejecute la llamada con la estrategia de reintentos descrita. Así tu capa web se mantiene receptiva y confina el trabajo lento y propenso a fallos donde los reintentos cuestan poco.

Conecta estas comprobaciones desde la primera llamada funcional, no después del primer incidente en producción: el coste de una pequeña función auxiliar de validación es mucho menor que depurar un archivo de imagen vacío tres semanas después. Cuando la autenticación, la estructura del cuerpo de la solicitud, la resolución y los reintentos estén confirmados, la API de GPT Image 2 se convierte en un componente fiable en el que construir, no en una integración solo apta para demos.