GPT Image
Genere y edite imágenes con GPT Image: parámetros, respuestas y advertencias.
| Elemento | Valor |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| Generar imágenes | POST /v1/images/generations |
| Editar imágenes | POST /v1/images/edits |
| Consultar tareas asíncronas | GET /v1/images/tasks?task_id=… |
| Grupo de la clave | GPT 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
| Modelo | ID de modelo | Niveles de quality | Precio oficial |
|---|---|---|---|
| GPT Image 2.6 Flare | gpt-image-2.6-flare | low / medium / high / xhigh / max | $5 / $30/ 1M tokens |
| GPT Image 2.6 Sunburst | gpt-image-2.6-sunburst | low / medium / high / xhigh / max | $5 / $30/ 1M tokens |
| GPT Image 2.5 Flare | gpt-image-2.5-flare | low / medium / high / xhigh / max | $5 / $30/ 1M tokens |
| GPT Image 2.5 Sunburst | gpt-image-2.5-sunburst | low / medium / high / xhigh / max | $5 / $30/ 1M tokens |
| GPT Image 2 | gpt-image-2 | low / 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ámetro | Obligatorio | Tipo y límites | Predeterminado | Notas |
|---|---|---|---|---|
model | Obligatorio | string | — | Uno de los ID de arriba |
prompt | Obligatorio | string, ≤ 32.000 caracteres | — | No puede quedar vacío tras quitar espacios |
size | Opcional | auto o WIDTHxHEIGHT | — | Reglas bajo la tabla |
quality | Opcional | auto / low / medium / high | — | 2.5 y 2.6 añaden xhigh / max |
n | Opcional | integer, 1–10 | 1 | Algunos grupos solo aceptan 1 |
background | Opcional | auto / opaque / transparent | — | Transparente requiere png / webp |
output_format | Opcional | png / jpeg / webp; 2.6 también svg / gif | png | Formato de la imagen decodificada |
output_compression | Opcional | integer, 0–100 | 100 | Solo jpeg / webp |
moderation | Opcional | auto / low | — | No desactiva los controles de seguridad |
user | Opcional | string | — | Identificador del usuario final |
stream | Opcional | boolean | false | true cambia a Images SSE |
response_format | Opcional | string | — | Omítalo |
input_fidelity | Opcional | low / high | — | Campo de compatibilidad; omítalo |
complexity | Opcional | low / medium / high | high | Solo 2.6; planificación antes de renderizar |
frame_count | Opcional | integer, 2–16 | 9 | Solo gif en 2.6; número de fotogramas |
frame_duration_ms | Opcional | integer, 20–2000 | 200 | Solo 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ámetro | Obligatorio | Tipo y límites | Predeterminado | Notas |
|---|---|---|---|---|
image | Obligatorio | 1–16 imágenes | — | Multipart: image o image[] repetido |
mask | Opcional | PNG con canal alfa | — | Los píxeles transparentes marcan la zona a editar |
markup | Opcional | Superposició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
| Campo | Tipo | Notas |
|---|---|---|
created | integer | Segundos Unix |
data[].b64_json | string | Imagen en Base64; decodifíquela y guárdela según output_format |
usage.input_tokens | integer | Tokens de entrada (puede devolverse) |
usage.output_tokens | integer | Tokens de salida (puede devolverse) |
usage.total_tokens | integer | Total (puede devolverse) |
usage.cost | number | El 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_usd | number | El importe en USD realmente descontado de su saldo, con hasta 8 decimales, el mismo importe que el registro de consumo de esta solicitud |
usage.currency | string | La moneda de usage.cost, siempre CNY |
error | object | Si 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.
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.
| Campo | Tipo | Notas |
|---|---|---|
task_id | string | ID de la tarea |
status | string | Estado de la tarea |
result_content | string | Al completarse: Markdown, una línea por imagen |
error | string | Solo si failed: motivo en inglés, sin código |
usage.cost | number | El cargo de esta tarea en CNY (el mismo cargo que usage.cost_usd) |
usage.cost_usd | number | El importe en USD realmente descontado de su saldo por esta tarea, el mismo que su registro de consumo |
usage.currency | string | La moneda de usage.cost, siempre CNY |
{
"task_id": "su-task-id",
"status": "completed",
"result_content": "",
"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.pngEl 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.pngEditar (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.
sizesolo aceptaautooWIDTHxHEIGHT; las abreviaturas de nivel devuelven 400.xhigh/maxsolo existen en los modelos 2.5 y 2.6.complexity,markup, la salida SVG / GIF,frame_countyframe_duration_mssolo existen en los dos modelos 2.6.- Para la salida GIF, use
size: "auto"o un tamaño de fotograma pequeño como512x512; los fotogramas grandes fallan. background: "transparent"requierepngowebp; la transparencia engpt-image-2es 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
streamen su valor predeterminadofalse. - 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_contentse abre sin clave, así que no la comparta públicamente y descárguela pronto a su propio almacenamiento.
- Los valores estándar siguen la referencia de OpenAI Images y la referencia oficial de edición.
output_compression,moderation,useryresponse_formatsolo se transmiten en generaciones JSON síncronas y ediciones multipart síncronas; las ediciones JSON y las tareas asíncronas descartan estos campos.- En los grupos que solo aceptan 1, un
nmayor devuelve 400; unn≤ 0 se trata como 1. input_fidelityes un campo de compatibilidad; GPT Image 2 procesa las referencias con alta fidelidad por defecto.- El número de referencias lo verifica el servicio oficial: el gateway no cuenta las imágenes, y el servicio puede rechazar la solicitud o ignorar algunas.
- La referencia oficial no indica un límite agregado en MB para todas las referencias; una cadena URL / Data URL en JSON admite hasta 20.971.520 caracteres.
- 4 MiB es un objetivo de compresión antes de reenviar, no un umbral de rechazo; Base64 añade aproximadamente un tercio al tamaño de los datos.
- Ejemplo de Data URL:
data:image/png;base64,iVBORw0KGgo…; envíe la codificación completa con el tipo MIME correcto. - Al enviar una tarea asíncrona solo se comprueba que el saldo sea mayor que 0; no se reserva ningún importe.
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.
| Error | Qué hacer |
|---|---|
size must be WIDTHxHEIGHT or auto y otros errores de size | Ajuste el valor según las reglas de size |
prompt must not be empty | Envíe un prompt no vacío |
n must be 1 for this model in the current group | Divida en solicitudes separadas |
/v1/images/edits requires at least one image | Ponga las referencias en image, no en images |
image download returned HTTP 404 | Use 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 cuerpo | Falló tras iniciarse el keepalive; revise error.message |
# 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. 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
- 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