API Seedream 5.0 Lite: endpoint de geração de imagens mais rápido

API REST, autenticação Bearer, geração assíncrona, webhooks, agrupamento nativo de até 50 imagens por requisição. Tudo disponível na interface web da Arteza também está na API. Confira a referência completa com exemplos funcionais em Python e JavaScript que você pode copiar diretamente para produção hoje.

Resumo rápido

• POST /v1/images/generate - endpoint para imagem única
• POST /v1/images/batch - até 50 imagens por requisição
• Latência média de 5-15 segundos com suporte a async e webhook
• SDKs para Python e JavaScript disponíveis (seedance / @seedance/sdk)
• Autenticação por token Bearer - gere chaves em Configurações > Chaves de API

Visão geral da API

A API do Seedream 5.0 Lite oferece acesso programático ao pipeline de geração de imagens na plataforma Arteza. Tudo que está na interface web, incluindo texto para imagem, raciocínio profundo, transferência de estilo e renderização de texto, também está disponível na API REST.

A API segue as convenções REST com corpos de requisição e resposta em JSON. A geração é assíncrona: envie uma requisição, receba um ID de tarefa e, em seguida, faça polling ou aguarde um webhook ao concluir.

Veja a visão geral completa dos recursos em nossa guia completo.

URL base

https://api.arteza.ai/v1

Características principais

Autenticação

Autenticação por token Bearer. Gere sua chave de API no painel da Arteza em Configurações > Chaves de API.

Como obter sua chave de API

1. Cadastre-se ou faça login na sua conta Arteza
2. Acesse Configurações > Chaves de API
3. Clique em Gerar nova chave
4. Copie e armazene sua chave com segurança (exibida apenas uma vez)

Cabeçalho de autenticação

Authorization: Bearer YOUR_API_KEY

Testando a autenticação

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.arteza.ai/v1/account/credits

Resposta:

{
  "credits_remaining": 1050,
  "tier": "starter"
}

Endpoint de imagem única

POST /v1/images/generate

Requisição mínima

{
  "model": "seedream-5.0-lite",
  "prompt": "A serene mountain landscape at sunrise"
}

Requisição completa

{
  "model": "seedream-5.0-lite",
  "prompt": "Professional YouTube thumbnail with text 'TOP 10 TIPS' in bold red font, excited person on left, bright blue background",
  "aspect_ratio": "16:9",
  "deep_thinking": true,
  "style": "photorealistic",
  "webhook_url": "https://your-app.com/webhook/image-complete",
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  }
}

Resposta

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "credits_remaining": 1043,
  "estimated_time_seconds": 10
}

Parâmetros da requisição

Proporções de aspecto

Predefinições de estilo

Formato de resposta

Consultando os resultados

GET /v1/images/{task_id}

Em processamento:

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "progress": 0.65,
  "estimated_time_remaining": 5
}

Concluído:

