API Seedream v4.5: Integre Imagens de IA em Seu Aplicativo

Integrar geração de imagens AI no seu app costumava significar escolher entre três opções ruins: rodar Stable Diffusion você mesmo (infraestrutura cara), pagar taxas por token do OpenAI (custos imprevisíveis) ou se comprometer com uma API de assinatura (capacidade desperdiçada). A API Seedream v4.5 foi construída diferente - pague por imagem a $0.08, REST padrão e tempos de resposta medidos em segundos. Este guia o leva do zero à primeira geração em menos de 10 minutos.

Resumo Executivo

• API Seedream v4.5 custa 8 créditos (~$0.08) por imagem gerada
• API REST padrão com requisições e respostas JSON
• Parâmetros: prompt, resolução, proporção de aspecto, num_images (1-6), escala de orientação
• Tempo de resposta típico: 5-15 segundos por geração
• Sem mínimo de assinatura - pague apenas pelo que gera

Para o que a API é Boa

A API Seedream v4.5 se adequa a aplicações que precisam de geração de imagens AI sob demanda com custos previsíveis por imagem. Casos de uso comuns:

Produtos SaaS que deixam usuários gerar imagens como parte do seu workflow - ferramentas de design, plataformas de marketing, apps de criação de conteúdo.

Plataformas de e-commerce gerando imagens lifestyle de produtos ou cabeçalhos de categoria programaticamente.

Ferramentas de automação de marketing produzindo visuals de campanha baseados em entradas estruturadas.

Sistemas de gestão de conteúdo oferecendo geração de imagens AI como uma funcionalidade nativa.

Projetos de desenvolvedor e scripts de automação para qualquer workflow que precise de geração de imagens em escala.

Aplicativos móveis que chamam a API de um serviço backend para manter a geração de imagens fora do dispositivo.

Se seu caso de uso corresponde a algum destes, este guia o integrará rapidamente.

Autenticação e Começando

Passo 1: Obtenha uma Chave de API

Inscrever-se para uma conta Arteza se você não tiver uma. Navegue até as configurações da sua conta e gere uma chave de API. Trate esta chave como uma senha - não a commite em repositórios públicos.

Passo 2: Adicione Créditos à Sua Conta

O uso da API é extraído do mesmo saldo de créditos que o uso web. Seus 50 créditos grátis de cadastro funcionam em chamadas de API. Para uso em produção, faça uma assinatura a partir de página de preços começando em $10.

Passo 3: Faça Sua Primeira Requisição

O endpoint da API para Seedream v4.5 é:

POST https://api.arteza.ai/v1/images/generate

Corpo da requisição mínimo:

{
  "model": "seedream-v4-5",
  "prompt": "Uma livraria aconchegante ao anoitecer, luz quente da janela",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

Inclua sua chave de API no cabeçalho de Autorização:

Authorization: Bearer SUA_CHAVE_API

Referência Completa de Parâmetros

Resoluções Suportadas

Seedream v4.5 suporta múltiplas opções de resolução até 4 megapixels:

Exemplos de Código

Node.js (Fetch)

const generateImage = async (prompt) => {
  const response = await fetch(
    'https://api.arteza.ai/v1/images/generate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SEEDANCE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'seedream-v4-5',
        prompt: prompt,
        width: 2048,
        height: 2048,
        num_images: 1,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data.images[0].url;
};

// Uso
const imageUrl = await generateImage(
  'Uma livraria aconchegante ao anoitecer, luz quente da janela, fotografia editorial'
);
console.log(imageUrl);

Python (Requests)

import os
import requests

def generate_image(prompt, width=2048, height=2048, num_images=1):
    response = requests.post(
        'https://api.arteza.ai/v1/images/generate',
        headers={
            'Authorization': f'Bearer {os.environ["SEEDANCE_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'seedream-v4-5',
            'prompt': prompt,
            'width': width,
            'height': height,
            'num_images': num_images,
        },
    )
    response.raise_for_status()
    data = response.json()
    return [img['url'] for img in data['images']]

# Uso
urls = generate_image(
    'Uma fotografia de produto editorial de uma caneca de cerâmica, '
    'luz quente da manhã, composição minimalista'
)
print(urls)

cURL

curl -X POST https://api.arteza.ai/v1/images/generate \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-5",
    "prompt": "Um horizonte futurista de cidade ao pôr do sol, fotografia cinematográfica",
    "width": 2048,
    "height": 1152,
    "num_images": 1
  }'

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type GenerateRequest struct {
    Model     string `json:"model"`
    Prompt    string `json:"prompt"`
    Width     int    `json:"width"`
    Height    int    `json:"height"`
    NumImages int    `json:"num_images"`
}

func generateImage(prompt string) (string, error) {
    reqBody := GenerateRequest{
        Model:     "seedream-v4-5",
        Prompt:    prompt,
        Width:     2048,
        Height:    2048,
        NumImages: 1,
    }

    jsonData, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest(
        "POST",
        "https://api.arteza.ai/v1/images/generate",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SEEDANCE_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    images := result["images"].([]interface{})
    firstImage := images[0].(map[string]interface{})
    return firstImage["url"].(string), nil
}

Formato de Resposta

Respostas bem-sucedidas retornam JSON com esta estrutura:

{
  "id": "gen_abc123xyz",
  "model": "seedream-v4-5",
  "created": 1712764800,
  "images": [
    {
      "url": "https://cdn.arteza.ai/gen/abc123.png",
      "width": 2048,
      "height": 2048,
      "seed": 42871
    }
  ],
  "credits_used": 8,
  "credits_remaining": 1042
}

URLs de imagem são válidas por 24 horas. Baixe e armazene imagens imediatamente se você precisar de acesso permanente.

Quer detalhes assim? Experimente Seedream v4.5 gratuitamente →

Pronto para começar a integrar? Obtenha sua chave de API →

Tratamento de Erros

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

Exemplo de resposta de erro:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Sua conta tem créditos insuficientes para esta requisição",
    "credits_required": 8,
    "credits_available": 3
  }
}

