Saltar al contenido

GPT Image

Genere y edite imágenes con GPT Image: parámetros, respuestas y advertencias.

ElementoValor
Base URLhttps://api.hop-base.com/v1
Generar imágenesPOST /v1/images/generations
Editar imágenesPOST /v1/images/edits
Consultar tareas asíncronasGET /v1/images/tasks?task_id=…
Grupo de la claveGPT Image (todos los modelos); gpt-image-2.5-flare y gpt-image-2.5-sunburst también funcionan con GPT oficial directo (Azure)

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 solo de chat, como Codex Plus y Codex Pro, reciben 404 con gpt-image-*. El grupo GPT oficial directo (Azure) devuelve las imágenes de forma síncrona en Base64.

Modelos disponibles

ModeloID de modeloNiveles de qualityPrecio oficial
GPT Image 2.6 Flaregpt-image-2.6-flarelow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.6 Sunburstgpt-image-2.6-sunburstlow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.5 Flaregpt-image-2.5-flarelow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.5 Sunburstgpt-image-2.5-sunburstlow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2gpt-image-2low / medium / high$5 / $30/ 1M tokens

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.

GPT Image 2.6 (lanzado el 2026-11-04) cuesta lo mismo que 2.5 y añade el parámetro complexity y la salida SVG y GIF animado. Flare es el modelo 2.6 centrado en velocidad y Sunburst el centrado en calidad. Tiempos de referencia para una imagen de 1024x1024: Flare unos 14 segundos en low, 20 en high, 29 en xhigh y 46 en max; Sunburst unos 29 segundos en low, 66 en high y 90 en xhigh.

Parámetros de la solicitud

Generar

POST /v1/images/generations con cuerpo JSON.

ParámetroObligatorioTipo y límitesPredeterminadoNotas
modelObligatoriostring—Uno de los ID de arriba
promptObligatoriostring, ≤ 32.000 caracteres—No puede quedar vacío tras quitar espacios
sizeOpcionalauto o WIDTHxHEIGHT—Reglas bajo la tabla
qualityOpcionalauto / low / medium / high—2.5 y 2.6 añaden xhigh / max
nOpcionalinteger, 1–101Algunos grupos solo aceptan 1
backgroundOpcionalauto / opaque / transparent—Transparente requiere png / webp
output_formatOpcionalpng / jpeg / webp; 2.6 también svg / gifpngFormato de la imagen decodificada
output_compressionOpcionalinteger, 0–100100Solo jpeg / webp
moderationOpcionalauto / low—No desactiva los controles de seguridad
userOpcionalstring—Identificador del usuario final
streamOpcionalbooleanfalsetrue cambia a Images SSE
response_formatOpcionalstring—Omítalo
input_fidelityOpcionallow / high—Campo de compatibilidad; omítalo
complexityOpcionallow / medium / highhighSolo 2.6; planificación antes de renderizar
frame_countOpcionalinteger, 2–169Solo gif en 2.6; número de fotogramas
frame_duration_msOpcionalinteger, 20–2000200Solo gif en 2.6; milisegundos por fotograma

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.

Solo GPT Image 2.6. complexity indica cuánto planifica el modelo antes de renderizar; no tiene cargo adicional y cualquier otro valor devuelve 400. output_format: "svg" devuelve un SVG y requiere n = 1. output_format: "gif" devuelve un GIF animado; en ese caso size es el tamaño de un fotograma, y todos los fotogramas se colocan en una sola hoja de hasta 3840 por lado, así que use auto o un fotograma pequeño como 512x512 (los fotogramas grandes fallan, y el mínimo de píxeles totales no se aplica a los fotogramas GIF). El resultado sigue llegando como b64_json; decodifíquelo y guárdelo como .svg o .gif. Las imágenes de 2.6 llevan credenciales de contenido C2PA de OpenAI, que cualquier verificador C2PA puede comprobar.

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.

ParámetroObligatorioTipo y límitesPredeterminadoNotas
imageObligatorio1–16 imágenes—Multipart: image o image[] repetido
maskOpcionalPNG con canal alfa—Los píxeles transparentes marcan la zona a editar
markupOpcionalSuperposición PNG transparente—Solo 2.6; anotaciones a seguir; no con mask

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.

Ediciones guiadas por anotaciones (solo GPT Image 2.6). Dibuje círculos, flechas o notas en un PNG transparente del mismo tamaño que la primera imagen de entrada y envíelo como markup: una parte de archivo multipart o, en JSON, una URL o Data URL. El modelo aplica lo que indican las anotaciones, por ejemplo un círculo rojo con la nota "añade aquí una hoja verde". markup no se puede combinar con mask; el gateway conserva su canal alfa y lo escala a la primera imagen.

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, complexity, frame_count, frame_duration_ms y las imágenes / máscara / markup de edición; el resto se descarta.

Respuesta

Síncrona

