Seedream 4.5: um guia completo com Python

A BytePlus acaba de lançar seu mais novo modelo de geração de imagens, o Seedream 4.5. Como braço de tecnologia empresarial da ByteDance, a empresa leva recursos avançados de IA para negócios no mundo todo, aproveitando a inovação por trás de plataformas como o TikTok.

Neste artigo, vou te mostrar como usar o Seedream 4.5 com Python, integrando-o via API para gerar imagens de forma programática. 

Recomendo fazer o curso Generative AI Concepts como uma ótima introdução à tecnologia por trás de modelos de geração de imagens como o Seedream. Se você também se interessa por outros modelos de imagem, confira nosso guia sobre o Nano Banana 2 do Google.

O que é o Seedream 4.5

Seedream 4.5 é a versão mais recente do modelo de geração de imagens por IA da BytePlus.

Este lançamento aprimora a consistência do sujeito, melhora a nitidez de textos pequenos e aperfeiçoa a mesclagem de múltiplas imagens. Ele também entende melhor instruções, tem raciocínio espacial mais forte e inferência lógica mais avançada.

O modelo também consegue produzir imagens 4K de alta qualidade, um avanço bem-vindo, já que modelos concorrentes costumam ter dificuldade para gerar imagens em alta resolução. Em termos de custo, ele também é competitivo, com gerações a apenas 4 centavos por imagem.

Aproveite para conferir também nosso artigo sobre o novo modelo de geração de vídeo da ByteDance, o Seedance 2.0.

Configuração da API do Seedream 4.5

Sem enrolação, vamos começar com a API do Seedream 4.5.

Criando uma chave de API

Para usar o Seedream 4.5 com Python via API, primeiro precisamos criar uma chave de API.

1. Acesse o site oficial, clique no botão Get API no canto inferior direito e faça login.

2. Depois de logado, há um botão Access API no canto superior direito. Clique e crie a chave de API. Para criar a chave, é necessário verificar o número de celular e informar os dados de cobrança. Não é uma assinatura, então você não será cobrado mensalmente. Apenas as chamadas feitas à API são cobradas.

3. Crie um arquivo chamado .env na mesma pasta onde vamos escrever o código em Python e cole a chave nele no seguinte formato:

ARK_API_KEY=<paste_key_here>

Antes de usar o modelo, certifique-se de também ativá-lo no console BytePlus ModelArk. Isso é feito separadamente da chave de API. Para ativar:

1. Navegue até Model activation na barra lateral esquerda.

2. No centro da tela, escolha Media como a categoria de modelo.

3. Clique em Activate à direita, na linha do modelo ByteDance-Seedream-4.5.

4. Confirme na janela que abrir.

Instalação das dependências em Python

Para interagir com a API do Seedream 4.5, vamos instalar alguns pacotes Python:

• byteplussdkarkruntime: pacote oficial em Python que permite fazer requisições à API do Seedream 4.5, parte do SDK da BytePlus.

• Alguns pacotes auxiliares para carregar a chave de API do arquivo .env, para requisições HTTP assíncronas e validação de configurações.

Instale os pacotes com o comando:

pip install byteplus-python-sdk-v2 python-dotenv httpx requests typing_extensions pydantic

Gerando imagens com o Seedream 4.5

Vamos começar aprendendo a gerar uma imagem a partir de um prompt de texto. Se você já leu nossos outros tutoriais de APIs de IA em Python, como os do GPT-Image-1 ou do Grok Imagine, provavelmente já está familiarizado com o fluxo típico:

1. Importar os pacotes.

2. Carregar a chave de API do arquivo .env.

3. Criar um cliente usando o pacote oficial da API.

4. Enviar a requisição para a API.

O Seedream 4.5 funciona exatamente assim. Veja um script de exemplo para gerar uma imagem:

# 1. Import the necessary packages
from dotenv import load_dotenv
from byteplussdkarkruntime import Ark 
import os
# 2. Load the API key
load_dotenv()
# 3. Create the client
client = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    api_key=os.getenv("ARK_API_KEY"), 
)
# 4. Send the API request
prompt = """
Photorealistic anthropomorphic animals hanging out in a coffee shop with no humans.
"""
 
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128",
    prompt=prompt,
    watermark=False,
)
 
