Tutorial da API de Seedream 5.5: código Python, preços e resultados reais

Para chamar a API de Seedream 5.5, faça um POST para https://api.seedrouter.ai/v1/images/generations com "model": "seedream-5-5" e um prompt, guarde o id da tarefa retornado e consulte GET /v1/tasks/{id} até o status ser completed. A tarefa concluída traz as URLs das imagens. A mesma requisição também edita com até 10 imagens de referência, cria PNGs com fundo transparente e separa uma imagem em camadas transparentes.

A ByteDance lançou Seedream 5.5 em 9 de novembro de 2026 com três mudanças principais: edição mais estável ao longo de muitas rodadas, saída transparente nativa e imagens mais realistas com texto pequeno mais nítido.^[1] Fizemos três testes no SeedRouter no dia seguinte. Este tutorial usa esses testes: o código que enviamos, o que retornou, quanto tempo levou e quanto custou. Todos os campos estão na referência da API de Seedream 5.5, e o Playground fica na página do modelo.

Do que você precisa antes da primeira chamada à API de Seedream 5.5?

Duas coisas: uma chave de API e o ID do modelo. Não há nada para baixar. A ByteDance não publicou os pesos de Seedream 5.5, então o modelo funciona como uma API hospedada e seu código só envia JSON.

Crie uma chave em chaves de API e guarde-a em uma variável de ambiente no seu servidor, nunca em código do navegador:

export SEEDROUTER_API_KEY="your-key"
pip install requests

O ID do modelo é seedream-5-5. Um único ID cobre texto para imagem, edição e decomposição em camadas; os campos da requisição decidem o que será executado. Uma conta nova começa com um pequeno saldo grátis, suficiente para algumas imagens de teste em 1K antes de você recarregar.

Como gerar uma imagem com Python?

O envio retorna na hora com uma tarefa, não com a imagem. Este script envia um prompt, consulta a cada 10 segundos, para de esperar após 15 minutos e salva cada imagem retornada.

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"])

Esse é o nosso primeiro teste. Terminou em 47 segundos e retornou um PNG de 1248 × 832.

Dois hábitos desse loop importam em produção. Se a consulta atingir o tempo limite, guarde o ID da tarefa e consulte de novo; a imagem ainda pode estar a caminho. Não envie a requisição uma segunda vez para “tentar de novo”, porque isso cria uma segunda tarefa e uma segunda cobrança.

Quais campos da requisição importam?

A maioria das requisições precisa apenas de model, prompt e size. Os campos que você vai definir com mais frequência, com seus valores padrão:

A maior saída é 2K. Nossa edição 16:9 em 2K retornou 2560 × 1440, e as dimensões exatas podem chegar a 4.624.220 pixels no total. Não há campo de proporção: para um formato fixo, envie dimensões exatas em pixels. Não há faixa 3K ou 4K, então, se precisar de um arquivo maior, você terá que ampliá-lo depois. A referência da API lista todos os campos. Campos que não estão listados nela são descartados em vez de rejeitados, então um seed, style ou n de outra API de imagens não quebra a requisição nem tem efeito algum. Uma requisição gera uma imagem.

Como editar uma imagem com imagens de referência?

Coloque a imagem de origem em image e diga no prompt o que mudar e o que manter. Nosso segundo teste transformou uma foto ensolarada de um pintor na varanda de um farol em uma noite de inverno:

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",
})

Levou 40 segundos e retornou um PNG de 2560 × 1440. O pintor, sua pose, o pincel, a corda enrolada, as duas latas de tinta e o guarda-corpo ficaram no lugar. Foram adicionados neve caindo, neve no piso da varanda e nos ombros dele, um céu escuro e janelas iluminadas acima da faixa vermelha.

Com várias referências, faça referência a elas pela ordem na lista (“a jaqueta da imagem 2”). Cada imagem de referência é cobrada, inclusive a primeira, então envie apenas as imagens necessárias para a edição.

A principal afirmação da ByteDance sobre esta versão é que as áreas não editadas permanecem idênticas pixel a pixel entre as edições, testadas em 100 rodadas consecutivas.^[1] Pela API, uma edição de várias rodadas é um loop: pegue a URL de uma tarefa concluída e passe como image na próxima requisição. Ainda não executamos uma sequência longa por conta própria, então não podemos confirmar o número de 100 rodadas. Lembre que cada rodada é uma tarefa nova e cobra sua imagem de referência.

Como obter um PNG transparente?

Defina background como transparent e mantenha output_format como png. Funciona a partir de um prompt sozinho ou com referências:

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