CampoTipoNotas
createdintegerSegundos Unix
data[].b64_jsonstringImagen en Base64; decodifíquela y guárdela según output_format
usage.input_tokensintegerTokens de entrada (puede devolverse)
usage.output_tokensintegerTokens de salida (puede devolverse)
usage.total_tokensintegerTotal (puede devolverse)
usage.costnumberEl cargo de esta solicitud en CNY (el mismo cargo que usage.cost_usd), con hasta 6 decimales. Presente en toda respuesta síncrona correcta con cargo
usage.cost_usdnumberEl importe en USD realmente descontado de su saldo, con hasta 8 decimales, el mismo importe que el registro de consumo de esta solicitud
usage.currencystringLa moneda de usage.cost, siempre CNY
errorobjectSi falla: message, type, code
{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802,
    "cost": 0.3264,
    "cost_usd": 0.048,
    "currency": "CNY"
  }
}

Una respuesta síncrona correcta también lleva el cargo real de esta solicitud: usage.cost, usage.cost_usd y usage.currency en el cuerpo, con los mismos valores en los encabezados de respuesta X-HopBase-Cost, X-HopBase-Cost-USD y X-HopBase-Currency. Si el servidor ya envió los encabezados 200 para mantener viva una generación larga (unos 40 segundos o más), los encabezados no llevan el cargo; concilie con usage.cost_usd (USD, igual que su registro de consumo) o usage.cost (CNY) del cuerpo. Los fallos sin cargo no llevan ninguno. Consulte Cargos.

Generaciones de más de 40 segundos: el estado sigue siendo 200 - revise el campo error.

Pasados unos 40 segundos, el servidor devuelve HTTP 200 y sigue escribiendo espacios en blanco al inicio del cuerpo para mantener la conexión; el JSON completo llega después. Desde entonces el estado sigue siendo 200 aunque la generación falle, así que busque error en el cuerpo y configure el tiempo de lectura en al menos 300 segundos.

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.

CampoTipoNotas
task_idstringID de la tarea
statusstringEstado de la tarea
result_contentstringAl completarse: Markdown, una línea por imagen
errorstringSolo si failed: motivo en inglés, sin código
usage.costnumberEl cargo de esta tarea en CNY (el mismo cargo que usage.cost_usd)
usage.cost_usdnumberEl importe en USD realmente descontado de su saldo por esta tarea, el mismo que su registro de consumo
usage.currencystringLa moneda de usage.cost, siempre CNY
{
  "task_id": "su-task-id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "cost_usd": 0.2,
    "currency": "CNY"
  }
}

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.

SVG, GIF animado y ediciones con anotaciones (2.6)

# SVG (n debe ser 1)
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.6-flare",
    "prompt": "Un icono plano de línea de un avión de papel",
    "output_format": "svg",
    "complexity": "low"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > icon.svg

# GIF animado: size es el tamaño de un fotograma
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.6-flare",
    "prompt": "Un shiba inu moviendo la cola, pixel art",
    "size": "512x512",
    "output_format": "gif",
    "frame_count": 9,
    "frame_duration_ms": 200
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > shiba.gif
# Edición guiada por anotaciones: markup.png es una superposición transparente con las anotaciones
curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-su-clave" \
  -F "model=gpt-image-2.6-flare" \
  -F "prompt=Siga las anotaciones del markup" \
  -F "image=@plant.png" \
  -F "markup=@markup.png" \
  -F "output_format=png" \
  | jq -r '.data[0].b64_json' | base64 --decode > edited.png

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[]=@scene.png" \
  -F "image[]=@style.png" \
  -F "mask=@mask.png" \
  -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 modelos 2.5 y 2.6.
  • complexity, markup, la salida SVG / GIF, frame_count y frame_duration_ms solo existen en los dos modelos 2.6.
  • Para la salida GIF, use size: "auto" o un tamaño de fotograma pequeño como 512x512; los fotogramas grandes fallan.
  • 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.

ErrorQué hacer
size must be WIDTHxHEIGHT or auto y otros errores de sizeAjuste el valor según las reglas de size
prompt must not be emptyEnvíe un prompt no vacío
n must be 1 for this model in the current groupDivida en solicitudes separadas
/v1/images/edits requires at least one imagePonga las referencias en image, no en images
image download returned HTTP 404Use una URL pública que el servidor pueda descargar
Your request was rejected by the safety system.Reformule el prompt o cambie la referencia
Request body exceeds the size limit (60 MB) (413)Comprima las imágenes o envíe URL
HTTP 200 con error en el cuerpoFalló tras iniciarse el keepalive; revise error.message

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. GPT Image 2.6 genera más en los niveles bajos, unos 820 en low y 1.450 en medium, así que en 2.6 las imágenes low / medium cuestan más que en 2.5; de high en adelante es igual. En tareas asíncronas, el cargo real es usage.cost_usd en la consulta (en USD; usage.cost es el mismo cargo en CNY), y una tarea fallida suele mostrar 0. En solicitudes síncronas, el cargo es usage.cost_usd / usage.cost de la propia respuesta.

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