{
  "task_id": "img_abc123def456",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "image_url_webp": "https://cdn.arteza.ai/generated/img_abc123def456.webp",
  "width": 1024,
  "height": 1024,
  "model": "seedream-5.0-lite",
  "deep_thinking_used": true,
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Expiração da URL da imagem

As URLs das imagens geradas são válidas por 24 horas. Faça o download e armazene as imagens no seu próprio storage dentro desse período.

Quer um texto tão preciso quanto esse? Experimente o Seedream 5.0 Lite gratuitamente →

Exemplo em Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.arteza.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Enviar requisição de geração
response = requests.post(
    f"{BASE_URL}/images/generate",
    headers=headers,
    json={
        "model": "seedream-5.0-lite",
        "prompt": "A futuristic city skyline at sunset with flying cars",
        "aspect_ratio": "16:9",
        "deep_thinking": True
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Tarefa enviada: {task_id}")
print(f"Créditos cobrados: {task['credits_charged']}")
print(f"Créditos restantes: {task['credits_remaining']}")

# Polling para verificar conclusão
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Imagem pronta: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Falha na geração: {result.get('error', 'Erro desconhecido')}")
        break

    time.sleep(2)

Exemplo em JavaScript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.arteza.ai/v1';

async function generateImage(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/images/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedream-5.0-lite',
      prompt,
      aspect_ratio: options.aspectRatio || '1:1',
      deep_thinking: options.deepThinking || false,
      ...options
    })
  });

  const task = await response.json();
  console.log(`Tarefa enviada: ${task.task_id}`);

  while (true) {
    const result = await fetch(
      `${BASE_URL}/images/${task.task_id}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    ).then(r => r.json());

    if (result.status === 'completed') {
      return result;
    }
    if (result.status === 'failed') {
      throw new Error(result.error || 'Falha na geração');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Uso
const result = await generateImage(
  'A cozy coffee shop interior with warm lighting',
  { aspectRatio: '16:9', deepThinking: true }
);
console.log(`URL da imagem: ${result.image_url}`);

Fazendo download das imagens geradas

import requests

def download_image(image_url, filename):
    response = requests.get(image_url)
    with open(filename, 'wb') as f:
        f.write(response.content)
    print(f"Salvo: {filename}")

download_image(result['image_url'], 'output/my_image.png')

Endpoint de geração em lote

Para várias imagens em uma única requisição:

POST /v1/images/batch

Requisição em lote

{
  "generations": [
    {
      "prompt": "Minimalist logo design, blue circle with lightning bolt",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": true
    },
    {
      "prompt": "Professional headshot background, soft gradient",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": false
    },
    {
      "prompt": "YouTube thumbnail with text 'MUST WATCH' in red",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "16:9",
      "deep_thinking": true
    }
  ],
  "webhook_url": "https://your-app.com/webhook/batch-complete"
}

Resposta do lote

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_generations": 3,
  "total_credits_charged": 21,
  "credits_remaining": 1029
}

Consultando o status do lote

GET /v1/images/batch/{batch_id}

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "task_id": "img_001",
      "image_url": "https://cdn.arteza.ai/generated/img_001.png"
    },
    {
      "index": 1,
      "status": "completed",
      "task_id": "img_002",
      "image_url": "https://cdn.arteza.ai/generated/img_002.png"
    },
    {
      "index": 2,
      "status": "completed",
      "task_id": "img_003",
      "image_url": "https://cdn.arteza.ai/generated/img_003.png"
    }
  ]
}

Limites do lote

Para fluxos de trabalho em lote, consulte nossa guia de geração em massa.

Integração com webhooks

Os webhooks eliminam a necessidade de polling. Quando a geração é concluída, a API envia um POST para a sua URL.

Payload do webhook

{
  "event": "image.completed",
  "task_id": "img_abc123def456",
  "batch_id": "batch_xyz789",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Exemplo de handler (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/image-complete', methods=['POST'])
def handle_image_webhook():
    data = request.json

    if data['event'] == 'image.completed':
        task_id = data['task_id']
        image_url = data['image_url']
        metadata = data.get('metadata', {})

        # Fazer download da imagem
        img_response = requests.get(image_url)
        filename = f"images/{metadata.get('project', 'default')}/{task_id}.png"
        with open(filename, 'wb') as f:
            f.write(img_response.content)

        # Atualizar o banco de dados
        update_generation_record(task_id, filename)

        print(f"Imagem salva: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Falha na geração: {data.get('error')}")

    return jsonify({'status': 'ok'}), 200

Segurança do webhook

Verifique a autenticidade do webhook pelo cabeçalho X-Seedance-Signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Modo de raciocínio profundo

Controlado pelo parâmetro booleano deep_thinking. Quando ativado, o modelo realiza um raciocínio adicional antes da geração.

Quando ativar

Impacto no desempenho

O raciocínio profundo adiciona aproximadamente 3-5 segundos, mas não consome créditos extras.

Tratamento de erros

Formato de resposta de erro

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation. Required: 7, Available: 3",
    "status": 402
  }
}

Códigos de erro

Estratégia de nova tentativa

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/images/generate",
                headers=headers,
                json={
                    "model": "seedream-5.0-lite",
                    "prompt": prompt
                }
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Backoff exponencial

Limites de taxa e boas práticas

Limites de taxa por plano

Boas práticas

1. Use webhooks em vez de polling - mais eficiente
2. Use lotes sempre que possível - uma requisição em lote supera 50 requisições individuais
3. Backoff exponencial - lide com limites de taxa de forma adequada
4. Armazene os resultados em cache - salve URLs de imagens e metadados no seu banco de dados
5. Faça o download rapidamente - as URLs das imagens expiram após 24 horas
6. Monitore o saldo de créditos - verifique credits_remaining para evitar interrupções
7. Use metadados - marque as gerações com IDs de projeto para rastreamento
8. Trate erros adequadamente - nem toda geração é bem-sucedida

Instalação do SDK

Python:

pip install seedance

from seedance import SeedanceClient

client = SeedanceClient(api_key="your_key")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A beautiful sunset",
    deep_thinking=True
)

JavaScript:

npm install @seedance/sdk

import { SeedanceClient } from '@seedance/sdk';

const client = new SeedanceClient({ apiKey: 'your_key' });
const result = await client.images.generate({
    model: 'seedream-5.0-lite',
    prompt: 'A beautiful sunset',
    deepThinking: true
});

Padrões comuns de integração

Integração com CMS

Gere imagens destacadas automaticamente na criação de posts:

@app.route('/cms/webhook/new-post', methods=['POST'])
def handle_new_post():
    post = request.json

    result = generate_image(
        prompt=f"Blog header image for article about {post['title']}, "
               f"professional editorial style, 16:9",
        aspect_ratio="16:9",
        deep_thinking=True,
        metadata={"post_id": post["id"]}
    )

    update_post_featured_image(post["id"], result["image_url"])

Imagens de produtos para e-commerce

def generate_product_images(product):
    prompts = [
        f"Product photo of {product.name}, white background, studio lighting, 1:1",
        f"Lifestyle photo of {product.name} in use, natural setting, 16:9",
        f"Product detail close-up of {product.name}, macro photography, 1:1"
    ]

    batch = client.images.batch_generate(
        generations=[
            {"model": "seedream-5.0-lite", "prompt": p}
            for p in prompts
        ]
    )

    return batch

Automação de redes sociais

def generate_weekly_social_content(brand, topics):
    generations = []
    for topic in topics:
        generations.append({
            "model": "seedream-5.0-lite",
            "prompt": f"{brand.style_prefix} {topic}, social media post, 1:1",
            "aspect_ratio": "1:1",
            "deep_thinking": True,
            "metadata": {"topic": topic, "platform": "instagram"}
        })

    return client.images.batch_generate(generations=generations)

---

A API do Seedream 5.0 Lite é o caminho mais rápido do prompt de texto à imagem gerada, com suporte completo para raciocínio profundo, geração em lote e integração via webhook.

Obtenha sua chave de API → - 10 créditos gratuitos, gere sua chave em Configurações > Chaves de API e comece a desenvolver em minutos.