API do Seedream v4.5: integre imagens de IA ao seu aplicativo

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

Resumo rápido

• A API do Seedream v4.5 custa 1 créditos ($0,10) por imagem gerada
• API REST padrão com requisições e respostas em JSON
• Parâmetros: prompt, resolução, proporção, num_images (1-6), escala de orientação
• Tempo de resposta típico: 5-15 segundos por geração
• Planos a partir de $5 por mês: créditos só são consumidos quando você gera

Para que a API é indicada

A API do Seedream v4.5 é ideal para aplicações que precisam de geração de imagens com IA sob demanda e custos previsíveis por imagem. Casos de uso comuns:

Produtos SaaS que permitem aos usuários gerar imagens como parte do fluxo de trabalho: ferramentas de design, plataformas de marketing, apps de criação de conteúdo.

Plataformas de e-commerce que geram imagens de lifestyle de produtos ou cabeçalhos de categoria de forma programática.

Ferramentas de automação de marketing que produzem visuais de campanha com base em entradas estruturadas.

Sistemas de gerenciamento de conteúdo que oferecem geração de imagens com IA como recurso nativo.

Projetos de desenvolvedores e scripts de automação para qualquer fluxo de trabalho que precise de geração de imagens em escala.

Apps mobile que chamam a API a partir de um serviço de backend para manter a geração de imagens fora do dispositivo.

Se o seu caso de uso se encaixa em algum desses, este guia vai te ajudar a integrar rapidamente.

Autenticação e primeiros passos

Passo 1: Obtenha uma chave de API

Criar conta para criar uma conta na Arteza, caso ainda não tenha. Acesse as configurações da sua conta e gere uma chave de API. Trate essa chave como uma senha: não a inclua em repositórios públicos.

Passo 2: Adicione créditos à sua conta

O uso da API consome o mesmo saldo de créditos que o uso via web. Seus 10 créditos gratuitos de cadastro funcionam nas chamadas de API. Para uso em produção, assine um plano a partir do página de preços por $5.

Passo 3: Faça sua primeira requisição

O endpoint da API para o Seedream v4.5 é:

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

Corpo mínimo da requisição:

{
  "model": "seedream-v4-5",
  "prompt": "A cozy bookstore at dusk, warm window light",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

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

Authorization: Bearer YOUR_API_KEY

Referência completa de parâmetros

Resoluções suportadas

O Seedream v4.5 suporta múltiplas opções de resolução de 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(`Erro na API: ${response.status}`);
  }

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

// Uso
const imageUrl = await generateImage(
  'A cozy bookstore at dusk, warm window light, editorial photography'
);
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(
    'An editorial product photograph of a ceramic coffee mug, '
    'warm morning light, minimalist composition'
)
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": "A futuristic city skyline at sunset, cinematic photography",
    "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 da resposta

As 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
}

Os URLs das imagens são válidos por 24 horas. Baixe e armazene as imagens imediatamente se precisar de acesso permanente.

Quer detalhes como estes? Experimente o Seedream v4.5 grátis →

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 não tem créditos suficientes para esta requisição",
    "credits_required": 8,
    "credits_available": 3
  }
}

Sempre implemente tratamento de erros e novas tentativas para erros 429 e 500. Não tente novamente para erros 400 e 401: eles exigem a correção da própria requisição.

Boas práticas para uso em produção

Limite de taxa

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

Implemente recuo 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("Número máximo de tentativas excedido")

Gerenciamento de créditos

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

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

Tratamento assíncrono

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

• Retorne um ID de trabalho imediatamente e consulte o status periodicamente
• Use webhooks (se disponíveis) para notificações de conclusão
• Gere especulativamente em segundo plano e armazene os resultados em cache

Cache

As imagens geradas são determinísticas dado o mesmo prompt e semente. Faça cache agressivamente por hash do 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 nos prompts

Se o seu app expõe prompts aos usuários finais, implemente filtragem de conteúdo antes de enviar para a API. A Arteza possui políticas de conteúdo: prompts que as violarem retornarão erros, desperdiçando créditos e gerando falhas visíveis ao usuário.

Preços para uso via API

O uso da API consome o saldo de créditos da sua conta à mesma taxa que o uso via web.

Os créditos vêm do mesmo níveis de preços, independentemente de você os usar via web ou API:

• Starter: $5 = 60 créditos por mês = 60 imagens
• Creator: $25 = 300 créditos por mês = 300 imagens
• Pro: $50 = 700 créditos por mês = 700 imagens
• Studio: $120 = 1.800 créditos por mês = 1.800 imagens

Clientes com volume maior podem entrar em contato com o suporte para discutir preços por volume para uso acima de 100.000 imagens/mês.

Combinando com outros modelos da Arteza

Sua aplicação pode usar múltiplos modelos Seedance pela mesma API, alterando o parâmetro model:

• seedream-v4-5 - 1 créditos - qualidade premium
• seedream-v3 - 1 crédito - mais rápido e simples
• seedream-5-lite - 1 crédito - modo de raciocínio profundo
• seedream-5-edit - 1 crédito - edição de imagens
• seedance-2 - geração de vídeo (endpoint diferente)

Para aplicações que precisam de capacidades de edição além da geração, o seedream-5-edit trata da edição de imagens baseada em texto. Consulte o Documentação do Seedream 5 Edit para mais detalhes.

Considerações de segurança

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

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

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

Implemente cotas de uso por usuário. Se o seu app oferece geração com IA como funcionalidade, limite o consumo por usuário para evitar abusos.

Perguntas frequentes

Existe um plano gratuito para a API? Seus 10 créditos gratuitos de cadastro funcionam nas chamadas de API. Isso equivale a 10 gerações gratuitas com o Seedream v4.5 para testar a integração antes de pagar.

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

Posso usar a API em produtos comerciais? Sim. O uso comercial está incluído. As imagens geradas pelos seus clientes são deles e podem ser usadas para qualquer finalidade legítima.

Existe um SDK para Python? SDKs oficiais estão em desenvolvimento. A API REST atual funciona perfeitamente com bibliotecas HTTP padrão em qualquer linguagem.

Como lidar com erros de política de conteúdo? Implemente mensagens para o usuário explicando que o prompt foi rejeitado. Registre o erro específico para depuração.

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

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

---

A API do Seedream v4.5 oferece geração de imagens com IA pronta para produção com preços previsíveis por imagem e convenções REST padrão. Para a maioria das integrações, você pode ir da chave de API à primeira geração em funcionamento em menos de 10 minutos. Para dúvidas ou preços por volume, entre em contato pelo painel da sua conta.

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