APIMart
APIMart

Como gerar imagens com o Seedream 5.0 Pro

Guia passo a passo para chamar o Seedream 5.0 Pro na APIMart: autenticação, campos da requisição, consulta de tarefas, leitura dos resultados e como salvar as imagens antes de os links expirarem.

Tutorial

Você coloca o Seedream 5.0 Pro para funcionar com uma requisição POST, uma API key e mais um passo: envia o trabalho, recebe um task_id e consulta a tarefa até a imagem ficar pronta. O Seedream 5.0 Pro é assíncrono, então a primeira resposta nunca traz a imagem.

A versão curta:

  • Envio as requisições para https://api.apimart.ai/v1/images/generations
  • Adiciono Authorization: Bearer YOUR_API_KEY
  • Defino model como seedream-5-0-pro
  • Incluo prompt, além de resolution (1K, 1.5K ou 2K) e size (auto ou uma proporção como 16:9)
  • Para editar ou combinar imagens, adiciono até 10 imagens de referência em image_urls
  • Consulto GET /v1/tasks/{task_id} a cada 5–10 segundos até o status ser completed
  • Baixo o resultado na hora, porque os links de imagem valem por 72 horas

O mais importante: é um modelo de imagem única. Cada requisição retorna uma imagem, e n maior que 1 é recusado. Você pode testar a Seedream 5.0 Pro API na APIMart; a lista completa de campos está na referência da API.

APIMart
Seedream 5.0 Pro API: resumo de requisição e consulta

Principais pontos

  • O Seedream 5.0 Pro é chamado com uma requisição POST para https://api.apimart.ai/v1/images/generations, o cabeçalho Authorization: Bearer YOUR_API_KEY e model igual a seedream-5-0-pro.
  • Escolha o nível de saída com resolution (1K, 1.5K ou 2K) e o formato com size: auto, uma de dez proporções ou pixels exatos. 1.5K custa o mesmo que 1K; 3K e 4K retornam 400.
  • Cada requisição gera uma imagem. n maior que 1, geração em grupo, streaming e busca na web são recusados com 400, e nenhuma tarefa é criada.
  • A edição de imagem envia até 10 imagens de referência em image_urls, como URLs públicas ou Data URIs em Base64.
  • A primeira resposta contém apenas um task_id. Consulte o endpoint de tarefas a cada 5–10 segundos e salve a imagem em até 72 horas.

Comparação rápida

ItemPara que usoLimite ou observação principal
Texto para imagemImagens novas só com o promptNão precisa de imagem de entrada
Edição com uma referênciaMudar fundo, luz ou detalhes de uma imagemUm item em image_urls
Edição com várias referênciasCombinar pessoas, roupas ou cenasAté 10 imagens de referência
Decomposição em camadasDividir um pôster em camadas editáveisExatamente uma imagem de entrada, até 16 camadas PNG
Fundo transparenteEditar uma camada mantendo o alfaUma imagem de entrada com alfa, output_format: "png"

Em resumo: este guia mostra como configuro a autenticação, monto o corpo da requisição, consulto a tarefa e salvo o resultado sem perder arquivos.

1. Configure o acesso à API e a autenticação

1.1 Crie sua conta na APIMart e gere uma API key

APIMart

Cadastre-se na APIMart, abra a página de gerenciamento de API keys no painel e crie uma chave. Copie-a na hora e guarde-a no servidor, em um gerenciador de segredos ou em uma variável de ambiente.

Nunca coloque a chave em código de frontend ou em um repositório público: quem tiver a chave pode gastar seu saldo. No Node.js, leia-a de process.env.APIMART_API_KEY; no terminal, use export APIMART_API_KEY="your-key-here".

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

Todas as requisições vão para a URL base https://api.apimart.ai com dois cabeçalhos:

CabeçalhoValor
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Mantenha o prefixo Bearer com exatamente um espaço. Um token ausente ou mal formatado retorna 401. Se o cURL funciona e seu app não, o problema costuma estar na forma como o app monta os cabeçalhos.

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

APIMart

2.1 Campos principais: Model, Prompt, Resolution e Size

