GPT Image

Por defecto la respuesta es síncrona y trae imágenes en Base64; añada Prefer: respond-async para usar una tarea asíncrona. Las claves de grupos de chat reciben 404 con gpt-image-*.

Modelos disponibles

Cómo elegir: Flare es la opción diaria; Sunburst ofrece mayor fidelidad y es algo más lento que Flare con la misma configuración; gpt-image-2 es de uso general y su ID es gpt-image-2, no gpt-image-2.0. Tiempos de referencia para una imagen de 1024x1024: unos 14 segundos en low con cualquiera de los dos modelos 2.5; en high, Flare tarda unos 19 segundos y Sunburst unos 37.

Parámetros de la solicitud

Generar

POST /v1/images/generations con cuerpo JSON.

En size, WIDTHxHEIGHT debe usar múltiplos de 16, cada lado ≤ 3840, relación de aspecto ≤ 3:1 y total de píxeles 655.360–8.294.400. No se aceptan las abreviaturas 1K / 2K / 4K; un size no válido devuelve 400 antes de generar y no se cobra.

Los niveles de quality más altos generan más tokens de salida y cuestan más. response_format siempre devuelve b64_json; user no es un ID de cuenta de HopBase ni cambia a quién se factura.

Editar

POST /v1/images/edits acepta todos los parámetros anteriores, más referencias y máscara. Prefiera multipart/form-data para archivos locales; también acepta JSON con URL / Data URL.

En JSON, image puede ser una cadena URL / Data URL, un array de cadenas u objetos {"url": …}. No se lee images, y no se acepta base64 sin prefijo ni file_id.

Una URL remota debe ser ≤ 25 MiB, con Content-Type image/* y sin apuntar a una dirección interna; puede comprimirse a 4 MiB antes de reenviarse. El cuerpo completo tiene un límite de 60 MB; si lo supera, devuelve 413.

Asíncrono

Añada la cabecera HTTP Prefer: respond-async a una solicitud de generación o edición; el cuerpo no cambia. Es una cabecera, no un parámetro JSON.

Las tareas asíncronas conservan solo model, prompt, n, size, quality, background, output_format, input_fidelity y las imágenes / máscara de edición; el resto se descarta.

Respuesta

Síncrona

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802
  }
}

Streaming (stream: true)

La respuesta pasa a Images SSE: mientras espera, el flujo envía líneas de comentario de keepalive que empiezan por dos puntos, y el último evento data: contiene el JSON completo de Images, seguido de [DONE]. No son los eventos progresivos nativos de OpenAI.

: hopbase-keepalive

data: {"created":1760000000,"data":[{"b64_json":"iVBORw0KGgoAAA..."}]}

data: [DONE]

Tareas asíncronas

Al enviar, la respuesta llega de inmediato con 202 Accepted; la cabecera Location apunta a la misma URL de consulta:

{
  "object": "image.task",
  "task_id": "su-task-id",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=su-task-id"
}

Consulte solo con GET /v1/images/tasks?task_id=…; no se admite poner el ID de la tarea en la ruta. pending, processing y retrying indican que sigue en curso; completed y failed son finales.

{
  "task_id": "su-task-id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

result_content contiene rutas relativas; anteponga https://api.hop-base.com para descargar. usage aparece cuando la tarea está completed o failed, y solo la ve la clave que creó la tarea.

Ejemplos

Generar

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Un shiba inu bajo un cerezo en flor, acuarela japonesa",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

El ejemplo de curl necesita tener jq instalado.

Editar (varias referencias + máscara)

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-su-clave" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Pon un jarrón en la zona enmascarada, al estilo de la 2.ª imagen" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png"

En JSON, sustituya los archivos por URL: "image": ["https://example.com/scene.png", "https://example.com/style.png"] y "mask": "https://example.com/mask.png".

Asíncrono

# 1. Enviar y recibir 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Una ciudad futurista de noche, estilo cinematográfico",
    "size": "2048x2048"
  }'

# 2. Consultar con el task_id de la primera respuesta
curl "https://api.hop-base.com/v1/images/tasks?task_id=su-task-id" \
  -H "Authorization: Bearer sk-su-clave"

Advertencias

• Para imágenes 2K / 4K, prefiera el modo asíncrono y así evitar que la CDN corte solicitudes largas.
• Configure el tiempo de lectura del cliente para solicitudes síncronas en al menos 300 segundos.
• size solo acepta auto o WIDTHxHEIGHT; las abreviaturas de nivel devuelven 400.
• xhigh / max solo existen en los dos modelos 2.5.
• background: "transparent" requiere png o webp; la transparencia en gpt-image-2 es una función en vista previa.
• No se admite el campo oficial de streaming partial_images (0–3); omítalo.
• Con los SDK oficiales, mantenga stream en su valor predeterminado false.
• El gateway redimensiona la máscara al tamaño de la primera referencia y no garantiza conservar píxel a píxel el resto.
• La URL de result_content se abre sin clave, así que no la comparta públicamente y descárguela pronto a su propio almacenamiento.

Errores frecuentes

Los parámetros no válidos devuelven 400 antes de generar y no se cobran. Un rechazo de seguridad de contenido también devuelve 400 sin cargo, con error.code igual a safety_rejected.

# size: siga las reglas de tamaño de arriba
size must be WIDTHxHEIGHT or auto
size side length exceeds 3840px (4096x2048)
size width and height must be multiples of 16 (1000x1000)
size aspect ratio must not exceed 3:1 (3840x1024)
size total pixel count must be at least 655360 (512x512=262144)
size total pixel count must not exceed 8294400 (3840x3840=14745600)

# prompt vacío
prompt must not be empty

# edits JSON: referencias en "image" como cadenas o {"url": ...}
# ("images" no se lee)
/v1/images/edits requires at least one image
image object is missing the url field
image must be a data URL or an http(s) URL

# referencias remotas: URL pública que devuelva image/*, como máximo 25 MiB
image download returned HTTP 404
image is too large
image Content-Type is not image/*: text/html
reference image URL must not point to an internal address
image is too large, please compress it to under 4MB and retry

# seguridad de contenido (error.code: safety_rejected)
Your request was rejected by the safety system.

# HTTP 413
Request body exceeds the size limit (60 MB)

Facturación

Se factura por token; un quality más alto genera más tokens de salida. Medido a 1024x1024: unos 200 en low, 1.760 en high, 3.120 en xhigh y 7.020 en max. En tareas asíncronas, el cargo real es usage.cost en la consulta (cost_cny / cost_usd con un cambio fijo de 1 USD = 6,8 CNY), y una tarea fallida suele mostrar 0.

Los precios están en las fichas de modelo de arriba y en el catálogo de modelos tras iniciar sesión.

Próximos pasos

• Otras familias de imagen y cómo elegir: Resumen de imágenes
• Otras familias: Imágenes de Gemini, Seedream, Imágenes de Grok Imagine, Imágenes de Kling, Midjourney
• Todos los campos en la referencia de API: Generar imágenes, Editar imágenes, Consultar una tarea de imagen
• Si algo falla, revise Solución de problemas