transparent com jpeg é rejeitado antes de criar uma tarefa, porque JPEG não tem canal alfa. A ByteDance descreve isso como saída RGBA nativa com transparência total e parcial e bordas renderizadas com cuidado, então o material não precisa de remoção de fundo separada.^[1]

Como separar uma imagem em camadas com a API?

Envie exatamente uma imagem com layer_decomposition: true. Nosso terceiro teste separou um pôster de jazz com reconhecimento de texto ativado e retorno de no máximo quatro imagens:

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},
})

Levou 39 segundos e retornou quatro imagens: a imagem de base e três camadas transparentes.

As duas camadas de texto retornaram com as palavras extraídas. O text_recognition da camada do título continha "BLUE TIDE\nSESSIONS", com a fonte estimada como HTF Didot em #122C4D, e a camada da linha inferior continha "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM". Cada linha tem sua própria caixa delimitadora e estilo, então você pode digitar o texto de novo com sua própria fonte no mesmo lugar.

Três coisas para saber antes de confiar no resultado:

• Os arquivos das camadas são maiores que suas caixas. A escala é diferente para cada camada: 1,74× para o título, 1,08× para a ilustração e 2,59× para a linha inferior. Redimensione cada PNG para sua bounding_box.absolute antes de posicioná-lo e depois empilhe as camadas em ordem crescente de z_index.
• max_images é um limite máximo, e um limite baixo junta partes. Com quatro espaços, o modelo colocou o saxofonista, as ondas e o sol coral em uma única camada. Deixe espaço para a quantidade de elementos que você espera.
• Um elemento pode aparecer duas vezes. O sol coral estava na camada de ilustração e também ficou na imagem de base. Confira a imagem de base antes de mover uma camada.

Quanto custa a API de Seedream 5.5?

Você paga por imagem, pelo tamanho de cada uma, mais cada imagem de referência. Imagens de até 2,61 milhões de pixels (1K e 1.5K) ficam na faixa inferior; 2K e qualquer tamanho maior ficam na faixa superior. Uma decomposição em camadas cobra a imagem de base e cada camada pelo próprio tamanho. Tarefas que falham não são cobradas.

Nossos três testes de 10 de novembro de 2026 e o que foi cobrado em cada um:

Multiplique essas unidades pelos preços da tabela acima para obter a cobrança. Fique de olho na decomposição: custou quatro imagens, não uma, porque a imagem de base e cada camada são cobradas.

Uma decomposição em camadas reserva mais saldo do que cobra enquanto é executada. Quando a tarefa é aceita, o saldo necessário para max_images imagens é reservado, 30 quando você omite o campo, com auto contado como faixa superior. Quando a tarefa termina, você é cobrado pelas imagens retornadas e o restante é liberado. Uma decomposição sem max_images e sem size, portanto, precisa de saldo suficiente para 30 imagens da faixa superior mais a imagem de entrada para começar, mesmo que retorne quatro imagens. Defina max_images próximo do número de partes que você espera e escolha uma faixa, como no nosso terceiro teste (quatro solicitadas, quatro retornadas), e a reserva fica próxima da cobrança.

Quais erros você deve prever?

As referências precisam ser URLs HTTP(S) públicas. URIs de dados Base64 são rejeitadas, então envie o arquivo para seu próprio armazenamento primeiro. JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC e HEIF são aceitos, até 30 MB cada. A lista completa de códigos está no catálogo de erros.

Perguntas frequentes

Existe Seedream 5.5 Pro?

Ainda não. A publicação de lançamento da ByteDance diz "A Pro version of the Seedream 5.5 series will follow" (Haverá uma versão Pro da série) e não informa uma data.^[1] Hoje a API tem um modelo, seedream-5-5. O modelo Pro da geração anterior continua disponível como Seedream 5.0 Pro.

A API de Seedream 5.5 é grátis?

Não. O pagamento é por imagem a partir de um saldo pré-pago, sem assinatura. O pequeno saldo grátis de uma conta nova cobre algumas imagens em 1K, então você pode executar o script acima antes de recarregar.

Posso baixar Seedream 5.5?

Não. A ByteDance não publicou os pesos do modelo, então não há arquivo para executar localmente. Você o usa por uma API como esta.

Quantas imagens de referência posso enviar?

Até 10 em image. Uma decomposição em camadas aceita exatamente uma.

Quanto tempo uma requisição demora?

Nossos três testes levaram de 39 a 47 segundos. Decomposições que retornam muitas camadas podem levar vários minutos, por isso o script acima consulta por até 15 minutos.

Referências

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. 9 de novembro de 2026. Consultado em 11 de novembro de 2026 em seed.bytedance.com.
2. SeedRouter. Referência da API de Seedream 5.5. /docs/seedream-5-5.