Como usar a API de imagens do Seedream 5.0 Pro

Você consegue colocar o Seedream 5.0 Pro para funcionar com uma requisição POST, uma chave de API e um passo de acompanhamento: envie o job, obtenha um task_id e depois verifique o status até a imagem ficar pronta. Se você pular esse segundo passo, não vai receber o arquivo final.

Aqui vai a versão curta:

• Eu envio requisições para https://api.apimart.ai/v1/images/generations
• Eu adiciono Authorization: Bearer YOUR_API_KEY
• Eu defino model como doubao-seedream-5-0-pro
• Eu incluo prompt, size e n
• Eu uso texto para imagem para novas ideias de imagem
• Eu uso imagem para imagem quando quero que a saída fique mais próxima de uma ou mais imagens de referência
• Eu armazeno as URLs das imagens rápido, porque elas expiram após 24 horas
• Eu uso jobs assíncronos para saídas lentas como imagens em 3K, que podem levar cerca de 35 a 50 segundos
• Eu fico de olho no custo, já que o preço é de cerca de $0.0320 por imagem

A principal coisa que eu lembraria: mantenha a chave no servidor, passe n como um número e use polling ou um webhook para jobs mais longos.

Alguns detalhes importam mais do que parecem. Por exemplo, 401 muitas vezes significa que a chave está faltando ou que o formato Bearer está errado. 403 muitas vezes significa que a chave funciona, mas a conta não pode usar o modelo ou tem saldo baixo. E se eu uso saída em Base64, preciso adicionar o prefixo data:image/...;base64, eu mesmo antes de exibir no navegador.

Comparação rápida

Em resumo: este guia mostra como eu configuraria a autenticação, montaria o corpo da requisição, escolheria entre T2I e I2I, lidaria com jobs assíncronos e salvaria o resultado sem perder arquivos ou desperdiçar gasto.

2. Configurar acesso e autenticação da API

2.1 Crie sua conta na APIMart e gere uma chave de API

Vá ao site da APIMart e cadastre-se em uma nova conta ^[8]. Depois abra a Página de Gerenciamento de Chaves de API no seu painel e gere uma chave de API ^[1][5].

Copie essa chave imediatamente e armazene-a no lado do servidor. Um gerenciador de segredos ou uma variável de ambiente é o lugar mais seguro para ela.

Nunca coloque sua chave de API em código de frontend ou em um repositório público. Se alguém pegar essa chave, pode usar sua conta. No Node.js, armazene-a com process.env.API_KEY. Em um ambiente de shell, use export API_KEY="your-key-here" ^[1][6].

Antes de construir o fluxo completo de requisição, envie uma pequena requisição POST para garantir que o acesso funciona ^[1][2]. Se você receber uma resposta 200 OK, sua chave e permissões estão configuradas corretamente.

Depois disso, você pode passar para os campos da requisição, incluindo o modelo e o prompt.

2.2 Defina a URL base e o cabeçalho de autenticação Bearer

Uma vez que você escolheu o modo T2I ou I2I e tem sua chave pronta, você precisa configurar a autenticação antes que qualquer requisição de imagem funcione. Envie estes cabeçalhos com cada requisição:

O prefixo Bearer importa. Deixe-o de fora, e a requisição vai falhar ^[2][5]. Também use exatamente um espaço depois de Bearer.

Códigos de status HTTP ajudam você a detectar problemas de autenticação rápido ^[1][10]. Um erro 401 Unauthorized normalmente significa que a chave está faltando, inválida, ou que o prefixo Bearer não foi incluído ^[1][10]. Um erro 403 Forbidden normalmente significa que a chave em si é válida, mas a conta não tem acesso ao modelo ou saldo suficiente ^[1][10].

Uma boa maneira de checar isso é testar com cURL primeiro. Se o cURL funciona mas seu app não, o bug provavelmente está no código de requisição do seu app ^[2][6].

Com a autenticação definida, o próximo passo é montar o corpo da requisição de imagem.

3. Monte uma requisição de imagem do Seedream 5.0 Pro

3.1 Campos obrigatórios: modelo, prompt, tamanho e contagem de imagens

Com a autenticação configurada, o próximo passo é montar o corpo JSON.

Um corpo de requisição válido precisa de quatro campos: model, prompt, size e n.