image_url = imagesResponse.data[0].url
print(image_url)

Neste exemplo específico, o prompt usado foi:

Photorealistic anthropomorphic animals hanging out in a coffee shop with no humans.

Este foi o resultado gerado pelo modelo:

Baixando a imagem gerada

O script acima mostra a URL da imagem gerada no terminal. Não é o fluxo mais prático. Uma alternativa melhor é criar uma função que baixe a imagem gerada para a pasta local.

import requests
from urllib.parse import urlparse
import os
def download_image(url):
    try:
        response = requests.get(url, stream=True)
        response.raise_for_status()
        parsed_url = urlparse(url)
        filename = os.path.basename(parsed_url.path)
        if not filename:
            filename = "downloaded_image"
        with open(filename, "wb") as f:
            for chunk in response.iter_content(1024):
                f.write(chunk)
        print(f"Image saved to: {filename}")
    except Exception as e:
        print(f"Error downloading image: {e}")

Recomendo criar um novo script chamado utils.py e colocar essa função lá. Depois, no script que gera a imagem, adicionamos o código a seguir para fazer o download:

import utils
utils.download_image(image_url)

Especificando o tamanho da imagem

Os exemplos anteriores usaram os parâmetros padrão do Seedream 4.5, com exceção de watermark, que definimos como False para ocultá-la.

O Seedream 4.5 oferece duas formas de especificar as dimensões da imagem de saída usando o parâmetro size.

A primeira é especificar a resolução da imagem gerada definindo size como "2K" ou "4K" e descrever a proporção, formato ou finalidade no prompt em linguagem natural, deixando o modelo determinar largura e altura. O valor padrão é "2K".

Exemplo:

prompt = """
Portait Instagram image to be used to promote travel to Tokyo, Japan.
"""
 
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128",
    prompt=prompt,
    size="4K",
    watermark=False,
)

Como alternativa, podemos especificar o tamanho da imagem em pixels com uma string como "3750x1250", mas existem duas regras a seguir:

1. Total de pixels (largura × altura) deve ficar entre 3,6 milhões e 16,7 milhões.
2. Proporção (largura ÷ altura) deve ficar entre 1/16 e 16.

Se apenas uma das regras for atendida, o tamanho não é válido. Para evitar ter que fazer essas contas, recomendo usar o método por resolução acima ou um dos seguintes tamanhos válidos:

Geração em lote

O Seedream 4.5 inclui um modo de geração em lote que pode ser usado para criar um conjunto de imagens tematicamente relacionadas. Isso é útil, por exemplo, para gerar um storyboard ou visuais em torno de um mesmo assunto.

Para gerar um lote de imagens, precisamos fornecer os parâmetros sequential_image_generation e sequential_image_generation_options na requisição. Veja um exemplo para gerar 4 imagens:

