Tutorial de la API de Seedream 5.5: código Python, precios y resultados reales

Para llamar a la API de Seedream 5.5, envía un POST a https://api.seedrouter.ai/v1/images/generations con "model": "seedream-5-5" y un prompt, conserva el id de tarea devuelto y sondea GET /v1/tasks/{id} hasta que el estado sea completed. La tarea terminada contiene las URL de las imágenes. La misma solicitud también edita con hasta 10 imágenes de referencia, crea PNG de fondo transparente y separa una imagen en capas transparentes.

ByteDance lanzó Seedream 5.5 el 9 de noviembre de 2026 con tres novedades principales: edición más estable a lo largo de muchas rondas, salida transparente nativa e imágenes más realistas con texto pequeño más nítido.^[1] Lo probamos tres veces en SeedRouter al día siguiente. Este tutorial se basa en esas pruebas: el código que enviamos, lo que devolvió, cuánto tardó y cuánto costó. Todos los campos están en la referencia de la API de Seedream 5.5, y el Playground está en la página del modelo.

¿Qué necesitas antes de la primera llamada a la API de Seedream 5.5?

Dos cosas: una clave de API y el ID de modelo. No hay nada que descargar. ByteDance no ha publicado los pesos de Seedream 5.5, así que el modelo funciona como una API alojada y tu código solo envía JSON.

Crea una clave en claves de API y guárdala en una variable de entorno en tu servidor, nunca en código del navegador:

export SEEDROUTER_API_KEY="your-key"
pip install requests

El ID de modelo es seedream-5-5. Un solo ID sirve para texto a imagen, edición y descomposición en capas; los campos de la solicitud deciden qué se ejecuta. Una cuenta nueva empieza con un pequeño saldo gratuito, suficiente para unas pocas imágenes de prueba en 1K antes de recargar.

¿Cómo se genera una imagen con Python?

El envío responde al instante con una tarea, no con la imagen. Este script envía un prompt, sondea cada 10 segundos, deja de esperar a los 15 minutos y guarda cada imagen que recibe.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

Esa es nuestra primera prueba. Terminó en 47 segundos y devolvió un PNG de 1248 × 832.

Dos hábitos de este bucle son importantes en producción. Si el sondeo agota el tiempo de espera, conserva el ID de tarea y vuelve a consultarlo; la imagen podría seguir en camino. No envíes la solicitud una segunda vez para «reintentar», porque eso crea una segunda tarea y un segundo cargo.

¿Qué campos de la solicitud importan?

La mayoría de las solicitudes solo necesitan model, prompt y size. Los campos que configurarás con más frecuencia, con sus valores predeterminados:

La salida más grande es 2K. Nuestra edición 16:9 en 2K devolvió 2560 × 1440, y los tamaños exactos pueden llegar a 4.624.220 píxeles en total. No hay campo de relación de aspecto: para una forma fija, envía píxeles exactos. No hay nivel 3K ni 4K, así que, si necesitas un archivo más grande, tendrás que ampliarlo después. La referencia de la API enumera todos los campos. Los campos que no aparecen en ella se descartan en lugar de rechazarse, así que un seed, style o n de otra API de imágenes no romperá la solicitud ni tendrá efecto alguno. Una solicitud crea una imagen.

¿Cómo se edita una imagen con imágenes de referencia?

Pon la imagen de origen en image e indica en el prompt qué cambiar y qué conservar. Nuestra segunda prueba convirtió una foto soleada de un pintor en el balcón de un faro en una noche de invierno:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

Tardó 40 segundos y devolvió un PNG de 2560 × 1440. El pintor, su pose, la brocha, la cuerda enrollada, los dos botes de pintura y la barandilla se mantuvieron en su sitio. Se añadieron nieve cayendo, nieve sobre la plataforma y sus hombros, un cielo oscuro y ventanas iluminadas por encima de la franja roja.

Con varias referencias, haz referencia a ellas por su orden en la lista («la chaqueta de la imagen 2»). Se cobra cada imagen de referencia, incluida la primera, así que envía solo las imágenes que la edición necesita.

La afirmación principal de ByteDance sobre esta versión es que las zonas sin editar se mantienen idénticas píxel a píxel entre ediciones, probado durante 100 rondas consecutivas.^[1] En la API, una edición de varias rondas es un bucle: toma la URL de una tarea terminada y pásala como image en la siguiente solicitud. Aún no hemos ejecutado una cadena larga nosotros mismos, así que no podemos confirmar la cifra de 100 rondas. Ten en cuenta que cada ronda es una tarea nueva y cobra su imagen de referencia.

¿Cómo se obtiene un PNG transparente?