Para o Seedream 5.0 Pro, defina model como doubao-seedream-5-0-pro ^[1]. O campo prompt aceita uma descrição em linguagem natural e suporta até 5,000 caracteres ^[2]. O campo size controla as dimensões de saída ou a proporção. Valores comuns incluem 1024x1024, 2K e proporções como 1:1 ou 16:9 ^[1][2]. O campo n define quantas imagens gerar, geralmente de 1 a 15 ^[1][6].

Um pequeno detalhe pode confundir as pessoas: n deve ser um inteiro, não uma string. Se você passar "1" em vez de 1, a API retorna um erro de validação ^[1][5].

3.2 Campos opcionais: imagens de referência, busca na web e jobs assíncronos

image_urls é o campo principal para o modo imagem para imagem. Use-o para enviar até 14 imagens de referência como URLs ou Data URIs em Base64. Cada imagem deve ter menos de 10 MB e usar uma proporção entre 1:3 e 3:1 ^[1]. Se você está usando Base64, inclua o prefixo completo do Data URI - data:image/jpeg;base64, - ou a requisição vai falhar ^[1][5].

web_search pode ajudar com prompts factuais ou em tempo real, como eventos atuais ou logotipos de marcas ^[4][7]. Para a maioria das gerações de imagem padrão, você não vai precisar dele.

Para jobs assíncronos ou em lote, callback_url aceita um endpoint HTTPS público onde a APIMart fará um POST do payload de conclusão da tarefa ^[2].

3.3 Exemplos de chamadas de API em cURL e JavaScript

Aqui vai uma requisição cURL mínima funcionando para uma única imagem 1024×1024:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

E aqui vai a mesma requisição em Node.js com fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Mantenha esta requisição no lado do servidor. Nunca exponha sua chave de API em código do lado do cliente.

Uma vez que você envia a requisição, o próximo passo é analisar o payload de resposta.

4. Trate as respostas e execute fluxos de imagem comuns

4.1 Analise URLs de imagem, saída em Base64 e objetos de erro

Uma vez que a requisição termina, o formato da resposta permanece o mesmo, quer você tenha enviado uma imagem ou várias.

Uma resposta bem-sucedida retorna um objeto JSON com quatro campos de nível superior: model, created (um timestamp Unix), data (um array de objetos de imagem) e usage ^[6]. Cada imagem gerada aparece dentro de data como uma string url ou b64_json, com base no formato que você pediu. Se n for maior que 1, data inclui um objeto de imagem por saída.

Se você usou o formato URL, cada item em data armazena o link da imagem em .url. Você pode definir esse valor como um src de imagem no navegador. Um detalhe: esses são links assinados temporários, e expiram após 24 horas ^[6]. Para apps de produção, baixe o arquivo imediatamente e salve-o em armazenamento permanente em vez de guardar a URL.

Se você usou o formato Base64, cada item em data armazena a string bruta em .b64_json. Ela não inclui o prefixo data:image/...;base64, ^[6]. Para exibi-la em um navegador, adicione esse prefixo você mesmo:

img.src = "data:image/png;base64", + data.b64_json;

Para salvá-la como arquivo em Python, decodifique-a primeiro:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Se a requisição falha, a resposta inclui um campo code e um campo message ^[6]. Um 400 normalmente significa um tamanho não suportado ou um parâmetro inválido. Um 401 significa que a requisição não está autorizada. Registre ambos os campos toda vez. Na maioria dos casos, a message aponta direto para o problema.

Use esses campos para decidir se você deve armazenar, decodificar ou exibir a saída.

---

4.2 Três tipos comuns de imagem que você pode gerar com o Seedream 5.0 Pro

Esses três padrões se alinham com os modos abordados antes: apenas texto, referência única e múltiplas referências.

• Visuais de marketing apenas com texto. Para ativos de campanha que precisam de mais detalhe, use resolução 3K (size: "3K") e escreva um prompt estruturado que comece com o assunto e o layout da cena, e depois adicione detalhes de iluminação, estilo e cor. A geração em 3K leva de 35 a 50 segundos, então o assíncrono costuma ser o melhor encaixe.

• Variações de produto com referência única. Use o modo imagem para imagem com uma imagem de referência em image_urls e um prompt focado que altere apenas o que você quer, como o fundo, a iluminação ou a textura da superfície. Isso mantém a forma e os detalhes do produto mais próximos da imagem de origem do que gerar do zero. Para variações em 3K, use callback_url, já que cada tarefa pode levar cerca de 40 segundos ^[2].

