Editar imágenes

Imagen a imagen / edición de imágenes: GPT Image (con mask), Seedream y Gemini del grupo "Gemini (todos los modelos, incl. imagen)".

POST/v1/images/edits

Genera a partir de imágenes de referencia o edita zonas concretas. Se recomienda multipart/form-data (archivos locales; campo de referencia image / image[], repetible); también acepta JSON (referencias como URL HTTP(S) o Data URL). Ambas formas usan los mismos nombres de campo. El ejemplo de la derecha usa JSON; para multipart consulte la guía de generación de imágenes.

La edición por JSON y las tareas asíncronas no conservan output_compression, moderation, user ni response_format. El grupo "Gemini oficial directo" no tiene este endpoint; envíe las referencias en Generar imágenes.

Editar imágenes

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Convierte la imagen de referencia en un óleo al estilo de La noche estrellada de Van Gogh",
    "image": "https://example.com/input.png",
    "size": "1536x1024",
    "quality": "medium"
  }'

200application/json

{
  "created": 1790222400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 1310,
    "output_tokens": 1056,
    "total_tokens": 2366
  }
}

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

image:obligatoriostring o array of string

Archivos multipart (image / image[]), o en JSON una cadena o array de cadenas con URL HTTP(S) / Data URL. No lee images y no acepta base64 sin prefijo ni file_id; puede comprimirse antes de reenviar