Sempre implemente tratamento de erro e retentativas para erros 429 e 500. Não tente novamente erros 400 e 401 - esses exigem corrigir a requisição em si.

Melhores Práticas para Uso em Produção

Rate Limiting

Limites de taxa padrão permitem throughput razoável de produção. Se você precisar de limites mais altos, entre em contato com o suporte com detalhes do seu caso de uso.

Implemente backoff exponencial em erros 429:

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return generate_image(prompt)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Max retries exceeded")

Gestão de Créditos

Monitore o campo credits_remaining em cada resposta. Configure alertas quando o saldo cai abaixo de um limite para que você possa recarregar antes do tráfego de produção atingir créditos zero.

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Aviso de crédito baixo: {remaining} créditos')

Tratamento Assíncrono

Para aplicações voltadas ao usuário, trate geração de imagens como assíncrona. Não bloqueie a thread da UI em uma chamada de API de 5-15 segundos. Padrões:

• Retorne um ID de job imediatamente, faça polling para conclusão
• Use webhooks (se suportado) para notificações de conclusão
• Gere especulativamente em background e cache resultados

Cache

Imagens geradas são determinísticas dado o mesmo prompt e seed. Faça cache agressivamente por hash de prompt para evitar regenerar imagens idênticas.

import hashlib

def prompt_cache_key(prompt, width, height, seed):
    raw = f'{prompt}|{width}x{height}|{seed}'
    return hashlib.sha256(raw.encode()).hexdigest()

Segurança de Prompt

Se seu app expõe prompts para usuários finais, implemente filtro de conteúdo antes de enviar à API. Arteza tem políticas de conteúdo - prompts que as violam retornarão erros, desperdiçando créditos e criando falhas voltadas ao usuário.

Preços para Uso da API

O uso da API é extraído do saldo de créditos da sua conta na mesma taxa que o uso web.

Créditos vêm do mesmo níveis de preços independentemente de você usá-los via web ou API:

• Starter: $10 = 1.050 créditos = ~131 imagens
• Popular: $25 = 2.750 créditos = ~343 imagens
• Creator: $50 = 5.750 créditos = ~718 imagens
• Studio: $100 = 12.000 créditos = ~1.500 imagens

Clientes com volume maior podem contatar o suporte sobre preços de volume para uso sustentado acima de 100.000 imagens/mês.

Combinando com Outros Modelos Arteza

Sua aplicação pode usar múltiplos modelos Seedance através da mesma API alterando o parâmetro model:

• seedream-v4-5 - 8 créditos - qualidade flagship
• seedream-v3 - 6 créditos - mais rápido, mais simples
• seedream-5-lite - 7 créditos - modo pensamento profundo
• seedream-5-edit - 7 créditos - edição de imagem
• seedance-2 - geração de vídeo (endpoint diferente)

Para aplicações que precisam de capacidades de edição além de geração, seedream-5-edit lida com edição de imagem baseada em texto. Veja a documentação do Seedream 5 Edit para detalhes.

Considerações de Segurança

Nunca exponha chaves de API no lado do cliente. Sempre roteie chamadas de API através do seu backend. Chaves expostas podem ser usadas para drenar seu saldo de créditos.

Rotacione chaves periodicamente. Se uma chave for comprometida, revogue-a e gere uma nova.

Registre requisições para debug. Inclua IDs de requisição nos seus logs para que você possa correlacionar falhas com respostas da API.

Implemente quotas de uso por usuário. Se seu app oferece geração AI como uma funcionalidade, limite consumo por usuário para evitar abuso.

Perguntas Frequentes

Há um nível gratuito para a API? Seus 50 créditos de cadastro funcionam em chamadas de API. Isso é 6 gerações gratuitas de Seedream v4.5 para testar integração antes de pagar.

Qual é o tempo de resposta típico? 5-15 segundos para Seedream v4.5 dependendo de resolução e carga atual.

Posso usar a API para produtos comerciais? Sim. Uso comercial é incluído. As imagens geradas pelos seus clientes são deles para usar para qualquer propósito legítimo.

Há um SDK Python? SDKs oficiais estão em desenvolvimento. A API REST atual funciona limpamente com bibliotecas HTTP padrão em qualquer linguagem.

Como eu lido com erros de política de conteúdo? Implemente mensagens voltadas ao usuário que expliquem que o prompt foi rejeitado. Registre o erro específico para debug.

O que acontece se meus créditos acabarem no meio de uma requisição? A API retorna um erro 402 antes da geração começar. Cobranças parciais nunca ocorrem - você obtém a imagem completa ou obtém um erro.

Posso fazer batch de múltiplos prompts em uma requisição? Não diretamente. Use num_images: 6 para obter variações do mesmo prompt, ou faça chamadas de API paralelas para prompts diferentes.

---

A API Seedream v4.5 fornece geração de imagens AI pronta para produção a preços previsíveis por imagem com convenções REST padrão. Para a maioria das integrações, você pode ir de chave de API a primeira geração funcionando em menos de 10 minutos. Para questões ou preços de volume, entre em contato através do seu dashboard de conta.

Comece a integrar hoje. Obtenha sua chave de API → | Ver preços completos → | Leia o guia v4.5 →