• Consistência de múltiplas referências para consistência de marca e personagem. Se você precisa que um personagem ou elemento de marca permaneça consistente em várias imagens, passe até 14 imagens de referência através de image_urls ^[2][3]. Defina sequential_image_generation como auto ao criar múltiplas saídas a partir de entradas de referência para manter a variedade sem perder a consistência visual ^[5][4]. Isso funciona bem para séries de conteúdo social, catálogos de produtos e fichas de personagem.

Esses padrões tendem a funcionar melhor quando o formato de resposta combina com o fluxo de trabalho.

---

4.3 Requisições síncronas vs. assíncronas e respostas em URL vs. Base64

Use esta comparação para escolher o formato de resposta antes de colocar a integração no ar.

Para jobs assíncronos, espere cerca de 20 segundos antes do primeiro polling, depois verifique a cada 3 segundos ^[2]. Em produção, callback_url é a melhor opção porque evita loops de polling e reduz a sobrecarga do servidor ^[2][9].

Use respostas em URL por padrão. Mude para Base64 apenas quando precisar dos dados da imagem na mesma resposta.

5. Checklist final para uma integração confiável do Seedream 5.0 Pro

Depois da sua primeira chamada de teste bem-sucedida, percorra este checklist antes de escalar para produção. É uma maneira simples de pegar os problemas que costumam travar lançamentos.

Autenticação e segurança da chave. Mantenha sua chave de API em uma variável de ambiente ou em um gerenciador de segredos. Envie requisições do seu backend com Authorization: Bearer <your_key>.

Valide os parâmetros da requisição antes de enviá-los. Verifique a string do modelo, passe n como um inteiro, mantenha image_urls dentro do limite permitido e garanta que o size solicitado seja suportado.

Para jobs que levam mais do que uma prévia rápida, ajuste seu caminho de entrega adequadamente. Defina timeouts com base no tamanho da saída e use callback_url para jobs de longa duração em vez de polling.

Uma vez que a imagem esteja pronta, trate a entrega como um problema de armazenamento, não apenas de resposta. Se você usa saída em URL, baixe o arquivo imediatamente e mova-o para armazenamento permanente. URLs assinadas expiram após 24 horas ^[6].

Teste prompts em um pequeno lote antes de escalar. O Seedream 5.0 é cobrado a cerca de $0.0320 por imagem gerada ^[2]. Registre createTime, completeTime e costTime para acompanhar latência e gasto ^[2].

Perguntas frequentes

Como verifico um job de imagem assíncrono depois de obter um task_id?

Use o task_id retornado para verificar o status do seu job de imagem assíncrono.

Envie uma requisição GET ao endpoint de status que a API fornece. Em muitas APIs, isso se parece com:

• /v1/tasks/{task_id}
• ou um endpoint em estilo de query com o task_id

Para uso em produção, espere cerca de 20 segundos após criar a tarefa antes da sua primeira verificação de status. Depois disso, faça polling a cada 3 segundos até o status do job mostrar completed.

Uma vez que o job esteja concluído, leia o payload de resposta e extraia as URLs da imagem dele.

Quando devo usar saída em URL em vez de Base64?

Use saída em URL na maioria dos casos. Ela dá um link direto para a imagem gerada, o que facilita plugar em apps web ou móveis.

Use Base64 apenas quando sua configuração precisa dos dados da imagem embutidos no corpo da resposta, como processamento em memória ou quando você quer pular uma segunda requisição. Para ativos de alta resolução em 4K, a saída em URL costuma ser mais eficiente.

Qual é a melhor maneira de evitar perder imagens geradas?

Salve as imagens geradas prontamente, porque os links de imagem da API são válidos por apenas 72 horas.

A API do Seedream 5.0 Pro roda de forma assíncrona. Isso significa que você não vai receber a URL da imagem imediatamente. Primeiro, você recebe um ID de tarefa. Depois usa esse ID de tarefa para buscar a URL da imagem.

Para evitar perder a saída, você tem duas opções principais:

• Faça polling com o ID da tarefa até a imagem ficar pronta
• Use uma callback URL para que seu sistema possa receber, capturar e armazenar a imagem antes de o link expirar

Se você esperar demais, a URL vai expirar e a imagem pode ser perdida.