Saltar al contenido

Seedream

Genere y edite imágenes con Seedream: parámetros, respuestas y advertencias.

ElementoValor
Base URLhttps://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 claveGeneració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

ModeloID del modeloAbreviaturas de tamañoPrecio oficial
Seedream 5.5seedream-5-51K / 1.5K / 2K$0,02desde/ imagen
Seedream 5.0 Proseedream-5-0-pro1K / 1.5K / 2K$0,0225desde/ imagen
Seedream 5.0 Liteseedream-5-0-lite2K / 3K / 4K$0,035/ imagen
Seedream 4.5seedream-4-52K / 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ámetroObligatorioTipo y límitesPredeterminadoDescripción
modelObligatorioCadena, vea la tabla anterior—Use el ID que devuelve GET /v1/models con su clave
promptObligatorioCadena no vacía tras recortar espacios—Contenido, composición, estilo o instrucción; opcional con layer_decomposition
sizeOpcionalAbreviatura del modelo o WIDTHxHEIGHT—auto solo con layer_decomposition; píxeles abajo
nOpcionalSolo 11Otro valor (incl. null) devuelve 400; para varias imágenes use sequential_image_generation
response_formatOpcionalSolo url / b64_jsonurlurl devuelve un enlace firmado; b64_json devuelve base64 en data[].b64_json
output_formatOpcionalSegún el modelo, abajo—Formato de la imagen
optimize_prompt_optionsOpcionalObjeto; mode según el modelo—Modo de optimización del prompt
imageOpcionalURL / Data URL, cadena o array de cadenas—Referencias; activa imagen a imagen / edición
layer_decompositionOpcionalBooleano, solo seedream-5-0-profalsetrue divide una imagen de entrada en una imagen base más capas; vea Descomposición en capas
backgroundOpcionalopaque / transparent, solo seedream-5-5 / seedream-5-0-proopaquetransparent exige exactamente una imagen de entrada con canal alfa; vea Fondo transparente
watermarkOpcionalBooleanofalsetrue añade marca de agua (el valor oficial por defecto es true)
sequential_image_generationOpcionalauto / disabled, solo seedream-5-0-lite / seedream-4-5disabledauto devuelve un grupo de imágenes; vea Generación en grupo
sequential_image_generation_optionsOpcionalObjeto; max_images es un entero de 1 a 15—Máximo del grupo; imágenes de referencia más max_images ≤ 15
streamOpcionalBooleano, solo seedream-5-0-lite / seedream-4-5falsetrue devuelve SSE; vea Streaming

Límites por modelo:

ID del modeloPíxeles totales de sizeMáx. referenciasoutput_formatoptimize_prompt_options.mode
seedream-5-5921.600–4.624.22010png / jpegstandard
seedream-5-0-pro921.600–4.624.22010png / jpegstandard / fast
seedream-5-0-lite3.686.400–16.777.21614png / jpegstandard
seedream-4-53.686.400–16.777.21614jpegstandard

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ámetroObligatorioTipo y límitesPredeterminadoDescripción
image / image[]ObligatorioArchivo o URL, repetible—Cada archivo ≤ 30 MB
model, promptObligatorioIgual que en Generar——
size, n, response_format, output_formatOpcionalIgual que en Generar——
background, watermark, stream, sequential_image_generationOpcionalIgual que en Generar—En multipart, los booleanos son las cadenas true / false
sequential_image_generation_options[max_images]OpcionalMismo max_images que en Generar—También vale max_images
optimize_prompt_options[mode]OpcionalMismo mode que en Generar—También vale optimize_prompt_mode
layer_decompositionOpcionalIgual que en Generar; en multipart, la cadena truefalseExige 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.