from byteplussdkarkruntime.types.images.images import SequentialImageGenerationOptions
prompt = """
Generate a series of four visually coherent and stylistically consistent images illustrating these stages of a human life: Child, Adolescent, Adult, and Elderly. Make sure it's the same person in the four images.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=4),
    response_format="url",
    watermark=False
)

Ao usar a geração em lote, o formato da resposta muda para conter todas as imagens. Podemos iterar por elas e baixá-las assim:

# Iterate through all image data
for image in imagesResponse.data:
    utils.download_image(image.url)

Testei com o seguinte prompt:

Generate a series of four visually coherent and stylistically consistent images illustrating these stages of a human life: Child, Adolescent, Adult, and Elderly. Make sure it's the same person in the four images.

Porém, por algum motivo, a quarta imagem sempre perdia a consistência e saía como uma mulher (tentei várias vezes).

Para gerar um número diferente de imagens, basta mudar o valor de max_images na requisição. Esse número pode ser qualquer inteiro entre 1 e 15 (inclusive). Por exemplo, para gerar 6 imagens, faríamos:

imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=6),
    response_format="url",
    watermark=False
)

Geração de texto

Vamos testar a capacidade do Seedream 4.5 de gerar texto. Nos testes, quis ver se ele conseguiria criar uma imagem com uma prova matemática sem especificar explicitamente o texto a ser renderizado. Isso também avalia a habilidade do modelo de entender contexto.

Este foi o prompt que usei:

Generate an image of a math professor standing in front of a blackboard. On the blackboard, there is a written proof that the square root of 2 is irrational.

E aqui está o resultado:

Fiquei bastante satisfeito com o resultado. Além de a prova estar correta, o modelo conseguiu lidar bem com uma grande quantidade de texto.

Editando imagens com o Seedream 4.5

Nesta seção, vamos aprender a editar imagens. A forma mais simples é fornecer a URL da imagem usando o parâmetro image e descrever as mudanças no prompt.

Aqui vai um exemplo completo de script:

from dotenv import load_dotenv
from byteplussdkarkruntime import Ark 
import os
import utils
load_dotenv()
client = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    api_key=os.getenv('ARK_API_KEY'), 
)
image = "https://images.pexels.com/photos/34408249/pexels-photo-34408249.jpeg"
prompt = """
Make in snowy.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=image,
    response_format="url",
    watermark=False,
    size="1664x2496"
) 
 
image_url = imagesResponse.data[0].url
utils.download_image(image_url)

Neste exemplo, usei uma foto pública no Pexels de Michael Fischer e usei o Seedream 4.5 para deixá-la com neve.

Este foi o resultado:

Note que, no exemplo acima, informamos explicitamente o tamanho de saída, "1664x2496", para manter a mesma proporção da imagem de entrada. Diferente de muitos modelos de imagem por IA, o Seedream 4.5 não gera automaticamente uma imagem com as mesmas dimensões da entrada. Quando omiti o parâmetro de size, a saída veio quadrada.

Editando imagens locais

Fornecer uma URL é a forma mais fácil de mandar uma imagem para o Seedream 4.5. Mas isso é incômodo quando a imagem não está hospedada em lugar nenhum.

A API do Seedream também permite usar uma imagem local com facilidade. Para isso, precisamos carregá-la como base64. Veja uma função para isso:

import mimetypes
import base64
def load_image_as_base64(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
if mime_type is None or not mime_type.startswith("image/"):
        raise ValueError("File is not a recognized image type")
with open(file_path, "rb") as f:
        encoded = base64.b64encode(f.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded}"

Recomendo adicionar essa função ao arquivo utils.py, que já contém a função de download, para facilitar o uso no script principal.

Suponha que temos uma imagem local na mesma pasta chamada motard.jpeg. Veja como carregar e editar essa imagem:

image = utils.load_image_as_base64("motard.jpeg")
prompt = """
Remove the sunglasses and add a helmet.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=image,
    response_format="url",
    watermark=False
) 

Edição com múltiplas imagens de entrada

O Seedream 4.5 suporta múltiplas imagens de entrada. Elas podem ser usadas para gerar uma nova imagem mesclando estilos e elementos visuais dessas imagens.

Fornecer várias imagens em uma requisição é tão simples quanto enviar uma lista com as imagens. Veja um exemplo que combina a imagem de uma pessoa e uma roupa para gerar essa pessoa vestindo a roupa:

image1 = utils.load_image_as_base64("woman.jpeg")
image2 = utils.load_image_as_base64("outfit.jpeg")
prompt = """
Make the woman from image 1 wear the outfit in image 2.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=[image1, image2],
    response_format="url",
    watermark=False,
)

Este exemplo mostra que o Seedream 4.5 preserva muito bem rostos; a pessoa na imagem final continua muito semelhante à original. Muitos outros modelos costumam ir pior nesse ponto.

Edição com múltiplas imagens de saída

A funcionalidade de lote que vimos acima também funciona para edição, em que o total de imagens (entradas + saídas) não pode exceder 15. Isso é muito útil, por exemplo, para gerar várias imagens baseadas em um mesmo visual.

Para isso, basta combinar o parâmetro de imagem com os parâmetros de geração em lote que aprendemos acima. Exemplo de requisição:

