Seedream v4.5 Edit API: Edição de Imagens Programática

Executar Seedream v4.5 Edit através da interface do Arteza funciona bem para edições pontuais e lotes pequenos. Para fluxos de trabalho de alto volume - catálogos com milhares de SKUs, geração de imagens dinâmica por usuário, pipelines de ativos orientados por CMS - você quer acesso à API. Este guia aborda a estrutura do endpoint, parâmetros de requisição, manipulação de respostas e padrões de produção para construir sistemas automatizados de edição de imagens no Seedream v4.5.

Por que usar a API

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

• Lotes de alto volume. Processe 1.000+ edições em uma única execução de pipeline.
• Geração dinâmica. Construa imagens sob demanda a partir de dados do usuário ou registros de banco de dados.
• Fluxos de trabalho agendados. Atualizações de catálogo noturnas, regeneração acionada por eventos.
• Integração com pilhas existentes. Node.js, Python, Go, Ruby - qualquer cliente HTTP.
• Produção reproduzível. Scripts controlados por versão em vez de cliques manuais.

Se seu caso de uso envolve mais de 20 a 50 edições similares, a API vale a pena configurar.

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 da API do Arteza se autenticam por meio de uma chave de API passada no cabeçalho Authorization como um token Bearer.

Obtendo sua chave de API

1. Faça login em arteza.ai
2. Navegue até 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 como uma senha

Nunca faça commit da sua chave de API no controle de versão. Use variáveis de ambiente:

export SEEDANCE_API_KEY="sua_chave_api_aqui"

Cabeçalho de Autenticação

Authorization: Bearer sua_chave_api_aqui

Estrutura da Requisição

Uma requisição básica do Seedream v4.5 Edit fica assim:

{
  "prompt": "Substitua o fundo por uma superfície de mármore polida. Preserve a posição, cor e iluminação do produto exatamente. Adicione uma sombra de contato sutil.",
  "image_urls": [
    "https://seu-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Referência de Parâmetros

Até 10 URLs de imagem podem ser passadas. O modelo trata a primeira imagem como principal e imagens subsequentes como referências.

Requisição de Amostra: 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: "Substitua o fundo por uma superfície de mármore polida. Preserve a posição, cor e iluminação do produto exatamente.",
    image_urls: [
      "https://seu-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

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

Requisição de Amostra: 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": "Substitua o fundo por uma superfície de mármore polida. Preserve a posição, cor e iluminação do produto exatamente.",
        "image_urls": [
            "https://seu-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 de imagem 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

Seedream v4.5 Edit leva 30 a 60 segundos por requisição. Para produção você provavelmente quer geração assíncrona com webhooks ou polling em vez de requisições bloqueantes.

Async Baseado em Webhook

Passe uma webhook_url na sua requisição e o Arteza fará POST do resultado para ela quando a geração for concluída:

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

Seu manipulador de webhook recebe:

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

O tratamento de webhook é o padrão de produção recomendado.

Comece a construir. Experimente a ferramenta primeiro.

Async Baseado em Polling

Se sua infraestrutura não conseguir receber webhooks, faça polling do status:

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();

// Faça polling para a conclusão
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 polling a cada 5 a 10 segundos. O tempo total de espera é geralmente 30 a 60 segundos.

Padrões de Produção

Padrão 1: Geração em Lote de Catálogo

Execute a API sobre 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 manipulador de webhook que salva as saídas no seu CDN e atualiza o registro do produto.

Padrão 2: Edições de Usuário sob Demanda

Permita que os usuários façam upload de imagens e obtenham resultados com edição AI sob demanda:

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

Orce ~60 segundos de tempo de espera por edição em sua UX.

Padrão 3: Pipeline de Ativos Orientado por CMS

Quando o conteúdo é publicado em seu CMS, gere automaticamente imagens associadas:

1. CMS emite um evento de publicação
2. Função serverless é acionada
3. Chama Seedream v4.5 Edit com um prompt de modelo
4. Armazena resultado no CDN
5. Atualiza registro do CMS com URL de imagem

Este padrão elimina a criação manual de imagens para publicação de alto volume.

Tratamento de Erros

Respostas de erro comum:

Sempre envolva as chamadas da API em try/except com lógica de retry 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 de produção você não atingirá, mas para lotes em massa com 1.000+ requisições, implemente:

• Backoff exponencial em respostas 429
• Limites de requisições simultâneas (comece com 5 paralelas, aumente)
• Fila de requisições para throughput previsível

Contate o suporte para limites de taxa mais altos em cargas de trabalho de produção pesada.

Custo em Volume de API

As chamadas de API custam o mesmo que as chamadas da interface: 8 créditos ($0,08) por imagem. Para fins de planejamento:

• 100 chamadas de API = 800 créditos (nível Starter, $10)
• 1.000 chamadas de API = 8.000 créditos (nível Pro, $50)
• 10.000 chamadas de API = 80.000 créditos (múltiplos níveis Studio, ~$650)

Para volumes acima de 10.000/mês, contate a equipe para preços customizados.

Melhores Práticas

1. Use webhooks em produçã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, erros.
4. Valide entradas antes de chamar. URLs de imagem ruins desperdiçam créditos.
5. Monitore saldo de créditos. Alerte quando cair abaixo de um limite.
6. Teste mudanças de prompt em staging. Valide em 3 a 5 imagens antes de executar um lote completo.
7. Coloque resultados em cache. Se as entradas forem idênticas, reutilize as saídas anteriores.

Leitura Adicional

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

Começar

Gere sua chave de API no painel do Arteza, pegue 50 créditos grátis e execute o exemplo Node.js acima com uma foto de produto. A API desbloqueia o potencial completo de produção do Seedream v4.5 Edit - uma vez que está conectado, todo o resto é engenharia de prompt. Para testes práticos primeiro, abrir a ferramenta web e valide seus prompts antes de automatizar.