Uma requisição de texto para imagem precisa de model e prompt. Outros dois campos controlam a saída:

  • model: seedream-5-0-pro (seedream-5.0-pro também é aceito).
  • prompt: uma descrição em linguagem natural. Além de chinês e inglês, o modelo renderiza texto nativamente em português, japonês, coreano, espanhol, francês, alemão, russo, indonésio, vietnamita e outros idiomas. Mantenha em cerca de 600 palavras em inglês; prompts muito longos podem perder detalhes.
  • resolution: 1K (padrão), 1.5K ou 2K. 1.5K custa o mesmo que 1K, então costuma ser a melhor escolha.
  • size: auto (padrão), uma de dez proporções (1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9) ou pixels exatos como 2048x1024. Pixels exatos devem somar entre 921.600 e 4.624.220, com proporção entre 1:16 e 16:1.

Por exemplo, resolution: "1.5K" com size: "16:9" retorna uma imagem de 2048×1152.

2.2 Campos opcionais

Parâmetro opcionalTipoQuando usar
image_urlsArrayEdição e composição com várias referências; até 10 URLs públicas ou Data URIs em Base64
output_formatStringjpeg (padrão) ou png
backgroundStringtransparent para manter o alfa ao editar uma imagem que já tem canal alfa (exige png)
layer_decompositionBooleanDividir uma imagem em uma base e até 16 camadas PNG transparentes
optimize_prompt_optionsObjectOtimização do prompt; só {"mode": "standard"} é aceito
watermarkBooleanAdicionar a marca “gerado por IA” no canto inferior direito
nsfw_checkBooleanModerar o prompt e as imagens de entrada antes de enviar a tarefa

Cada imagem de referência pode ser jpeg, png, webp, bmp, tiff, gif, heic ou heif, com até 30 MB e 36 milhões de pixels. A primeira referência é gratuita; cada referência extra soma uma taxa fixa.

Para direcionar uma edição com precisão, escreva coordenadas no prompt: <point>x y</point> para um ponto ou <bbox>x1 y1 x2 y2</bbox> para uma área.

2.3 Campos que este modelo recusa

O Seedream 5.0 Pro é um modelo de imagem única. Estas requisições retornam 400, não criam tarefa e não são cobradas:

  • n maior que 1, ou sequential_image_generation (use o Seedream 5.0 Lite para imagens em grupo)
  • stream ou tools (streaming e busca na web não são suportados)
  • mais de 10 itens em image_urls
  • níveis não suportados como 3K ou 4K, ou proporções fora da lista acima

2.4 Exemplos de chamadas em cURL e JavaScript

Esta é uma requisição cURL mínima para uma imagem 16:9 no nível 1.5K:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "resolution": "1.5K",
    "size": "16:9"
  }'

A resposta só confirma a tarefa:

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

E esta é uma edição com várias referências em Node.js com fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-5-0-pro",
    prompt: "Replace the outfit in image 1 with the outfit in image 2",
    image_urls: ["https://example.com/person.jpg", "https://example.com/dress.jpg"],
    resolution: "2K",
    size: "auto",
  }),
});

const { data } = await response.json();
const taskId = data[0].task_id;

Faça essas chamadas no servidor, nunca no código do cliente.

3. Consulte a tarefa e salve a imagem

3.1 Verifique o status da tarefa

Envie GET https://api.apimart.ai/v1/tasks/{task_id} com o mesmo cabeçalho Authorization. O Seedream 5.0 Pro prioriza a qualidade, então uma tarefa pode levar alguns minutos. Consulte a cada 5–10 segundos e defina o timeout do cliente em cerca de 5 minutos.

Pare de consultar quando status for completed ou failed. Tarefas com falha são reembolsadas integralmente.

3.2 Leia o resultado

Uma tarefa concluída fica assim:

{
  "code": 200,
  "data": {
    "id": "task_01JFXYZ123456789ABCDEF",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
          "expires_at": 1784696685
        }
      ]
    }
  }
}

Leia a imagem em data.result.images[0].url[0]. A resposta também traz o cost da tarefa. Os links valem 72 horas (expires_at é um timestamp Unix), então baixe o arquivo e leve-o para o seu próprio armazenamento em vez de guardar só a URL.

3.3 Exemplo completo em Python

import os
import time

import requests

BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-pro",
        "prompt": "A product poster with the headline SUMMER SALE in bold letters",
        "resolution": "1.5K",
        "size": "3:4",
        "output_format": "png",
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"][0]["task_id"]

while True:
    task = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers, timeout=30).json()["data"]
    if task["status"] == "completed":
        image_url = task["result"]["images"][0]["url"][0]
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", {}).get("message", task["status"]))
    time.sleep(5)

with open("seedream-5-0-pro.png", "wb") as f:
    f.write(requests.get(image_url, timeout=60).content)

4. Três fluxos de imagem comuns

  • Pôsteres e artes com texto. Escreva o texto exato entre aspas no prompt, descreva o layout (por exemplo, “pôster vertical, título no topo”) e use resolution: "1.5K" com uma proporção fixa como 3:4. Mude para 2K só nos materiais finais, já que esse nível custa mais.

  • Edição com várias referências. Coloque as imagens de pessoa, produto ou cena em image_urls e chame-as pela ordem no prompt (“imagem 1”, “imagem 2”). Com size: "auto", a proporção de saída acompanha as referências. Adicione coordenadas <bbox> para indicar exatamente onde algo deve ficar.

  • Decomposição em camadas e edições transparentes. Envie um PNG ou JPEG com layer_decomposition: true para receber uma imagem base e até 16 camadas PNG transparentes com dados de posição e empilhamento. Para editar uma camada, envie-a de volta com background: "transparent" e output_format: "png". Tarefas de camadas são cobradas por imagem gerada após uma pré-autorização, e o excedente é reembolsado.

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

Autenticação e segurança da chave. Guarde a chave em uma variável de ambiente ou em um gerenciador de segredos e chame a API apenas pelo backend.

Valide os parâmetros antes de enviar. Use seedream-5-0-pro, omita n (ou use 1), mantenha image_urls em até 10 e use apenas 1K, 1.5K ou 2K com um size suportado.

Planeje o fluxo assíncrono. Consulte a cada 5–10 segundos, defina um timeout de cliente de cerca de 5 minutos e trate as tarefas failed.

Trate a entrega como uma questão de armazenamento. Baixe cada imagem assim que a tarefa tiver sucesso; os links expiram em 72 horas.

Confira o custo antes de escalar. A saída é cobrada por imagem conforme o nível de pixels (1K e 1.5K dividem o preço mais baixo; 2K custa mais), e cada referência depois da primeira soma uma taxa. Veja a tabela de preços atualizada antes de rodar lotes grandes.

Perguntas frequentes

Como verifico uma tarefa de imagem depois de receber um task_id?

Envie GET https://api.apimart.ai/v1/tasks/{task_id} com o seu cabeçalho Authorization: Bearer.

Consulte a cada 5–10 segundos até status virar completed e leia a imagem em data.result.images[0].url[0]. Se o status for failed, verifique o campo error; tarefas com falha são reembolsadas.

Posso receber várias imagens ou saída em Base64 em uma única requisição?

Não. O Seedream 5.0 Pro retorna uma imagem por requisição, e n maior que 1 é recusado com 400. Para várias variações, envie várias requisições ou use o Seedream 5.0 Lite para geração em grupo.

O resultado é sempre uma URL; escolha jpeg ou png com output_format. Base64 é aceito para imagens de entrada em image_urls, não para a saída.

Qual é a melhor forma de não perder as imagens geradas?

Os links de imagem valem por 72 horas, e expires_at no resultado mostra o momento exato.

Baixe cada imagem para o seu próprio armazenamento assim que a tarefa chegar a completed e registre você mesmo o task_id. Não trate a URL retornada como armazenamento permanente.

Tags#Seedream 5.0 Pro#geração de imagens#tutorial de API#desenvolvedores

Sobre a equipe APIMart

A equipe APIMart escreve guias de modelos, comparativos e análises de preço para desenvolvedores que constroem com IA. A APIMart oferece uma única API para modelos de chat, imagem e vídeo de vários provedores, para que você compare os modelos citados aqui antes de lançar.

Pronto para testar?

Escolha o modelo que você quer no marketplace

Teste modelos de chat, imagem e vídeo no marketplace da APIMart e experimente rapidamente as capacidades dos modelos com uma API unificada.

Modelos de chatModelos de imagemModelos de vídeo
Explorar marketplace