API de edição do Seedream 5.0: edição de imagens por programação

Interfaces web são ótimas para edições pontuais. APIs são como você edita 10.000 imagens durante a noite. A API de edição Seedream 5.0 oferece acesso programático ao mesmo modelo de edição em linguagem natural que alimenta a plataforma Arteza, ao mesmo preço de $0,10 por edição. Este guia aborda autenticação, endpoints, exemplos em Python e JavaScript, padrões de lote e boas práticas para produção.

Resumo rápido

• Acesso programático ao Seedream 5.0 Edit por $0,10 por edição (1 créditos)
• API REST com respostas JSON, geração em 5-15 segundos
• Exemplos em Python e JavaScript incluídos
• Desenvolvida para fluxos em lote: processe milhares de imagens por job
• 10 créditos gratuitos para testes em arteza.ai

Quando usar a API versus a interface web

Use a interface web quando:

• Você estiver editando 1-20 imagens manualmente
• Quiser iterar visualmente
• Estiver explorando direções criativas

Use a API quando:

• Você estiver editando 50 ou mais imagens
• Estiver criando um produto que edita imagens
• Precisar de prompts consistentes em um lote
• Quiser integrar a edição a um pipeline existente (exportação do Lightroom, Shopify, CMS etc.)

Autenticação

A API usa autenticação por token Bearer. Obtenha sua chave de API no Painel do Arteza após criar sua conta.

# Armazene sua chave como variável de ambiente
export SEEDANCE_API_KEY="your_api_key_here"

Nunca inclua chaves de API no git. Use variáveis de ambiente, gerenciadores de segredos ou arquivos .env.

O endpoint de edição

Endpoint: POST https://api.arteza.ai/v1/edit

Parâmetros obrigatórios:

Parâmetros opcionais:

Cada chamada bem-sucedida deduz 1 créditos.

Exemplo em Python

import os
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
API_URL = "https://api.arteza.ai/v1/edit"

def edit_image(image_path: str, prompt: str) -> bytes:
    with open(image_path, "rb") as f:
        files = {"image": f}
        data = {
            "prompt": prompt,
            "model": "seedream-5-lite-edit",
            "output_format": "png",
        }
        headers = {"Authorization": f"Bearer {API_KEY}"}
        response = requests.post(
            API_URL, files=files, data=data, headers=headers, timeout=60
        )
        response.raise_for_status()
        return response.content

# Uso
edited = edit_image(
    "product.jpg",
    "Replace background with seamless white studio, add soft shadow"
)
with open("product_edited.png", "wb") as f:
    f.write(edited)

Exemplo em JavaScript / Node.js

import fs from "fs";
import FormData from "form-data";
import axios from "axios";

const API_KEY = process.env.SEEDANCE_API_KEY;
const API_URL = "https://api.arteza.ai/v1/edit";

async function editImage(imagePath, prompt) {
  const form = new FormData();
  form.append("image", fs.createReadStream(imagePath));
  form.append("prompt", prompt);
  form.append("model", "seedream-5-lite-edit");
  form.append("output_format", "png");

  const response = await axios.post(API_URL, form, {
    headers: {
      ...form.getHeaders(),
      Authorization: `Bearer ${API_KEY}`,
    },
    responseType: "arraybuffer",
    timeout: 60000,
  });

  return response.data;
}

// Uso
const edited = await editImage(
  "product.jpg",
  "Apply warm golden-hour cinematic color grade"
);
fs.writeFileSync("product_edited.png", edited);

Exemplo com cURL

curl -X POST https://api.arteza.ai/v1/edit \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -F "image=@product.jpg" \
  -F "prompt=Replace background with clean white studio" \
  -F "model=seedream-5-lite-edit" \
  -o product_edited.png

Quer resultados assim? Experimente o Seedream 5.0 Edit grátis →

Padrão de processamento em lote

O caso de uso mais poderoso da API é o processamento em lote. Veja um padrão Python pronto para produção:

import os
import concurrent.futures
from pathlib import Path

def process_batch(image_dir: str, prompt: str, output_dir: str, workers: int = 4):
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    images = list(Path(image_dir).glob("*.jpg"))

    def process_one(img_path: Path):
        try:
            result = edit_image(str(img_path), prompt)
            output_path = Path(output_dir) / f"{img_path.stem}_edited.png"
            with open(output_path, "wb") as f:
                f.write(result)
            return (img_path.name, "success")
        except Exception as e:
            return (img_path.name, f"error: {e}")

    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
        results = list(executor.map(process_one, images))

    for name, status in results:
        print(f"{name}: {status}")