Pon background en transparent y mantén output_format en png. Funciona a partir de un prompt solo o con referencias:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent con jpeg se rechaza antes de crear una tarea, porque JPEG no tiene canal alfa. ByteDance lo describe como salida RGBA nativa con transparencia total y parcial y bordes cuidadosamente renderizados, por lo que no hace falta eliminar el fondo por separado.^[1]

¿Cómo se separa una imagen en capas con la API?

Envía exactamente una imagen con layer_decomposition: true. Nuestra tercera prueba separó un póster de jazz con el reconocimiento de texto activado y un máximo de cuatro imágenes devueltas:

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

Tardó 39 segundos y devolvió cuatro imágenes: la imagen base y tres capas transparentes.

Las dos capas de texto llegaron con las palabras extraídas. El text_recognition de la capa del titular contenía "BLUE TIDE\nSESSIONS", con la fuente estimada como HTF Didot en #122C4D, y la capa de la línea inferior contenía "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM". Cada línea tiene su propia caja delimitadora y estilo, así que puedes volver a escribir el texto con tu propia fuente en el mismo lugar.

Tres cosas que debes saber antes de confiar en el resultado:

• Los archivos de las capas son más grandes que sus cajas. La escala es distinta para cada capa: 1,74× para el titular, 1,08× para la ilustración y 2,59× para la línea inferior. Ajusta cada PNG a su bounding_box.absolute antes de colocarlo y después apila las capas en orden ascendente de z_index.
• max_images es un límite máximo, y un límite bajo agrupa partes. Con cuatro espacios, el modelo puso al saxofonista, las olas y el sol coral en una sola capa. Deja espacio para el número de elementos que esperas.
• Un elemento puede aparecer dos veces. El sol coral estaba en la capa de ilustración y también permaneció en la imagen base. Revisa la imagen base antes de mover una capa.

¿Cuánto cuesta la API de Seedream 5.5?

Pagas por imagen, según el tamaño de cada una, más cada imagen de referencia. Las imágenes de hasta 2,61 millones de píxeles (1K y 1.5K) pertenecen al nivel inferior; 2K y cualquier tamaño mayor, al nivel superior. Una descomposición en capas cobra la imagen base y cada capa según su propio tamaño. Las tareas fallidas no se cobran.

Nuestras tres pruebas del 10 de noviembre de 2026 y qué se cobró en cada una:

Multiplica esas unidades por los precios de la tabla de arriba para obtener el importe. Ojo con la descomposición: costó cuatro imágenes, no una, porque se cobra la imagen base y cada capa.

Una descomposición en capas reserva más saldo del que cobra mientras se ejecuta. Al aceptar la tarea, se reserva el saldo necesario para max_images imágenes, 30 si lo omites, con auto contado como nivel superior. Al terminar, se cobran las imágenes devueltas y se libera el resto. Por tanto, una descomposición sin max_images ni size necesita saldo suficiente para 30 imágenes de nivel superior más la imagen de entrada para empezar, aunque devuelva cuatro imágenes. Fija max_images cerca del número de partes que esperas y elige un nivel, como en nuestra tercera prueba (cuatro solicitadas, cuatro devueltas), y la reserva se mantiene cerca del cargo.

¿Qué errores debes prever?

Las referencias deben ser URL públicas HTTP(S). Las URI de datos Base64 se rechazan, así que sube primero el archivo a tu propio almacenamiento. Se aceptan JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC y HEIF, hasta 30 MB cada uno. La lista completa de códigos está en el catálogo de errores.

Preguntas frecuentes

¿Existe Seedream 5.5 Pro?

Todavía no. La publicación de lanzamiento de ByteDance dice "A Pro version of the Seedream 5.5 series will follow" (Habrá una versión Pro de la serie) y no da fecha.^[1] Hoy la API tiene un modelo, seedream-5-5. El modelo Pro de la generación anterior sigue disponible como Seedream 5.0 Pro.

¿La API de Seedream 5.5 es gratis?

No. Se paga por imagen desde un saldo prepago, sin suscripción. El pequeño saldo gratuito de una cuenta nueva cubre unas pocas imágenes en 1K, así que puedes ejecutar el script de arriba antes de recargar.

¿Puedo descargar Seedream 5.5?

No. ByteDance no ha publicado los pesos del modelo, así que no hay ningún archivo para ejecutarlo en local. Se usa mediante una API como esta.

¿Cuántas imágenes de referencia puedo enviar?

Hasta 10 en image. Una descomposición en capas acepta exactamente una.

¿Cuánto tarda una solicitud?

Nuestras tres pruebas tardaron entre 39 y 47 segundos. Las descomposiciones que devuelven muchas capas pueden tardar varios minutos; por eso el script de arriba sondea durante un máximo de 15 minutos.

Referencias

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. 9 de noviembre de 2026. Consultado el 11 de noviembre de 2026 en seed.bytedance.com.
2. SeedRouter. Referencia de la API de Seedream 5.5. /docs/seedream-5-5.