Límites1–16 imágenes (límite oficial); URL remota ≤ 26214400 bytes por imagen y debe devolver image/*. Solo lee image, no images

mask:opcionalstring

Las zonas transparentes indican qué editar; el gateway escala la máscara al tamaño de la primera imagen de referencia; no se garantiza que lo que queda fuera de la máscara quede idéntico píxel a píxel

LímitesPNG con canal alfa; las zonas transparentes indican qué editar

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

model:obligatorio"gpt-image-2.5-flare"

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

Valoresautolowmediumhighxhighmax

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

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

image:obligatoriostring o array of string

Límites1–16 imágenes (límite oficial); URL remota ≤ 26214400 bytes por imagen y debe devolver image/*. Solo lee image, no images

mask:opcionalstring

LímitesPNG con canal alfa; las zonas transparentes indican qué editar

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

model:obligatorio"gpt-image-2.5-sunburst"

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

Valoresautolowmediumhighxhighmax

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

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

image:obligatoriostring o array of string

Límites1–16 imágenes (límite oficial); URL remota ≤ 26214400 bytes por imagen y debe devolver image/*. Solo lee image, no images

mask:opcionalstring

LímitesPNG con canal alfa; las zonas transparentes indican qué editar

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

model:obligatorio"gemini-3.1-flash-image"

Según lo que devuelve GET /v1/models para la clave actual

prompt:obligatoriostring

Si el modelo se niega o solo responde con texto, devuelve 400 (el mensaje cita ese texto) o 502: reformule el prompt

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

n:opcionalinteger

Se generan en paralelo. Todo o nada: si falla una, falla toda la solicitud y no se factura

LímitesTope según el nivel de salida: 1K ≤ 10, 2K ≤ 5Rango1–10Predeterminado1

image_size:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size

Valores1K2K

Predeterminado"1K"

aspect_ratio:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.aspect_ratio; tiene prioridad sobre size

Valores1:12:33:23:44:34:55:49:1616:921:9

Predeterminado"1:1"

size:opcional"auto" o string

anchoxalto nunca se rechaza por la proporción: se asigna a la proporción oficial más cercana y el nivel se deduce del lado largo, bajando sin aviso al nivel máximo del modelo. Un 1K / 2K / 4K explícito por encima del nivel del modelo devuelve 400; si también se envía image_size, prevalece este

Valores1K2K

Límitesauto, anchoxalto con cualquier proporción (se asigna a la proporción oficial más cercana; el nivel se deduce del lado largo y baja sin aviso al nivel máximo del modelo) o un nivel del modelo

google:opcionalobject

En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes

image:opcionalstring o array of string

Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits

images:opcionalstring o array of string

Igual que image; si se envían ambas, prevalece images

LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14

mask:no compatible

No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt

background:opcionalany

No admite transparent (devuelve 400)

No puede ser"transparent"

stream:opcionalany

No admitido; omítalo o envíe false

No puede sertrue

Con salida 2K, como máximo 5 imágenes por solicitud (límite de tamaño de la respuesta)

model:obligatorio"gemini-3.1-flash-image-preview"

Según lo que devuelve GET /v1/models para la clave actual

prompt:obligatoriostring

Si el modelo se niega o solo responde con texto, devuelve 400 (el mensaje cita ese texto) o 502: reformule el prompt

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

n:opcionalinteger

Se generan en paralelo. Todo o nada: si falla una, falla toda la solicitud y no se factura

LímitesTope según el nivel de salida: 1K ≤ 10, 2K ≤ 5Rango1–10Predeterminado1

image_size:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size

Valores1K2K

Predeterminado"1K"

aspect_ratio:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.aspect_ratio; tiene prioridad sobre size

Valores1:12:33:23:44:34:55:49:1616:921:9

Predeterminado"1:1"

size:opcional"auto" o string

Valores1K2K

google:opcionalobject

En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes

image:opcionalstring o array of string

images:opcionalstring o array of string

Igual que image; si se envían ambas, prevalece images

LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14

mask:no compatible

No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt

background:opcionalany

No admite transparent (devuelve 400)

No puede ser"transparent"

stream:opcionalany

No admitido; omítalo o envíe false

No puede sertrue

Con salida 2K, como máximo 5 imágenes por solicitud (límite de tamaño de la respuesta)

model:obligatorio"gemini-3-pro-image"

Según lo que devuelve GET /v1/models para la clave actual

prompt:obligatoriostring

Si el modelo se niega o solo responde con texto, devuelve 400 (el mensaje cita ese texto) o 502: reformule el prompt

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

n:opcionalinteger

Se generan en paralelo. Todo o nada: si falla una, falla toda la solicitud y no se factura

LímitesTope según el nivel de salida: 1K ≤ 10, 2K ≤ 5, 4K ≤ 2Rango1–10Predeterminado1

image_size:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size

Valores1K2K4K

Predeterminado"1K"

aspect_ratio:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.aspect_ratio; tiene prioridad sobre size

Valores1:12:33:23:44:34:55:49:1616:921:9

Predeterminado"1:1"

size:opcional"auto" o string

Valores1K2K4K

google:opcionalobject

En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes

image:opcionalstring o array of string

images:opcionalstring o array of string

Igual que image; si se envían ambas, prevalece images

LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14

mask:no compatible

No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt

background:opcionalany

No admite transparent (devuelve 400)

No puede ser"transparent"

stream:opcionalany

No admitido; omítalo o envíe false

No puede sertrue

Con salida 2K, como máximo 5 imágenes por solicitud (límite de tamaño de la respuesta)
Con salida 4K, como máximo 2 imágenes por solicitud (límite de tamaño de la respuesta)

model:obligatorio"gemini-3.1-flash-lite-image"

Según lo que devuelve GET /v1/models para la clave actual

prompt:obligatoriostring

Si el modelo se niega o solo responde con texto, devuelve 400 (el mensaje cita ese texto) o 502: reformule el prompt

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

n:opcionalinteger

Se generan en paralelo. Todo o nada: si falla una, falla toda la solicitud y no se factura

LímitesTope según el nivel de salida: 1K ≤ 10Rango1–10Predeterminado1

image_size:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size

Valores1K

Predeterminado"1K"

aspect_ratio:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.aspect_ratio; tiene prioridad sobre size

Valores1:12:33:23:44:34:55:49:1616:921:9

Predeterminado"1:1"

size:opcional"auto" o string

Valores1K

google:opcionalobject

En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes

image:opcionalstring o array of string

images:opcionalstring o array of string

Igual que image; si se envían ambas, prevalece images

LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14

mask:no compatible

No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt

background:opcionalany

No admite transparent (devuelve 400)

No puede ser"transparent"

stream:opcionalany

No admitido; omítalo o envíe false

No puede sertrue

model:obligatorio"gemini-2.5-flash-image"

Según lo que devuelve GET /v1/models para la clave actual

prompt:obligatoriostring

Si el modelo se niega o solo responde con texto, devuelve 400 (el mensaje cita ese texto) o 502: reformule el prompt

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

n:opcionalinteger

Se generan en paralelo. Todo o nada: si falla una, falla toda la solicitud y no se factura

LímitesTope según el nivel de salida: 1K ≤ 10Rango1–10Predeterminado1

image_size:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size

Valores1K

Predeterminado"1K"

aspect_ratio:opcionalstring

Forma plana de nivel superior, equivalente a google.image_config.aspect_ratio; tiene prioridad sobre size

Valores1:12:33:23:44:34:55:49:1616:921:9

Predeterminado"1:1"

size:opcional"auto" o string

Valores1K

google:opcionalobject

En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes

image:opcionalstring o array of string

images:opcionalstring o array of string

Igual que image; si se envían ambas, prevalece images

LímitesImágenes de referencia: cadena o array de cadenas, como máximo 3

mask:no compatible

No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt

background:opcionalany

No admite transparent (devuelve 400)

No puede ser"transparent"

stream:opcionalany

No admitido; omítalo o envíe false

No puede sertrue

Respuesta

200Éxito síncrono

202Con Prefer: respond-async

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)

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

Encabezados

Parámetros del cuerpoJSON

Respuesta

Errores

Páginas relacionadas