# Edite 100 fotos de produtos com o mesmo prompt
process_batch(
    image_dir="./raw_products",
    prompt="Replace background with pure white studio, soft shadow beneath",
    output_dir="./edited_products",
    workers=4,
)

Desempenho: com 4 workers, 100 imagens levam aproximadamente 3-5 minutos no total. Custo: 100 x 1 crédito = 100 créditos = $10 no total.

Tratamento de erros

A API retorna códigos de status HTTP padrão:

Padrão de retry

import time
import requests

def edit_with_retry(image_path: str, prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            return edit_image(image_path, prompt)
        except requests.HTTPError as e:
            if e.response.status_code in (429, 500, 502, 503, 504):
                wait = 2 ** attempt  # backoff exponencial: 1s, 2s, 4s
                time.sleep(wait)
                continue
            raise
    raise Exception("Max retries exceeded")

Fluxo com webhooks para grandes lotes

Para jobs com milhares de imagens, use webhooks para evitar polling prolongado:

# Envie um job com uma URL de webhook
response = requests.post(
    f"{API_URL}/batch",
    json={
        "model": "seedream-5-lite-edit",
        "images": ["s3://bucket/img1.jpg", "s3://bucket/img2.jpg", ...],
        "prompt": "Replace background with white studio",
        "webhook": "https://yourapp.com/webhook/seedance",
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
)
job_id = response.json()["job_id"]

# A Arteza enviará os resultados ao seu webhook quando o job for concluído

Limites de taxa

Se precisar de limites maiores, entre em contato com o suporte pelo seu painel.

Padrões comuns em produção

1. Pipeline de produtos no Shopify

# Busca novos produtos do Shopify → edita → envia de volta
for product in new_products:
    for image_url in product.images:
        edited = edit_image_url(image_url, BRAND_PROMPT)
        upload_to_shopify(product.id, edited)

Veja o guia de fotos de produtos para ideias de prompts.

2. Automação de listagens imobiliárias

# Aprimore automaticamente as fotos de novos imóveis
for photo in listing.photos:
    if photo.type == "exterior":
        edited = edit_image(photo.path, "Replace sky with blue clear sky, brighten")
    elif photo.type == "interior_empty":
        edited = edit_image(photo.path, "Stage in modern Scandinavian style")
    save_to_mls(edited)

Veja o guia de decoração virtual para modelos de prompts.

3. Pipeline de conteúdo para redes sociais

# Gere variantes para múltiplas plataformas a partir de cada publicação
for source_image in incoming_posts:
    instagram = edit_image(source_image, "Bright airy Instagram aesthetic")
    tiktok = edit_image(source_image, "High-energy saturated TikTok look")
    linkedin = edit_image(source_image, "Clean corporate LinkedIn tones")
    publish_to_platforms(instagram, tiktok, linkedin)

Veja o guia de redes sociais.

Monitoramento de custos

Cada chamada à API deduz 1 créditos. Acompanhe seus gastos de forma programática:

def get_credit_balance():
    response = requests.get(
        "https://api.arteza.ai/v1/account/credits",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    return response.json()["balance"]

print(f"Créditos restantes: {get_credit_balance()}")

Preços

Os créditos mensais são renovados a cada ciclo de cobrança. Os créditos de recarga nunca expiram. Preços completos.

Lista de verificação para produção

• Chave de API armazenada com segurança (variável de ambiente ou gerenciador de segredos)
• Lógica de retry com backoff exponencial
• Registro e alertas de erros
• Monitoramento do saldo de créditos
• Concorrência respeitando os limites de taxa
• Validação do tamanho da imagem de entrada (<2048px)
• Armazenamento de saída (CDN, S3 etc.)
• Templates de prompts versionados no git

Próximos passos

• Guia completo do Seedream 5.0 Edit
• Fluxos de trabalho para fotografia de produtos
• Automação para imóveis
• Criando variações em escala

Obtenha sua chave de API grátis → - créditos gratuitos ao criar conta, sem necessidade de cartão.