CampoTipoDescripción
createdintegerSegundos Unix
modelstringID del modelo solicitado
data[].urlstringEnlace firmado, válido 24 horas
data[].b64_jsonstringImagen en base64, solo con response_format: b64_json
data[].errorobjectSolo generación en grupo: esta imagen falló (code, message) y no se cobra
data[].sizestringWIDTHxHEIGHT real de la salida
usageobjectPuede aparecer, con generated_images y otros
usage.costnumberEl 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_usdnumberEl importe en USD realmente descontado de su saldo, con hasta 8 decimales, el mismo importe que el registro de consumo de esta solicitud
usage.currencystringLa 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.

Descargue enseguida los resultados.

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[].error con code y message y 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: true y reciba las imágenes una a una. Un grupo sin streaming no puede usar response_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.

Eventodata
image_generation.partial_succeededUna imagen lista: image_index, url (o b64_json), size
image_generation.partial_failedUna imagen falló: image_index, error.code, error.message; no se cobra
image_generation.completedFin: 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ámetroCon layer_decomposition: true
modelSolo seedream-5-0-pro; otros modelos devuelven 400
imageExactamente una imagen. Una Data URL debe ser PNG o JPEG
promptOpcional. 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)
sizeSolo 1K / 1.5K / 2K / auto, por defecto auto; no acepta WIDTHxHEIGHT
output_formatSolo 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.

Use un tiempo de espera largo en el cliente.

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
  }
}
CampoDescripción
data[].z_index0 es la imagen base; las capas cuentan desde 1, y los números mayores quedan encima
data[].urlEnlace firmado, válido durante 24 horas
data[].sizeTamaño real en píxeles de esta imagen. Una capa no suele medir lo mismo que su recuadro en la imagen base
data[].output_formatLa imagen base sigue su output_format; las capas son png
data[].bounding_box.absoluteSolo capas: [left, top, right, bottom] en píxeles de la imagen base
data[].bounding_box.normalizedSolo capas: el mismo recuadro, normalizado de 0 a 999
data[].name, data[].descriptionSolo capas: nombre y contenido de la capa
usage.generated_imagesImagen 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

  • n debe 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-async se ignora y la respuesta sigue siendo síncrona.
  • Por defecto el resultado llega como url; para base64 use response_format: b64_json (un grupo sin streaming necesita además stream: true).
  • size no acepta auto (salvo con la descomposición en capas), y Lite y 4.5 generan como mínimo 2K.
  • seedream-4-5 solo genera JPEG.
  • seedream-5-5 solo acepta standard en optimize_prompt_options.mode (fast devuelve 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.

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.

ErrorSolución
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel sizeUse 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 sizeUse 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 16777216Ajuste el ancho y el alto al rango de píxeles
size aspect ratio must be between 1:16 and 16:1Ajuste 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_jsonUse url o b64_json
model seedream-4-5 only supports output_format jpegEnvíe jpeg u omítalo
model seedream-5-5 only supports optimize_prompt_options.mode standardEnvíe standard u omítalo; fast requiere seedream-5-0-pro
at most 10 reference images are supportedEnví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_decompositionLa descomposición en capas requiere seedream-5-0-pro
layer_decomposition requires exactly one imageEnvíe exactamente una image
layer_decomposition only accepts png or jpeg imagesConvierta la imagen de entrada a PNG o JPEG
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decompositionUse un tramo de tamaño u omita size
layer_decomposition must be a booleanPase true o false
model seedream-5-0-lite does not support backgroundbackground requiere seedream-5-5 o seedream-5-0-pro
background transparent requires exactly one image with an alpha channelEnvíe exactamente una imagen con transparencia, como un PNG
background transparent outputs png; output_format jpeg is not allowedQuite output_format o use png
model seedream-5-0-pro does not support sequential_image_generationLa generación en grupo requiere seedream-5-0-lite o seedream-4-5
the number of reference images plus max_images must not exceed 15Reduzca max_images o envíe menos referencias
response_format b64_json with sequential_image_generation auto requires stream=trueAñada stream: true o use url
model seedream-5-0-pro does not support streamEl streaming requiere seedream-5-0-lite o seedream-4-5
model seedream-5-0-lite does not support toolsQuite tools

Facturació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