prompt = """
Use the given logo to create a visual design system for an outdoor hiking brand, 
including backpack, hat, and shoes.
"""
image = utils.load_image_as_base64("logo.jpeg")
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    image=image,
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=3),
    response_format="url",
    watermark=False
) 

Mascaramento

Alguns modelos de geração de imagens por IA suportam mascaramento permitindo que o usuário envie uma máscara em preto e branco para indicar as áreas a serem editadas. No entanto, o Seedream 4.5 não possui suporte nativo a parâmetros de máscara.

Mesmo assim, fiz um teste enviando a máscara como imagem de entrada e especificando no prompt o que eu queria, para ver se ele conseguiria entender e emular o resultado:

Funcionou neste exemplo, mas, por não ser um recurso nativo do modelo, não é muito confiável. Por exemplo, quando tentei o mesmo para adicionar um cachorro, não deu certo.

Boas práticas no Seedream 4.5

Como vimos, o Seedream 4.5 oferece bom desempenho e alguns recursos bem legais. Para tirar o máximo proveito, fique de olho nas boas práticas abaixo.

Diretrizes centrais de prompting

Para obter os melhores resultados de geração de imagens no Seedream 4.5, responda o que você quer, por que você quer, e como deve ser o estilo — mantendo o prompt curto:

• Descreva sujeito, ação e ambiente em linguagem simples.
• Especifique a finalidade/uso (logo, pôster, storyboard, UI etc.).
• Controle o estilo usando palavras-chave precisas ou uma imagem de referência.
• Prefira prompts concisos e precisos a listas longas de adjetivos.
• Coloque entre aspas duplas todo texto que deve aparecer na imagem.

Diretrizes para edição de imagem

Ao editar imagens, diga exatamente quais mudanças serão feitas e o que deve permanecer inalterado. Use estas quatro palavras para especificar ações:

• Adicionar
• Remover
• Substituir
• Modificar

Se a cena for complexa, usar pistas visuais (setas, caixas, rabiscos) para marcar regiões pode ajudar o modelo.

Quando usar imagem de referência para preservar identidade, estilo ou características de produto, sempre especifique:

• Alvo de referência: o que extrair/manter (ex.: design do personagem, material, estilo).
• Cena gerada: onde/como usar (layout, cenário, realismo, tamanho, posição).

Diretrizes para geração em lote

Ao usar várias imagens de entrada, deixe claro os papéis: 

• Qual fornece o sujeito, qual fornece o figurino/estilo/fundo?
• Refira-se a elas como imagem 1, imagem 2, etc.

Apesar de o modelo ter parâmetros para especificar quantas imagens gerar, é melhor reforçar no prompt o que você quer:

• Peça “uma série”, “um conjunto” ou especifique o número exato de imagens.
• Use para storyboards, quadrinhos, conjuntos de marca consistentes, pacotes de emojis etc.

Conclusão

O Seedream 4.5 se mostra um gerador de imagens maduro e pronto para produção, no mesmo nível de modelos de ponta como o Nano Banana, oferecendo fidelidade comparável, boa aderência a instruções e coerência entre imagens, mantendo um ótimo custo-benefício.

O que mais me chamou a atenção foi como a API é acessível na prática: o mesmo endpoint de geração cobre criação simples, edições (via URL ou base64), mesclas multi-imagem e lotes sequenciais — e ativamos cada modo ajustando um pequeno conjunto de parâmetros com nomes claros.

Dito isso, não sinto que traga inovações particularmente novas: é uma execução excelente de uma caixa de ferramentas de geração de imagens já familiar, mais do que um salto conceitual.

Para continuar aprendendo

Se quiser manter o embalo depois deste passo a passo, vale reforçar os fundamentos que deixam projetos com o Seedream 4.5 mais fluídos em produção.

Comece pelo curso Introduction to APIs in Python para dominar autenticação e tratamento de erros, e combine com Image Processing in Python para lidar com redimensionamento, composição e conversões de formato no seu pipeline.

Se você busca um caminho mais formal em ML aplicado e ferramentas, a trilha de carreira AI Engineer conecta tudo com fluxos para colocar no ar recursos de IA confiáveis e escaláveis.