Editar imágenes
Imagen a imagen / edición de imágenes: GPT Image (con mask), Seedream y Gemini del grupo "Gemini económico (AI Studio / Vertex)".
/v1/images/editsGenera 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 (empresarial)" no tiene este endpoint; envíe las referencias en Generar imágenes.
Las respuestas sin streaming que generan un cargo devuelven el cargo real de la solicitud: los encabezados X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency y cost / cost_usd / currency en el objeto usage de nivel superior del cuerpo (los campos existentes de usage se conservan). cost_usd es el importe en USD realmente descontado del saldo; cost es el mismo cargo en CNY, y currency es siempre CNY. Las respuestas en streaming (SSE) no lo incluyen; consulta Uso en la consola. Las respuestas sin cargo, como los errores, no incluyen ninguno. Consulte API de cuenta · Cargos.
Encabezados
Bearer sk-…: una clave de API creada en la consola; su grupo debe incluir el modelo solicitado
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
data[].b64_json. Hasta 16 imágenes de referencia.Confirme primero que GET /v1/models de la clave actual incluye este ID
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
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
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
Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1
Rango1–10Predeterminado1
transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa
Valoresautoopaquetransparent
Determina el formato de b64_json una vez decodificado
Valorespngjpegwebp
Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart
Rango0–100Predeterminado100
No desactiva la revisión de seguridad del contenido
Valoresautolow
Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura
Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo
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
Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo
Valoreslowhigh
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
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
Confirme primero que GET /v1/models de la clave actual incluye este ID
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
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
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
Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1
Rango1–10Predeterminado1
transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa
Valoresautoopaquetransparent
Determina el formato de b64_json una vez decodificado
Valorespngjpegwebp
Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart
Rango0–100Predeterminado100
No desactiva la revisión de seguridad del contenido
Valoresautolow
Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura
Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo
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
Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo
Valoreslowhigh
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
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
Confirme primero que GET /v1/models de la clave actual incluye este ID
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
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
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
Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1
Rango1–10Predeterminado1
transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa
Valoresautoopaquetransparent
Determina el formato de b64_json una vez decodificado
Valorespngjpegwebp
Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart
Rango0–100Predeterminado100
No desactiva la revisión de seguridad del contenido
Valoresautolow
Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura
Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo
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
Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo
Valoreslowhigh
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
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
Confirme primero que GET /v1/models de la clave actual incluye este ID
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
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
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
Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1
Rango1–10Predeterminado1
transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa
Valoresautoopaquetransparent
Determina el formato de b64_json una vez decodificado
Valorespngjpegwebpsvggif
Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart
Rango0–100Predeterminado100
No desactiva la revisión de seguridad del contenido
Valoresautolow
Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura
Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo
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
Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo
Valoreslowhigh
Cuánto planifica el modelo antes de renderizar; sin cargo adicional. Otros valores devuelven 400 en el gateway
Valoreslowmediumhigh
Predeterminado"high"
Solo con output_format=gif: número de fotogramas. En gif, 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 tamaño pequeño como 512x512
Rango2–16Predeterminado9
Solo con output_format=gif: duración de cada fotograma (milisegundos)
Rango20–2000Predeterminado200
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
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
Solo GPT Image 2.6: una superposición PNG transparente con círculos, flechas o notas dibujados, del mismo tamaño que la primera imagen de entrada; el modelo edita según las anotaciones. No se puede combinar con mask
- transparent requiere png o webp
- output_compression solo aplica a jpeg / webp
- n debe ser 1 cuando output_format=svg
- markup no se puede combinar con mask
Confirme primero que GET /v1/models de la clave actual incluye este ID
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
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
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
Algunos grupos solo admiten 1 y un valor mayor devuelve 400; ≤ 0 se trata como 1
Rango1–10Predeterminado1
transparent requiere png o webp; el fondo transparente en 2.0 es una función en vista previa
Valoresautoopaquetransparent
Determina el formato de b64_json una vez decodificado
Valorespngjpegwebpsvggif
Solo jpeg / webp; solo se conserva en el JSON síncrono de generations y en la edición multipart
Rango0–100Predeterminado100
No desactiva la revisión de seguridad del contenido
Valoresautolow
Cadena de identificación del usuario final; no es un ID de cuenta de HopBase ni cambia a quién se factura
Envíe lo que envíe, se devuelve b64_json; no se puede obtener un enlace de descarga con url. Omítalo
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
Campo de compatibilidad; GPT Image 2 ya procesa las referencias en alta fidelidad por defecto. Omítalo
Valoreslowhigh
Cuánto planifica el modelo antes de renderizar; sin cargo adicional. Otros valores devuelven 400 en el gateway
Valoreslowmediumhigh
Predeterminado"high"
Solo con output_format=gif: número de fotogramas. En gif, 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 tamaño pequeño como 512x512
Rango2–16Predeterminado9
Solo con output_format=gif: duración de cada fotograma (milisegundos)
Rango20–2000Predeterminado200
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
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
Solo GPT Image 2.6: una superposición PNG transparente con círculos, flechas o notas dibujados, del mismo tamaño que la primera imagen de entrada; el modelo edita según las anotaciones. No se puede combinar con mask
- transparent requiere png o webp
- output_compression solo aplica a jpeg / webp
- n debe ser 1 cuando output_format=svg
- markup no se puede combinar con mask
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K2K
Predeterminado"1K"
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"
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K2K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
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)
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K2K
Predeterminado"1K"
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"
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K2K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
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)
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K2K4K
Predeterminado"1K"
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"
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
Valores1K2K4K
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K2K4K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
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)
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K2K4K
Predeterminado"1K"
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"
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
Valores1K2K4K
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K2K4K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
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)
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K
Predeterminado"1K"
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"
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
Valores1K
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 14
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
No admitido; omítalo o envíe false
No puede sertrue
Según lo que devuelve GET /v1/models para la clave actual
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
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
Forma plana de nivel superior, equivalente a google.image_config.image_size; sustituye el nivel deducido de size
Valores1K
Predeterminado"1K"
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"
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
Valores1K
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
En el SDK puede escribirse como extra_body.google.image_config; las tres formas son equivalentes
Valores1:12:33:23:44:34:55:49:1616:921:9
Valores1K
Imágenes de referencia; basta con incluirlas en el cuerpo de generations. Si se envían ambas, prevalece images. En "Gemini oficial directo (empresarial)", cada imagen decodificada ≤ 20 MiB y no hay /v1/images/edits
Igual que image; si se envían ambas, prevalece images
LímitesImágenes de referencia: cadena o array de cadenas, como máximo 3
No admitido: enviar mask devuelve 400; para ediciones locales, describa la zona en el prompt
No admite transparent (devuelve 400)
No puede ser"transparent"
No admitido; omítalo o envíe false
No puede sertrue
Use el ID completo que devuelve GET /v1/models para la clave actual
Contenido, composición, estilo o instrucción de edición; para ediciones locales puede describir coordenadas, bbox, flechas o zonas marcadas en la imagen de referencia
LímitesTras quitar los espacios al inicio y al final no puede quedar vacío; si no, 400 "missing prompt"Longitud≥ 1 caracteres
Un valor no válido devuelve 400 antes de generar, indicando el intervalo permitido, sin facturar
Valores1K1.5K2K
LímitesAbreviatura 1K / 1.5K / 2K, o anchoxalto: 921600–4624220 píxeles en total, relación de aspecto de 1:16 a 16:1
Otros valores (incluido null) devuelven 400
Límitesonly a single output is supported (n=1)Predeterminado1
url devuelve un enlace firmado válido 24 horas; b64_json devuelve data[].b64_json. Un grupo sin streaming no puede usar b64_json (requiere stream: true)
Valoresurlb64_json
Predeterminado"url"
En 4.5 solo jpeg
Valorespngjpeg
Debe ser un objeto
Valoresstandard
Al enviarlo se activa imagen a imagen o edición con una o varias imágenes; /v1/images/edits requiere al menos 1. Las URL no se descargan ni se comprueba su tamaño al enviar
LímitesImágenes de referencia (al enviarlas, imagen a imagen / edición): como máximo 10; Data URL ≤ 31457280 bytes por imagen; las URL no se descargan al enviar
Solo seedream-5-0-pro: true divide una imagen de entrada PNG / JPEG en una imagen base más hasta 16 capas PNG transparentes; prompt pasa a ser opcional y size solo acepta 1K / 1.5K / 2K / auto (por defecto auto). Unos 1,5 minutos a 1K; configure el tiempo de espera del cliente en ≥ 5 minutos. Vea Seedream · Descomposición en capas
LímitesNo admite descomposición en capas: enviar true devuelve 400 «model seedream-5-5 does not support layer_decomposition»No puede sertrue
Aquí el valor por defecto es false (el oficial es true); pase true para añadir marca de agua
Predeterminadofalse
Solo seedream-5-5 / seedream-5-0-pro: transparent es solo para imagen a imagen y exige exactamente una imagen de entrada con canal alfa (las Data URL JPEG / BMP devuelven 400); la salida es PNG, así que no admite output_format: jpeg. Vea Seedream · Fondo transparente
Valoresopaquetransparent
Predeterminado"opaque"
Solo seedream-5-0-lite / seedream-4-5: auto activa la generación en grupo y el modelo decide según el prompt cuántas imágenes crear (hasta max_images). Una imagen fallida llega en data[].error y no se cobra; si fallan todas, devuelve 400. Para un grupo sin streaming el servidor espera hasta unos 280 segundos, así que se recomienda stream: true. Vea Seedream · Generación en grupo
max_images es un entero de 1 a 15, y las imágenes de referencia más max_images ≤ 15; en multipart escriba sequential_image_generation_options[max_images] o max_images
Solo seedream-5-0-lite / seedream-4-5: true devuelve SSE, con image_generation.partial_succeeded / image_generation.partial_failed por imagen y luego image_generation.completed y data: [DONE]. Se cobran las imágenes correctas; las respuestas en streaming no llevan los campos de cargo. Vea Seedream · Streaming
LímitesNo admitido: enviar true devuelve 400 «model seedream-5-5 does not support stream»No puede sertrue
La búsqueda web aún no se admite; enviarla devuelve 400
No admitido: /v1/images/edits con mask devuelve 400 (también con null)
- background transparent: exactamente una imagen de entrada con canal alfa, salida png
Use el ID completo que devuelve GET /v1/models para la clave actual
Contenido, composición, estilo o instrucción de edición; para ediciones locales puede describir coordenadas, bbox, flechas o zonas marcadas en la imagen de referencia
LímitesNo puede quedar vacío tras recortar espacios; si no, 400 «missing prompt». Opcional con layer_decomposition: trueLongitud≥ 1 caracteres
Un valor no válido devuelve 400 antes de generar, indicando el intervalo permitido, sin facturar
Valores1K1.5K2K
LímitesAbreviatura 1K / 1.5K / 2K, o anchoxalto: 921600–4624220 píxeles en total, relación de aspecto de 1:16 a 16:1; la descomposición en capas solo acepta 1K / 1.5K / 2K / auto (por defecto auto)
Otros valores (incluido null) devuelven 400
Límitesonly a single output is supported (n=1)Predeterminado1
url devuelve un enlace firmado válido 24 horas; b64_json devuelve data[].b64_json. Un grupo sin streaming no puede usar b64_json (requiere stream: true)
Valoresurlb64_json
Predeterminado"url"
En 4.5 solo jpeg
Valorespngjpeg
Debe ser un objeto
Valoresstandardfast
Al enviarlo se activa imagen a imagen o edición con una o varias imágenes; /v1/images/edits requiere al menos 1. Las URL no se descargan ni se comprueba su tamaño al enviar
LímitesImágenes de referencia (al enviarlas, imagen a imagen / edición): como máximo 10; Data URL ≤ 31457280 bytes por imagen; las URL no se descargan al enviar
Solo seedream-5-0-pro: true divide una imagen de entrada PNG / JPEG en una imagen base más hasta 16 capas PNG transparentes; prompt pasa a ser opcional y size solo acepta 1K / 1.5K / 2K / auto (por defecto auto). Unos 1,5 minutos a 1K; configure el tiempo de espera del cliente en ≥ 5 minutos. Vea Seedream · Descomposición en capas
Predeterminadofalse
Aquí el valor por defecto es false (el oficial es true); pase true para añadir marca de agua
Predeterminadofalse
Solo seedream-5-5 / seedream-5-0-pro: transparent es solo para imagen a imagen y exige exactamente una imagen de entrada con canal alfa (las Data URL JPEG / BMP devuelven 400); la salida es PNG, así que no admite output_format: jpeg. Vea Seedream · Fondo transparente
Valoresopaquetransparent
Predeterminado"opaque"
Solo seedream-5-0-lite / seedream-4-5: auto activa la generación en grupo y el modelo decide según el prompt cuántas imágenes crear (hasta max_images). Una imagen fallida llega en data[].error y no se cobra; si fallan todas, devuelve 400. Para un grupo sin streaming el servidor espera hasta unos 280 segundos, así que se recomienda stream: true. Vea Seedream · Generación en grupo
max_images es un entero de 1 a 15, y las imágenes de referencia más max_images ≤ 15; en multipart escriba sequential_image_generation_options[max_images] o max_images
Solo seedream-5-0-lite / seedream-4-5: true devuelve SSE, con image_generation.partial_succeeded / image_generation.partial_failed por imagen y luego image_generation.completed y data: [DONE]. Se cobran las imágenes correctas; las respuestas en streaming no llevan los campos de cargo. Vea Seedream · Streaming
LímitesNo admitido: enviar true devuelve 400 «model seedream-5-0-pro does not support stream»No puede sertrue
La búsqueda web aún no se admite; enviarla devuelve 400
No admitido: /v1/images/edits con mask devuelve 400 (también con null)
- Descomposición en capas: prompt opcional, size solo por tramos (por defecto auto), exactamente una imagen de entrada PNG / JPEG
- background transparent: exactamente una imagen de entrada con canal alfa, salida png
Use el ID completo que devuelve GET /v1/models para la clave actual
Contenido, composición, estilo o instrucción de edición; para ediciones locales puede describir coordenadas, bbox, flechas o zonas marcadas en la imagen de referencia
LímitesTras quitar los espacios al inicio y al final no puede quedar vacío; si no, 400 "missing prompt"Longitud≥ 1 caracteres
Un valor no válido devuelve 400 antes de generar, indicando el intervalo permitido, sin facturar
Valores2K3K4K
LímitesAbreviatura 2K / 3K / 4K, o anchoxalto: 3686400–16777216 píxeles en total, relación de aspecto de 1:16 a 16:1
Otros valores (incluido null) devuelven 400
Límitesonly a single output is supported (n=1)Predeterminado1
url devuelve un enlace firmado válido 24 horas; b64_json devuelve data[].b64_json. Un grupo sin streaming no puede usar b64_json (requiere stream: true)
Valoresurlb64_json
Predeterminado"url"
En 4.5 solo jpeg
Valorespngjpeg
Debe ser un objeto
Valoresstandard
Al enviarlo se activa imagen a imagen o edición con una o varias imágenes; /v1/images/edits requiere al menos 1. Las URL no se descargan ni se comprueba su tamaño al enviar
LímitesImágenes de referencia (al enviarlas, imagen a imagen / edición): como máximo 14; Data URL ≤ 31457280 bytes por imagen; las URL no se descargan al enviar
Solo seedream-5-0-pro: true divide una imagen de entrada PNG / JPEG en una imagen base más hasta 16 capas PNG transparentes; prompt pasa a ser opcional y size solo acepta 1K / 1.5K / 2K / auto (por defecto auto). Unos 1,5 minutos a 1K; configure el tiempo de espera del cliente en ≥ 5 minutos. Vea Seedream · Descomposición en capas
LímitesNo admite descomposición en capas: enviar true devuelve 400 «model seedream-5-0-lite does not support layer_decomposition»No puede sertrue
Aquí el valor por defecto es false (el oficial es true); pase true para añadir marca de agua
Predeterminadofalse
Solo seedream-5-5 / seedream-5-0-pro: transparent es solo para imagen a imagen y exige exactamente una imagen de entrada con canal alfa (las Data URL JPEG / BMP devuelven 400); la salida es PNG, así que no admite output_format: jpeg. Vea Seedream · Fondo transparente
Solo seedream-5-0-lite / seedream-4-5: auto activa la generación en grupo y el modelo decide según el prompt cuántas imágenes crear (hasta max_images). Una imagen fallida llega en data[].error y no se cobra; si fallan todas, devuelve 400. Para un grupo sin streaming el servidor espera hasta unos 280 segundos, así que se recomienda stream: true. Vea Seedream · Generación en grupo
Valoresautodisabled
Predeterminado"disabled"
max_images es un entero de 1 a 15, y las imágenes de referencia más max_images ≤ 15; en multipart escriba sequential_image_generation_options[max_images] o max_images
Máximo de imágenes del grupo; referencias + max_images ≤ 15
Rango1–15
Solo seedream-5-0-lite / seedream-4-5: true devuelve SSE, con image_generation.partial_succeeded / image_generation.partial_failed por imagen y luego image_generation.completed y data: [DONE]. Se cobran las imágenes correctas; las respuestas en streaming no llevan los campos de cargo. Vea Seedream · Streaming
Predeterminadofalse
La búsqueda web aún no se admite; enviarla devuelve 400
No admitido: /v1/images/edits con mask devuelve 400 (también con null)
- Un grupo sin streaming no puede usar b64_json (requiere stream=true)
Use el ID completo que devuelve GET /v1/models para la clave actual
Contenido, composición, estilo o instrucción de edición; para ediciones locales puede describir coordenadas, bbox, flechas o zonas marcadas en la imagen de referencia
LímitesTras quitar los espacios al inicio y al final no puede quedar vacío; si no, 400 "missing prompt"Longitud≥ 1 caracteres
Un valor no válido devuelve 400 antes de generar, indicando el intervalo permitido, sin facturar
Valores2K4K
LímitesAbreviatura 2K / 4K, o anchoxalto: 3686400–16777216 píxeles en total, relación de aspecto de 1:16 a 16:1
Otros valores (incluido null) devuelven 400
Límitesonly a single output is supported (n=1)Predeterminado1
url devuelve un enlace firmado válido 24 horas; b64_json devuelve data[].b64_json. Un grupo sin streaming no puede usar b64_json (requiere stream: true)
Valoresurlb64_json
Predeterminado"url"
En 4.5 solo jpeg
Valoresjpeg
Debe ser un objeto
Valoresstandard
Al enviarlo se activa imagen a imagen o edición con una o varias imágenes; /v1/images/edits requiere al menos 1. Las URL no se descargan ni se comprueba su tamaño al enviar
LímitesImágenes de referencia (al enviarlas, imagen a imagen / edición): como máximo 14; Data URL ≤ 31457280 bytes por imagen; las URL no se descargan al enviar
Solo seedream-5-0-pro: true divide una imagen de entrada PNG / JPEG en una imagen base más hasta 16 capas PNG transparentes; prompt pasa a ser opcional y size solo acepta 1K / 1.5K / 2K / auto (por defecto auto). Unos 1,5 minutos a 1K; configure el tiempo de espera del cliente en ≥ 5 minutos. Vea Seedream · Descomposición en capas
LímitesNo admite descomposición en capas: enviar true devuelve 400 «model seedream-4-5 does not support layer_decomposition»No puede sertrue
Aquí el valor por defecto es false (el oficial es true); pase true para añadir marca de agua
Predeterminadofalse
Solo seedream-5-5 / seedream-5-0-pro: transparent es solo para imagen a imagen y exige exactamente una imagen de entrada con canal alfa (las Data URL JPEG / BMP devuelven 400); la salida es PNG, así que no admite output_format: jpeg. Vea Seedream · Fondo transparente
Solo seedream-5-0-lite / seedream-4-5: auto activa la generación en grupo y el modelo decide según el prompt cuántas imágenes crear (hasta max_images). Una imagen fallida llega en data[].error y no se cobra; si fallan todas, devuelve 400. Para un grupo sin streaming el servidor espera hasta unos 280 segundos, así que se recomienda stream: true. Vea Seedream · Generación en grupo
Valoresautodisabled
Predeterminado"disabled"
max_images es un entero de 1 a 15, y las imágenes de referencia más max_images ≤ 15; en multipart escriba sequential_image_generation_options[max_images] o max_images
Máximo de imágenes del grupo; referencias + max_images ≤ 15
Rango1–15
Solo seedream-5-0-lite / seedream-4-5: true devuelve SSE, con image_generation.partial_succeeded / image_generation.partial_failed por imagen y luego image_generation.completed y data: [DONE]. Se cobran las imágenes correctas; las respuestas en streaming no llevan los campos de cargo. Vea Seedream · Streaming
Predeterminadofalse
La búsqueda web aún no se admite; enviarla devuelve 400
No admitido: /v1/images/edits con mask devuelve 400 (también con null)
- Un grupo sin streaming no puede usar b64_json (requiere stream=true)
Respuesta
200Éxito síncrono
202Con Prefer: respond-async
Encabezados de respuesta
Cargo de esta solicitud en CNY (el mismo cargo que X-HopBase-Cost-USD), con hasta 6 decimales, por ejemplo 0.0816. Solo se envía cuando la solicitud genera un cargo; no se envía en respuestas en streaming (SSE). Si la generación de imágenes tarda más de unos 40 segundos, los encabezados ya se enviaron: lee usage.cost en el cuerpo
Importe en USD realmente descontado del saldo por esta solicitud, el mismo que su registro de uso, con hasta 8 decimales, como 0.012; solo se envía junto con X-HopBase-Cost
Moneda de X-HopBase-Cost, siempre CNY
Segundos Unix
Un elemento por imagen
GPT Image / Gemini: datos de imagen en Base64; al decodificar, guárdelos según output_format. Gemini puede devolver JPEG; consulte mime_type. Seedream también devuelve este campo con response_format: b64_json
Seedream: enlace directo firmado válido 24 horas; al caducar solo queda volver a generar
Generación en grupo de Seedream: esta imagen falló (normalmente por moderación de contenido) y no se cobra
Código de error
Motivo del fallo
Seedream: WIDTHxHEIGHT real de la salida
Descomposición en capas de Seedream: la imagen base sigue el output_format solicitado; las capas son siempre png
Descomposición en capas de Seedream: 0 es la imagen base; las capas empiezan en 1 y se apilan en orden ascendente
Descomposición en capas de Seedream (solo capas): posición de la capa en la imagen base
[left, top, right, bottom] en píxeles de la imagen base
El mismo recuadro, normalizado de 0 a 999
Descomposición en capas de Seedream (solo capas): nombre de la capa
Descomposición en capas de Seedream (solo capas): contenido de la capa
MIME de la imagen
Prompt reescrito por el modelo (algunos modelos)
Puede devolverse
Tokens de entrada
Tokens de salida
Total
Grok Imagine: medición propia de xAI en unidades de 1e-10 USD al precio oficial; no es su cargo. El importe en USD realmente descontado del saldo es cost_usd, y cost es el mismo cargo en CNY
Añadido por la pasarela: el cargo de esta solicitud en CNY (el mismo cargo que cost_usd), igual que el encabezado X-HopBase-Cost; no se devuelve en streaming
Añadido por la pasarela: el importe en USD realmente descontado del saldo, igual que el encabezado X-HopBase-Cost-USD y el registro de uso; no se devuelve en streaming
Añadido por la pasarela: la moneda de cost, siempre CNY
Errores
missing_api_key / invalid_api_key / api_key_expired)insufficient_quota)model_not_found) o la ruta no pertenece a ese grupo (route_not_found)request_too_large)user_concurrency_limit / apikey_concurrency_limit), con Retry-After