Seedream
Genere y edite imágenes con Seedream: parámetros, respuestas y advertencias.
| Elemento | Valor |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| Generar (incl. edición con referencias) | POST /v1/images/generations |
| Editar (entrada compatible multipart) | POST /v1/images/edits |
| Grupo de la clave | Generación de imágenes Seedream |
Seedream devuelve los resultados de forma síncrona (Lite y 4.5 también admiten streaming). n está fijado en 1, así que cada solicitud genera una imagen salvo con la generación en grupo o la descomposición en capas. Los enlaces son válidos durante 24 horas.
Modelos disponibles
| Modelo | ID del modelo | Abreviaturas de tamaño | Precio oficial |
|---|---|---|---|
| Seedream 5.5 | seedream-5-5 | 1K / 1.5K / 2K | $0,02desde/ imagen |
| Seedream 5.0 Pro | seedream-5-0-pro | 1K / 1.5K / 2K | $0,0225desde/ imagen |
| Seedream 5.0 Lite | seedream-5-0-lite | 2K / 3K / 4K | $0,035/ imagen |
| Seedream 4.5 | seedream-4-5 | 2K / 4K | $0,04/ imagen |
Cómo elegir: solo 5.5 y 5.0 Pro generan 1K, y en ambos 1.5K cuesta lo mismo que 1K y ofrece mejor calidad, así que prefiera 1.5K; Lite y 4.5 generan como mínimo 2K.
Parámetros de la solicitud
Generar
POST /v1/images/generations con cuerpo JSON. Si añade image, la solicitud pasa a ser una edición de una imagen, una composición de varias o una edición local.
| Parámetro | Obligatorio | Tipo y límites | Predeterminado | Descripción |
|---|---|---|---|---|
model | Obligatorio | Cadena, vea la tabla anterior | — | Use el ID que devuelve GET /v1/models con su clave |
prompt | Obligatorio | Cadena no vacía tras recortar espacios | — | Contenido, composición, estilo o instrucción; opcional con layer_decomposition |
size | Opcional | Abreviatura del modelo o WIDTHxHEIGHT | — | auto solo con layer_decomposition; píxeles abajo |
n | Opcional | Solo 1 | 1 | Otro valor (incl. null) devuelve 400; para varias imágenes use sequential_image_generation |
response_format | Opcional | Solo url / b64_json | url | url devuelve un enlace firmado; b64_json devuelve base64 en data[].b64_json |
output_format | Opcional | Según el modelo, abajo | — | Formato de la imagen |
optimize_prompt_options | Opcional | Objeto; mode según el modelo | — | Modo de optimización del prompt |
image | Opcional | URL / Data URL, cadena o array de cadenas | — | Referencias; activa imagen a imagen / edición |
layer_decomposition | Opcional | Booleano, solo seedream-5-0-pro | false | true divide una imagen de entrada en una imagen base más capas; vea Descomposición en capas |
background | Opcional | opaque / transparent, solo seedream-5-5 / seedream-5-0-pro | opaque | transparent exige exactamente una imagen de entrada con canal alfa; vea Fondo transparente |
watermark | Opcional | Booleano | false | true añade marca de agua (el valor oficial por defecto es true) |
sequential_image_generation | Opcional | auto / disabled, solo seedream-5-0-lite / seedream-4-5 | disabled | auto devuelve un grupo de imágenes; vea Generación en grupo |
sequential_image_generation_options | Opcional | Objeto; max_images es un entero de 1 a 15 | — | Máximo del grupo; imágenes de referencia más max_images ≤ 15 |
stream | Opcional | Booleano, solo seedream-5-0-lite / seedream-4-5 | false | true devuelve SSE; vea Streaming |
Límites por modelo:
| ID del modelo | Píxeles totales de size | Máx. referencias | output_format | optimize_prompt_options.mode |
|---|---|---|---|---|
seedream-5-5 | 921.600–4.624.220 | 10 | png / jpeg | standard |
seedream-5-0-pro | 921.600–4.624.220 | 10 | png / jpeg | standard / fast |
seedream-5-0-lite | 3.686.400–16.777.216 | 14 | png / jpeg | standard |
seedream-4-5 | 3.686.400–16.777.216 | 14 | jpeg | standard |
La relación de aspecto de WIDTHxHEIGHT debe estar entre 1:16–16:1. Un size no válido devuelve 400 antes de generar y no se cobra.
Cada elemento de image es una URL http(s) o una Data URL en base64; cada Data URL debe ocupar ≤ 30 MB. Formatos admitidos: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF. Las URL no se descargan ni se comprueban al enviar, y deben ser direcciones públicas accesibles para el servidor.
La edición local no usa máscara: dibuje la anotación sobre una referencia y describa en el prompt sus coordenadas, cuadro delimitador, flecha o zona pintada.
Editar
POST /v1/images/edits es una entrada compatible para código de edición de OpenAI Images ya existente. Se recomienda multipart/form-data, aunque también acepta el mismo JSON que generations. Requiere al menos 1 imagen de referencia.
| Parámetro | Obligatorio | Tipo y límites | Predeterminado | Descripción |
|---|---|---|---|---|
image / image[] | Obligatorio | Archivo o URL, repetible | — | Cada archivo ≤ 30 MB |
model, prompt | Obligatorio | Igual que en Generar | — | — |
size, n, response_format, output_format | Opcional | Igual que en Generar | — | — |
background, watermark, stream, sequential_image_generation | Opcional | Igual que en Generar | — | En multipart, los booleanos son las cadenas true / false |
sequential_image_generation_options[max_images] | Opcional | Mismo max_images que en Generar | — | También vale max_images |
optimize_prompt_options[mode] | Opcional | Mismo mode que en Generar | — | También vale optimize_prompt_mode |
layer_decomposition | Opcional | Igual que en Generar; en multipart, la cadena true | false | Exige exactamente una image |
Cualquier campo mask devuelve 400, incluso null. Los campos multipart que no aparecen en la tabla se ignoran.
Respuesta
Respuesta síncrona en el JSON estándar de OpenAI Images; las imágenes están en data[].url, o en data[].b64_json con response_format: b64_json. Con stream: true recibe SSE; vea Streaming.
| Campo | Tipo | Descripción |
|---|---|---|
created | integer | Segundos Unix |
model | string | ID del modelo solicitado |
data[].url | string | Enlace firmado, válido 24 horas |
data[].b64_json | string | Imagen en base64, solo con response_format: b64_json |
data[].error | object | Solo generación en grupo: esta imagen falló (code, message) y no se cobra |
data[].size | string | WIDTHxHEIGHT real de la salida |
usage | object | Puede aparecer, con generated_images y otros |
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 |
{
"model": "seedream-5-0-pro",
"created": 1760000000,
"data": [
{
"url": "https://…/result.jpeg?X-Signature=…",
"size": "2048x2048"
}
],
"usage": {
"generated_images": 1,
"output_tokens": 16384,
"total_tokens": 16384,
"cost": 1.53,
"cost_usd": 0.225,
"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, y las respuestas en streaming tampoco (revise el registro de consumo). Consulte Cargos.
La URL devuelta es un enlace firmado válido durante 24 horas. Una vez caducado no se puede recuperar y solo queda regenerar, lo que se vuelve a cobrar; descárguelo en cuanto lo reciba.
Ejemplos
Texto a imagen
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-su-clave" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "Calle futurista de noche con neones, encuadre de cine",
"size": "2048x2048",
"response_format": "url"
}'Editar con referencias
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-su-clave" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "Mueva la taza a la derecha; mantenga el resto",
"image": ["https://example.com/source.png"],
"size": "2K",
"output_format": "png",
"response_format": "url"
}'Generación en grupo
seedream-5-0-lite y seedream-4-5 pueden devolver un grupo de imágenes relacionadas en una sola solicitud (n sigue siendo 1). Envíe "sequential_image_generation": "auto": el modelo decide según el prompt cuántas imágenes crear, hasta sequential_image_generation_options.max_images (un entero de 1 a 15; las imágenes de referencia más max_images no pueden superar 15). Describa el grupo completo en el prompt, por ejemplo «cuatro ilustraciones del mismo personaje en cada estación». En multipart de /v1/images/edits, envíe sequential_image_generation_options[max_images] (o max_images).
- Solo se cobran las imágenes correctas. Una imagen que falla, normalmente por moderación de contenido, llega como
data[].errorconcodeymessagey no se cobra; si fallan todas, la solicitud devuelve 400 con el motivo. - Un grupo sin streaming responde cuando termina todo el grupo, y el servidor espera hasta unos 280 segundos. Para grupos grandes, añada
stream: truey reciba las imágenes una a una. Un grupo sin streaming no puede usarresponse_format: b64_json.
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"size": "2K"
}'Streaming
seedream-5-0-lite y seedream-4-5 aceptan "stream": true, para una imagen o un grupo; la respuesta es SSE (text/event-stream). seedream-5-5 y seedream-5-0-pro devuelven 400.
| Evento | data |
|---|---|
image_generation.partial_succeeded | Una imagen lista: image_index, url (o b64_json), size |
image_generation.partial_failed | Una imagen falló: image_index, error.code, error.message; no se cobra |
image_generation.completed | Fin: usage.generated_images, usage.output_tokens, usage.total_tokens |
El data de cada evento también lleva type, model y created; el flujo termina con data: [DONE]. Se cobran las imágenes correctas. Las respuestas en streaming no llevan usage.cost ni los encabezados X-HopBase-Cost; consulte la solicitud en el registro de consumo de la consola.
curl -N https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"stream": true
}'event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream-5-0-lite","created":1792723998,"image_index":0,"url":"https://…","size":"2048x2048"}
event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream-5-0-lite","created":1792723998,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}
data: [DONE]Fondo transparente
seedream-5-5 y seedream-5-0-pro aceptan background: opaque / transparent, por defecto opaque. transparent solo sirve para imagen a imagen: envíe exactamente una imagen de entrada con canal alfa, como un PNG (las Data URL JPEG y BMP devuelven 400). La salida es un PNG con transparencia, así que output_format: jpeg devuelve 400. Otros modelos devuelven 400 con background.
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-your-key" \
-F "model=seedream-5-0-pro" \
-F "prompt=Keep the product and make the background transparent" \
-F "image=@product.png" \
-F "background=transparent" \
-F "output_format=png"Descomposición en capas
seedream-5-0-pro puede dividir una imagen en una imagen base más hasta 16 capas transparentes (sujetos, texto, fondo, decoración), para editar o mover cada capa y volver a componer la imagen. Envíe "layer_decomposition": true como booleano JSON a POST /v1/images/generations, o el campo layer_decomposition=true a POST /v1/images/edits (multipart o JSON).
Al activarla cambian estas reglas:
| Parámetro | Con layer_decomposition: true |
|---|---|
model | Solo seedream-5-0-pro; otros modelos devuelven 400 |
image | Exactamente una imagen. Una Data URL debe ser PNG o JPEG |
prompt | Opcional. Si lo omite, el modelo detecta por sí mismo sujetos, texto, fondo y decoración; también puede describir qué separar, o marcar una región con <bbox>x1 y1 x2 y2</bbox> (coordenadas normalizadas de 0 a 999) |
size | Solo 1K / 1.5K / 2K / auto, por defecto auto; no acepta WIDTHxHEIGHT |
output_format | Solo afecta a la imagen base; las capas son siempre PNG con transparencia |
Con auto, una entrada de entre unos 1280x720 y 2048x2048 conserva su tamaño; una más pequeña sale a 1K y una más grande a 2K. Límites oficiales de la imagen de entrada: píxeles totales de 512x512 a 6000x6000, relación de aspecto de 1:16 a 16:1 y hasta 30 MB.
La descomposición en capas es síncrona y lenta: unos 1,5 minutos a 1K. Configure el tiempo de espera del cliente en al menos 5 minutos y no reenvíe mientras la primera solicitud siga en curso; puede terminar igualmente y cobrarse.
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-pro",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "1K"
}'data[] trae primero la imagen base y después las capas:
{
"model": "seedream-5-0-pro",
"created": 1792722728,
"data": [
{
"url": "https://…/base.jpeg?X-Signature=…",
"size": "880x1088",
"output_format": "jpeg",
"z_index": 0
},
{
"url": "https://…/layer-1.png?X-Signature=…",
"size": "959x354",
"output_format": "png",
"z_index": 1,
"bounding_box": {
"absolute": [156, 751, 784, 983],
"normalized": [177, 690, 890, 903]
},
"name": "Wooden stump stage",
"description": "A wooden stump stage at the bottom of the scene"
}
],
"usage": {
"generated_images": 2
}
}| Campo | Descripción |
|---|---|
data[].z_index | 0 es la imagen base; las capas cuentan desde 1, y los números mayores quedan encima |
data[].url | Enlace firmado, válido durante 24 horas |
data[].size | Tamaño real en píxeles de esta imagen. Una capa no suele medir lo mismo que su recuadro en la imagen base |
data[].output_format | La imagen base sigue su output_format; las capas son png |
data[].bounding_box.absolute | Solo capas: [left, top, right, bottom] en píxeles de la imagen base |
data[].bounding_box.normalized | Solo capas: el mismo recuadro, normalizado de 0 a 999 |
data[].name, data[].description | Solo capas: nombre y contenido de la capa |
usage.generated_images | Imagen base más capas: el número de imágenes cobradas |
Para recomponer, use la imagen base como lienzo y coloque las capas en orden ascendente de z_index: escale cada capa a su recuadro, (right - left) x (bottom - top), y péguela en (left, top) con su canal alfa. Por ejemplo, con Pillow:
import io
import urllib.request
from PIL import Image
def fetch(url):
return Image.open(io.BytesIO(urllib.request.urlopen(url).read())).convert("RGBA")
items = sorted(resp["data"], key=lambda d: d["z_index"]) # resp es el JSON de la respuesta ya analizado
canvas = fetch(items[0]["url"])
for item in items[1:]:
left, top, right, bottom = item["bounding_box"]["absolute"]
layer = fetch(item["url"]).resize((right - left, bottom - top))
canvas.alpha_composite(layer, (left, top))
canvas.save("recomposed.png")Notas
ndebe ser 1: cada solicitud genera una imagen, salvo la generación en grupo (sequential_image_generation: auto, Lite y 4.5) y la descomposición en capas (5.0 Pro).- Solo síncrono:
Prefer: respond-asyncse ignora y la respuesta sigue siendo síncrona. - Por defecto el resultado llega como
url; para base64 useresponse_format: b64_json(un grupo sin streaming necesita ademásstream: true). sizeno aceptaauto(salvo con la descomposición en capas), y Lite y 4.5 generan como mínimo 2K.seedream-4-5solo genera JPEG.seedream-5-5solo aceptastandardenoptimize_prompt_options.mode(fastdevuelve 400) y no admite la descomposición en capas, la generación en grupo ni el streaming.- No admite máscaras tradicionales; para editar localmente, use una referencia anotada y descríbala en el prompt.
imagesen plural,qualityy similares no tienen efecto y se ignoran.tools(búsqueda web) aún no se admite; enviarlo devuelve 400.seedream-5-0-litees el modelo ligero de Seedream 5.0, con nombre público Seedream 5.0 Lite; no lo trate como Pro.- Las Data URL deben ir en base64 y su MIME debe coincidir con la imagen.
- Especificación oficial: cada imagen de entrada puede tener hasta 30 MB / 36 MP.
Errores comunes
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 el motivo en error.message.
| Error | Solución |
|---|---|
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | Use una abreviatura del modelo o un WIDTHxHEIGHT válido |
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | Use 1K, 1.5K, 2K o un WIDTHxHEIGHT válido; 4K no se acepta |
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216 | Ajuste el ancho y el alto al rango de píxeles |
size aspect ratio must be between 1:16 and 16:1 | Ajuste la relación de aspecto |
only a single output is supported (n=1) | Quite n; para varias imágenes use sequential_image_generation |
response_format only supports url or b64_json | Use url o b64_json |
model seedream-4-5 only supports output_format jpeg | Envíe jpeg u omítalo |
model seedream-5-5 only supports optimize_prompt_options.mode standard | Envíe standard u omítalo; fast requiere seedream-5-0-pro |
at most 10 reference images are supported | Envíe menos referencias |
seedream does not accept a traditional mask; ... | Quite mask y use una referencia anotada |
model seedream-5-0-lite does not support layer_decomposition | La descomposición en capas requiere seedream-5-0-pro |
layer_decomposition requires exactly one image | Envíe exactamente una image |
layer_decomposition only accepts png or jpeg images | Convierta la imagen de entrada a PNG o JPEG |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition | Use un tramo de tamaño u omita size |
layer_decomposition must be a boolean | Pase true o false |
model seedream-5-0-lite does not support background | background requiere seedream-5-5 o seedream-5-0-pro |
background transparent requires exactly one image with an alpha channel | Envíe exactamente una imagen con transparencia, como un PNG |
background transparent outputs png; output_format jpeg is not allowed | Quite output_format o use png |
model seedream-5-0-pro does not support sequential_image_generation | La generación en grupo requiere seedream-5-0-lite o seedream-4-5 |
the number of reference images plus max_images must not exceed 15 | Reduzca max_images o envíe menos referencias |
response_format b64_json with sequential_image_generation auto requires stream=true | Añada stream: true o use url |
model seedream-5-0-pro does not support stream | El streaming requiere seedream-5-0-lite o seedream-4-5 |
model seedream-5-0-lite does not support tools | Quite tools |
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-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # p. ej. "size": "4K"
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 or b64_json
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
model seedream-5-0-lite only supports optimize_prompt_options.mode standard
model seedream-5-5 only supports optimize_prompt_options.mode standard # fast: solo seedream-5-0-pro
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
model seedream-5-0-lite does not support layer_decomposition # solo seedream-5-0-pro lo admite
layer_decomposition must be a boolean
layer_decomposition requires exactly one image # sin imagen, o dos o más
layer_decomposition only accepts png or jpeg images # Data URL en otro formato
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
model seedream-5-0-lite does not support background # solo seedream-5-5 / seedream-5-0-pro lo admiten
model seedream-5-0-pro only supports background opaque or transparent
background transparent requires exactly one image with an alpha channel
background transparent outputs png; output_format jpeg is not allowed
background transparent requires an input image with an alpha channel, image/jpeg is not supported
model seedream-5-0-pro does not support sequential_image_generation # grupo y streaming: solo seedream-5-0-lite / seedream-4-5
sequential_image_generation only supports auto or disabled
sequential_image_generation_options must be an object
sequential_image_generation_options.max_images must be an integer between 1 and 15
the number of reference images plus max_images must not exceed 15
response_format b64_json with sequential_image_generation auto requires stream=true
model seedream-5-0-pro does not support stream
watermark must be a boolean
model seedream-5-0-lite does not support tools # la búsqueda web aún no se admiteFacturación
Se cobra por imagen generada con éxito (en un grupo, las imágenes fallidas no se cobran), 5.5 y 5.0 Pro también cobran cada imagen de referencia, y las generaciones fallidas y los rechazos de seguridad no se cobran. 5.5 y 5.0 Pro tienen precio por tramo de píxeles de salida, y 1K y 1.5K cuestan lo mismo. El cargo real de cada solicitud es usage.cost_usd (USD) y usage.cost (CNY) en la respuesta. Con la descomposición en capas, cada imagen de salida (la imagen base y cada capa) se cobra según su propio tramo de píxeles a la tarifa de descomposición en capas, que es la mitad del precio normal por imagen de 5.0 Pro; la imagen de entrada se cobra como referencia, como siempre. usage.generated_images es el número de imágenes de salida cobradas. Las respuestas en streaming no llevan los campos de cargo; revise el registro de consumo.
Los precios unitarios están en las fichas de cada modelo y en el catálogo de modelos tras iniciar sesión.
Próximos pasos
- Resumen de generación de imágenes
- GPT Image, imágenes Gemini, imágenes Grok, imágenes Kling
- Referencia de API: Generar imágenes, Editar imágenes
- Si algo falla, revise Solución de problemas