Saltar al contenido
HopBase Docs
Iniciar sesión

Generar imágenes

Texto a imagen compatible con OpenAI Images: GPT Image, Gemini Banana y Seedream; Seedream y Gemini también reciben aquí imágenes de referencia.

POST/v1/images/generations

Genera imágenes a partir de un prompt. GPT Image y Gemini devuelven data[].b64_json; Seedream devuelve data[].url (válido 24 horas). Seedream y los dos grupos de Gemini también hacen imagen a imagen en este endpoint con image / images.

Cada modelo tiene parámetros y límites distintos: elija un modelo abajo y la tabla de parámetros cambia con él; las cifras provienen de las especificaciones que exporta el código de validación del plugin (la misma fuente que /spec/models/<model>.json). Cuando GPT Image tarda más de unos 40 segundos, el servidor responde primero 200 y escribe espacios en blanco para mantener viva la conexión, así que un fallo posterior también llega con 200: determine el resultado según si el cuerpo contiene error y use en el cliente un tiempo de espera de lectura de al menos 300 segundos.

Kling y Midjourney también se envían en este endpoint, pero siempre de forma asíncrona (202 + id; consulte con Consultar una tarea de video); elija «Kling» o «Midjourney» en el selector de modelo para verlos. Para Grok Imagine, vea generación de imágenes de Grok Imagine.

  • GPT Image no admite el campo oficial de streaming partial_images; omítalo. stream: true devuelve SSE de Images de HopBase, no eventos de vista previa por imagen.
  • output_compression, moderation, user y response_format solo se reenvían en texto a imagen síncrono JSON y en edición multipart síncrona; la edición JSON y las tareas asíncronas no conservan estos campos. En modo asíncrono, GPT Image solo conserva model, prompt, n, size, quality, background, output_format, input_fidelity y las imágenes / mask de edición.
  • Facturación de Gemini: «Gemini (todos los modelos, incl. imagen)» factura un precio fijo por imagen (igual para 1K / 2K / 4K); «Gemini oficial directo» factura por tokens (tokens de salida × precio).
  • La ruta puente de Chat Completions a Images solo conserva las primeras 6 imágenes de referencia; para usar 14, llame directamente a este endpoint.

Encabezados

Authorization:obligatoriostring

Bearer sk-…: una clave de API creada en la consola; su grupo debe incluir el modelo solicitado

Prefer:opcionalstring

respond-async: GPT Image / Gemini devuelven de inmediato 202 Accepted, task_id y status_url; después consulte con GET /v1/images/tasks?task_id=…. Recomendado para imágenes grandes 2K / 4K; Seedream ignora esta cabecera y responde de forma síncrona como siempre

Valoresrespond-async

Parámetros del cuerpoJSON

ModeloAbrir en el constructor de solicitudes de imagen Documentación del modelo
Grupo: GPT Image (todos los modelos). Lee el resultado en data[].b64_json. Hasta 16 imágenes de referencia.
model:obligatorio"gpt-image-2"

Confirme primero que GET /v1/models de la clave actual incluye este ID

prompt:obligatoriostring

Instrucción de generación o edición; si está vacío devuelve 400 prompt must not be empty. El gateway no limita la longitud; el máximo es el límite oficial

LímitesTras quitar los espacios al inicio y al final no puede quedar vacío; si no, 400 "prompt must not be empty"Longitud1–32000 caracteres

size:opcional"auto" o string

Ejemplos: 1024x1024, 2048x2048, 3840x2160. Un valor no válido devuelve 400 antes de generar, sin facturar; no acepta 1K / 2K / 4K

Límitesauto o anchoxalto: lados múltiplos de 16, cada lado ≤ 3840, relación lado largo/corto ≤ 3:1, 655360–8294400 píxeles en total

quality:opcionalstring

Cuanto más alto el nivel, más tokens de salida y mayor costo: en pruebas con 1024x1024, low da unos 200, high unos 1,760, xhigh unos 3,120 y max unos 7,020 tokens de salida

Valoresautolowmediumhigh

LímitesEl gateway no lo valida y lo reenvía sin cambios; cuanto más alto el nivel, más tokens de salida

n:opcionalinteger

Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1

Rango1–10Predeterminado1

background:opcionalstring

transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa

Valoresautoopaquetransparent

output_format:opcionalstring

Determina el formato de b64_json una vez decodificado

Valorespngjpegwebp

output_compression:opcionalinteger

Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart

Rango0–100Predeterminado100

moderation:opcionalstring

No desactiva la revisión de seguridad del contenido

Valoresautolow

user:opcionalstring

Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura

response_format:opcionalstring

Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo

stream:opcionalboolean

true cambia a SSE de Images de HopBase (envía keepalive durante la espera; solo el último evento data: contiene el JSON de Images y termina con [DONE]), no los eventos nativos de vista previa imagen por imagen de OpenAI; en el SDK mantenga false

Límitestrue devuelve SSE de Images de HopBase; en el SDK mantenga falsePredeterminadofalse

input_fidelity:opcionalstring

Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo

Valoreslowhigh

  • transparent requiere png o webp
  • output_compression solo aplica a jpeg / webp

Respuesta

200Éxito síncrono

202Aceptado de forma asíncrona: GPT Image / Gemini con Prefer: respond-async; Kling y Midjourney siempre

created:opcionalinteger

Segundos Unix

data:obligatorioarray of object

Un elemento por imagen

usage:opcionalobject

Puede devolverse

Errores

400Parámetros no válidos (rechazo antes de generar, sin facturar); bloqueo por seguridad de contenido safety_rejected
401Falta la clave, la clave no es válida o ha caducado (missing_api_key / invalid_api_key / api_key_expired)
402Se agotó el saldo o la cuota de la clave, del miembro o del departamento (insufficient_quota)
404El modelo no está en el grupo de esta clave (model_not_found) o la ruta no pertenece a ese grupo (route_not_found)
413El cuerpo de la solicitud supera 60 MB (request_too_large)
429Se alcanzó el límite de concurrencia de la cuenta o de la clave (user_concurrency_limit / apikey_concurrency_limit), con Retry-After
Mensajes de error de GPT Image
# 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: ponga las 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)
Mensajes de error de Gemini
# Gemini (todos los modelos, incl. imagen)
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# Gemini oficial directo
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type
Mensajes de error de Seedream
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size   # p. ej. "size": "auto"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference            # /v1/images/edits sin imagen
seedream does not accept a traditional mask; ...            # cualquier "mask" en /v1/images/edits, incluso null

Páginas relacionadas