A API Kling 4.0 já está disponível. Crie vídeos →
PoYoPoYo
tutorials

Guia da API do Seedream 5.0 Pro: Gere e Edite Imagens com Código

Poyo.ai Team
6 min read
Share:

Guia da API do Seedream 5.0 Pro

A API do Seedream 5.0 Pro oferece aos desenvolvedores acesso ao principal modelo de geração e edição de imagens da ByteDance por meio de um fluxo de trabalho assíncrono voltado para produção. Neste guia, você aprenderá a enviar tarefas de geração de imagens a partir de texto e de edição de imagens usando o Poyo.ai, além de recuperar os resultados por polling ou webhook.

O preço atual é de 15 créditos, cerca de $0.075 por imagem gerada, para ambas as variantes do modelo.

Modelos e Parâmetros da API

Fluxo de trabalhoID do modelo
Texto para imagemseedream-5.0-pro
Edição de imagensseedream-5.0-pro-edit

As entradas compatíveis incluem:

  • prompt: instrução obrigatória para geração ou edição
  • size: uma predefinição de resolução como 1K ou 2K, ou uma proporção como 1:1, 4:3, 3:4, 16:9 ou 9:16
  • n: número de imagens a serem geradas
  • output_format: jpeg ou png
  • image_urls: imagens de referência para o modelo de edição, até 10
  • callback_url: endpoint HTTPS opcional para notificações de conclusão

Consulte a referência da API em tempo real para acessar o esquema mais atualizado.

1. Crie uma Chave de API

Crie uma conta no Poyo.ai, acesse Gerenciamento de Chaves de API e armazene a chave em uma variável de ambiente. Nunca exponha uma chave de produção em código executado no navegador nem faça commit dela no Git.

export POYO_API_KEY="your-api-key"

2. Envie uma Solicitação de Texto para Imagem

Todas as tarefas utilizam o endpoint unificado de envio:

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 um ID da tarefa:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Chame 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;
}

Use 2K quando a resolução for mais importante do que uma proporção fixa. Use um valor de proporção quando o formato de exibição for a principal restrição.

4. Chame 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. Edite Imagens com Múltiplas Referências

Altere o ID do modelo e forneça image_urls. Informe ao modelo qual é a função de cada imagem de referência.

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 obter edições consistentes, divida o prompt em três partes: papéis das referências, alterações solicitadas e restrições de preservação.

6. Recupere o Resultado

O envio é assíncrono. Após receber o task_id, você pode:

  • fazer polling no endpoint unificado de status de tarefas do Poyo.ai; ou
  • fornecer callback_url e processar o webhook de conclusão.

Consulte a documentação de gerenciamento de tarefas para obter a rota de status e o objeto de resposta mais atuais. Em produção, utilize exponential backoff em vez de fazer polling contínuo.

Tratamento de Erros

Trate explicitamente os seguintes casos:

  • 400: parâmetros de modelo inválidos, tamanhos não compatíveis, URLs de imagens inacessíveis ou JSON malformado
  • 401: chave de API ausente ou inválida
  • falha na tarefa assíncrona: a geração falhou após um envio válido
  • nova tentativa de webhook: o mesmo evento de conclusão pode ser entregue mais de uma vez

Armazene o ID da tarefa junto com o ID interno do seu processo, torne o processamento de webhooks idempotente e registre as mensagens de erro do provedor sem registrar informações sensíveis.

Checklist para Produção

  • Mantenha as chaves de API apenas no servidor.
  • Valide o comprimento do prompt e os tipos das URLs das imagens antes do envio.
  • Use imagens de referência via HTTPS que possam ser acessadas pelo serviço de geração.
  • Defina timeouts para as chamadas de envio.
  • Tente novamente em caso de erros transitórios de rede, mas não repita automaticamente solicitações inválidas.
  • Acompanhe o custo como número de saídas solicitadas × 15 créditos com o preço atual.
  • Revise textos gerados, detalhes de produtos e informações factuais antes da publicação.
  • Adicione moderação de conteúdo adequada ao seu produto e mercado.

Quando Usar o Pro em vez do Lite

Use o Seedream 5.0 Pro para designs estruturados, layouts complexos, texto multilíngue e edições controladas. Use o Seedream 5.0 Lite para tarefas de geração de imagens em maior volume e menor custo, quando a precisão de design do Pro não for necessária.

Para uma visão geral voltada a quem não é técnico, leia recursos e preços do Seedream 5.0 Pro. Você também pode testar visualmente a carga útil da API na página do modelo Seedream 5.0 Pro.

Perguntas Frequentes

Qual é o endpoint da API do Seedream 5.0 Pro?

Envie tarefas de geração e edição para POST https://api.poyo.ai/api/generate/submit.

Qual é o ID do modelo de edição?

Use seedream-5.0-pro-edit e inclua um ou mais valores em input.image_urls.

Quantas imagens de referência são compatíveis?

A documentação atual do Poyo.ai oferece suporte a até 10 imagens de referência para edição com o Seedream 5.0 Pro.

Quanto custa uma imagem pela API?

O preço atual do Poyo.ai é de 15 créditos, cerca de $0.075, para cada imagem gerada ou editada.

Share: