API de edição Seedream v4.5: edição programática de imagens

Usar o Seedream v4.5 Edit pela interface do Arteza funciona bem para edições pontuais e pequenos lotes. Para fluxos de trabalho de alto volume, como catálogos com milhares de SKUs, geração de imagens dinâmica por usuário ou pipelines de assets orientados por CMS, o acesso via API é o caminho ideal. Este guia percorre a estrutura do endpoint, os parâmetros de requisição, o tratamento de respostas e os padrões de produção para construir sistemas automatizados de edição de imagens com o Seedream v4.5.

Resumo rápido

• O Seedream v4.5 Edit está disponível via endpoint fal-ai/bytedance/seedream/v4.5/edit
• Mesmo preço de 1 crédito ($0,10) por imagem que a interface
• Aceita até 10 URLs de imagens de entrada mais um prompt de texto
• Saída de 4MP (2048×2048) retornada como URL de imagem
• Tempo de geração típico de 30-60 segundos: use padrões assíncronos em produção

Por que usar a API

A API desbloqueia padrões de automação que a interface não consegue oferecer:

• Processamento em lote de alto volume. Processe mais de 1.000 edições em uma única execução de pipeline.
• Geração dinâmica. Crie imagens sob demanda a partir de dados do usuário ou registros de banco de dados.
• Fluxos de trabalho agendados. Atualizações noturnas de catálogo, regeneração disparada por eventos.
• Integração com stacks existentes. Node.js, Python, Go, Ruby: qualquer cliente HTTP.
• Produção reproduzível. Scripts versionados no lugar de cliques manuais.

Se o seu caso de uso envolve mais de 20-50 edições semelhantes, a API vale o esforço de configuração.

Estrutura do endpoint

O modelo Seedream v4.5 Edit está disponível em:

fal-ai/bytedance/seedream/v4.5/edit

Este é um endpoint de modelo padrão do fal.ai que pode ser chamado diretamente ou via sistema de créditos do Arteza.

Autenticação

As requisições à API do Arteza são autenticadas via chave de API passada no cabeçalho Authorization como token Bearer.

Obtendo sua chave de API

1. Entre em arteza.ai
2. Acesse as configurações da sua conta
3. Encontre a seção de API
4. Gere uma nova chave de API
5. Armazene-a com segurança: trate-a como uma senha

Nunca inclua sua chave de API no controle de versão. Use variáveis de ambiente:

export SEEDANCE_API_KEY="your_api_key_here"

Cabeçalho de autenticação

Authorization: Bearer your_api_key_here

Estrutura da requisição

Uma requisição básica ao Seedream v4.5 Edit tem esta aparência:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Referência de parâmetros

É possível passar até 10 URLs de imagens. O modelo trata a primeira imagem como a principal e as imagens seguintes como referências.

Exemplo de requisição: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Exemplo de requisição: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Estrutura da resposta

Uma resposta bem-sucedida inclui as URLs das imagens geradas:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Baixe a imagem a partir da URL retornada: as URLs de saída são válidas por 24 horas.

Padrão de geração assíncrona

O Seedream v4.5 Edit leva de 30-60 segundos por requisição. Em produção, é recomendável usar geração assíncrona com webhooks ou polling em vez de requisições bloqueantes.

Assíncrono com webhook

Passe um webhook_url na sua requisição e o Arteza enviará o resultado via POST assim que a geração for concluída:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Seu handler de webhook recebe:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

O uso de webhooks é o padrão recomendado para produção.

Comece a construir. Experimente a ferramenta primeiro.

Assíncrono com polling

Se sua infraestrutura não consegue receber webhooks, consulte o status periodicamente:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Consultar até concluir
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Faça o polling a cada 5-10 segundos. O tempo de espera total costuma ser de 30-60 segundos.

Padrões de produção

Padrão 1: geração em lote para catálogos

Execute a API sobre o seu catálogo de produtos para gerar trocas de fundo consistentes para cada SKU:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Combine com um handler de webhook que salva as saídas no seu CDN e atualiza o registro do produto.

Padrão 2: edições sob demanda pelo usuário

Permita que os usuários façam upload de imagens e recebam resultados editados por IA sob demanda:

1. O usuário faz upload da imagem para o seu bucket
2. Seu backend chama o Seedream v4.5 Edit com um prompt escolhido pelo usuário
3. Faça polling ou aguarde o webhook
4. Retorne a URL do resultado para o cliente do usuário

Planeje cerca de 60 segundos de tempo de espera por edição na sua experiência de usuário.

Padrão 3: pipeline de assets orientado por CMS

Quando um conteúdo é publicado no seu CMS, gere automaticamente as imagens associadas:

1. O CMS emite um evento de publicação
2. Uma função serverless é disparada
3. Chama o Seedream v4.5 Edit com um prompt de template
4. Armazena o resultado no CDN
5. Atualiza o registro do CMS com a URL da imagem

Este padrão elimina a criação manual de imagens em publicações de alto volume.

Tratamento de erros

Respostas de erro mais comuns:

Sempre envolva as chamadas de API em try/except com lógica de repetição para respostas 429 e 500.

Limites de taxa

O Arteza aplica limites de taxa razoáveis na API. Para a maioria dos fluxos de trabalho em produção você não os atingirá, mas para lotes em massa com mais de 1.000 requisições, implemente:

• Backoff exponencial em respostas 429
• Limites de requisições concorrentes (comece com 5 em paralelo e ajuste para cima)
• Fila de requisições para um throughput previsível

Entre em contato com o suporte para limites de taxa mais altos em cargas de trabalho pesadas de produção.

Custo em volume de API

As chamadas via API custam o mesmo que pela interface: 1 créditos ($0,10) por imagem. Para fins de planejamento:

• 100 chamadas de API = 100 créditos (bem dentro do plano Starter de $5)
• 1.000 chamadas de API = 1.000 créditos (o plano Studio de $120, com 1.800 por mês)
• 10.000 chamadas de API = 10.000 créditos (o plano Studio de $120 mais cerca de 8.200 créditos em recargas)

Para volumes acima de 10.000 por mês, entre em contato com a equipe para uma precificação personalizada.

Boas práticas

1. Use webhooks em produção. O polling funciona, mas desperdiça recursos.
2. Armazene prompts no controle de versão. Trate prompts como código.
3. Registre tudo. IDs de requisição, prompts, saídas e erros.
4. Valide as entradas antes de chamar. URLs de imagem inválidas desperdiçam créditos.
5. Monitore o saldo de créditos. Configure alertas quando cair abaixo de um limite.
6. Teste mudanças de prompt em staging. Valide em 3-5 imagens antes de executar um lote completo.
7. Armazene os resultados em cache. Se as entradas forem idênticas, reutilize as saídas anteriores.

Leitura adicional

• Guia completo de edição do Seedream v4.5
• Tutorial de edição em lote
• Detalhamento de preços

Primeiros passos

Gere sua chave de API no painel do Arteza, resgate 10 créditos grátis e execute o exemplo em Node.js acima com uma foto de produto. A API desbloqueia todo o potencial produtivo do Seedream v4.5 Edit: uma vez configurada, todo o resto é engenharia de prompts. Para testes práticos primeiro, abrir a ferramenta web e valide seus prompts antes de automatizar.