A API do Seedream 5.0 Pro dá aos programadores acesso ao modelo emblemático de geração e edição de imagens da ByteDance, através de um fluxo assíncrono pensado para produção. Este guia mostra como submeter tarefas de texto para imagem e de edição de imagem através da Poyo.ai e como obter depois o resultado com polling ou com um webhook.
O preço atual é de 15 créditos, cerca de $0.075 por imagem gerada, nas duas variantes do modelo.
Modelos e parâmetros da API
| Fluxo de trabalho | ID do modelo |
|---|---|
| Texto para imagem | seedream-5.0-pro |
| Edição de imagem | seedream-5.0-pro-edit |
Entre as entradas suportadas contam-se:
prompt: instrução de geração ou de edição, obrigatóriasize: uma predefinição de resolução como1Kou2K, ou uma proporção como1:1,4:3,3:4,16:9ou9:16n: número de imagens a geraroutput_format:jpegoupngimage_urls: imagens de referência para o modelo de edição, até 10callback_url: endpoint HTTPS opcional para notificações de conclusão
Consulta a referência da API em direto para veres o esquema atual.
1. Cria uma chave de API
Cria uma conta na Poyo.ai, abre a gestão de chaves de API e guarda a chave numa variável de ambiente. Nunca exponhas uma chave de produção em código de navegador nem a envies para o Git.
export POYO_API_KEY="your-api-key"
2. Submete um pedido de texto para imagem
Todas as tarefas utilizam o endpoint de submissão unificado:
POST https://api.poyo.ai/api/generate/submit
cURL
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header "Authorization: Bearer $POYO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "seedream-5.0-pro",
"callback_url": "https://example.com/webhooks/poyo",
"input": {
"prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
"size": "3:4",
"n": 1,
"output_format": "png"
}
}'
A resposta contém o ID de uma tarefa:
{
"code": 200,
"data": {
"task_id": "task-unified-example",
"status": "not_started",
"created_time": "2026-07-16T10:10:00"
}
}
3. Chama o Seedream 5.0 Pro com JavaScript
const API_URL = 'https://api.poyo.ai/api/generate/submit';
async function generateSeedreamImage(prompt) {
const response = await fetch(API_URL, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.POYO_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'seedream-5.0-pro',
input: {
prompt,
size: '2K',
n: 1,
output_format: 'png',
},
}),
});
const payload = await response.json();
if (!response.ok || payload.code !== 200) {
throw new Error(payload.error?.message || 'Seedream request failed');
}
return payload.data.task_id;
}
Usa 2K quando a resolução importa mais do que uma proporção fixa. Usa um valor de proporção quando o formato de colocação for a principal restrição.
4. Chama o Seedream 5.0 Pro com Python
import os
import requests
API_URL = "https://api.poyo.ai/api/generate/submit"
def generate_seedream_image(prompt: str) -> str:
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "seedream-5.0-pro",
"input": {
"prompt": prompt,
"size": "16:9",
"n": 1,
"output_format": "jpeg",
},
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("code") != 200:
raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
return payload["data"]["task_id"]
5. Edita imagens com várias referências
Troca o ID do modelo e fornece image_urls. Diz ao modelo o que cada referência contribui.
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header "Authorization: Bearer $POYO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "seedream-5.0-pro-edit",
"input": {
"prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
"image_urls": [
"https://example.com/room.jpg",
"https://example.com/chair.png",
"https://example.com/logo.png"
],
"size": "16:9",
"n": 1,
"output_format": "png"
}
}'
Para edições fiáveis, separa o prompt em três ideias: funções das referências, alterações pedidas e restrições de preservação.
6. Obtém o resultado
A submissão é assíncrona. Depois de receberes o task_id, podes:
- fazer polling ao endpoint unificado de estado das tarefas da Poyo.ai; ou
- indicar um
callback_urle processar o webhook de conclusão.
Segue a documentação de gestão de tarefas para veres a rota de estado e o objeto de resposta atuais. Em produção, usa um backoff exponencial em vez de fazeres polling continuamente.
Tratamento de erros
Trata estes casos de forma explícita:
400: parâmetros do modelo inválidos, tamanhos não suportados, URLs de imagem inacessíveis ou JSON malformado401: chave de API em falta ou inválida- tarefa assíncrona falhada: a geração falhou depois de uma submissão válida
- nova tentativa de webhook: o mesmo evento de conclusão pode ser entregue mais do que uma vez
Guarda o ID da tarefa junto do ID interno do teu job, torna o tratamento do webhook idempotente e regista as mensagens de erro do fornecedor sem registar segredos.
Lista de verificação para produção
- Mantém as chaves de API do lado do servidor.
- Valida o comprimento do prompt e os tipos de URL das imagens antes da submissão.
- Usa imagens de referência em HTTPS a que o serviço de geração consiga aceder.
- Define limites de tempo para os pedidos de submissão.
- Repete os erros de rede transitórios, mas não repitas às cegas pedidos inválidos.
- Acompanha o custo como
número de resultados pedidos × 15 créditosaos preços atuais. - Revê o texto gerado, os detalhes de produto e as afirmações factuais antes de publicares.
- Acrescenta uma moderação de conteúdo adequada ao teu produto e ao teu mercado.
Quando usar o Pro em vez do Lite
Usa o Seedream 5.0 Pro para designs estruturados, layouts densos, texto multilingue e edições controladas. Usa o Seedream 5.0 Lite para tarefas de imagem mais baratas e de maior volume, em que não é necessária a precisão de design do nível Pro.
Para uma visão geral não técnica, lê funcionalidades e preços do Seedream 5.0 Pro. Também podes testar visualmente o payload da API na página do modelo Seedream 5.0 Pro.
Perguntas frequentes
Qual é o endpoint da API do Seedream 5.0 Pro?
Submete as tarefas de geração e de edição para POST https://api.poyo.ai/api/generate/submit.
Qual é o ID do modelo de edição?
Usa seedream-5.0-pro-edit e inclui um ou mais valores em input.image_urls.
Quantas imagens de referência são suportadas?
A documentação atual da Poyo.ai suporta até 10 imagens de referência na edição do Seedream 5.0 Pro.
Quanto custa uma imagem pela API?
O preço atual da Poyo.ai é de 15 créditos, cerca de $0.075, por cada imagem gerada ou editada.