API Seedance 2.0: como gerar vídeos com IA de forma programática

Gere um vídeo de IA cinematográfico com uma única requisição HTTP. A API do Seedance 2.0 é o mesmo pipeline de geração usado pela plataforma web, exposto como uma interface REST limpa com autenticação Bearer, webhooks e endpoints em lote. Se você consegue fazer uma requisição POST, consegue construir um pipeline de geração de vídeo.

Este guia cobre tudo o que você precisa para integrar o Seedance 2.0 às suas próprias aplicações: autenticação, endpoints, parâmetros, tratamento de erros e exemplos de código prontos para produção em Python e JavaScript.

Resumo rápido - visão geral da API

• URL base: https://api.arteza.ai/v1
• Autenticação: Token Bearer no cabeçalho Authorization
• Geração: Assíncrona - envie uma tarefa, monitore ou use webhook para receber a conclusão
• Limites de requisição: 60 requisições/minuto, 5 gerações simultâneas
• Modelos: Seedance 2.0, 1.0 Pro, 1.0 Lite, Seedream v3/v4.5/v5, todos em uma única API
• Custo em créditos: O mesmo preço dinâmico por segundo da interface web (19-351 créditos para o 2.0)

O que a API realmente faz

Tudo o que a interface web faz, a API também faz. Texto para vídeo, imagem para vídeo, seleção de modelo, controle de duração, proporção de tela, alternância de áudio e acesso a todos os modelos da plataforma. Endpoints em lote para gerar vários clipes de uma vez. Notificações via webhook para que você não precise fazer polling. Metadados personalizados que são retornados nos resultados para rastrear testes A/B ou variantes de campanha.

Modelos disponíveis

Todos os modelos usam a mesma superfície de API, apenas com identificadores diferentes.

Autenticação em 30 segundos

Gere uma chave de API no painel em Configurações > Chaves de API. Envie-a como token Bearer:

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

Resposta:

{
  "credits": 2750,
  "tier": "popular"
}

Regras de segurança que importam:

• Nunca inclua sua chave de API em código client-side ou repositórios públicos
• Armazene-a em variáveis de ambiente (SEEDANCE_API_KEY)
• Faça a rotação das chaves periodicamente pelo painel
• Cada chave herda o saldo de créditos da conta principal

O endpoint de texto para vídeo

Este é o endpoint que você mais usará.

POST /v1/generate/text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Aerial shot of a coastal city at sunset, golden light reflecting off glass skyscrapers, cinematic drone footage",
  "duration": 10,
  "aspect_ratio": "16:9",
  "audio": true
}

Referência de parâmetros

Resposta de sucesso

{
  "task_id": "task_abc123def456",
  "status": "queued",
  "model": "seedance-2.0",
  "credits_charged": 607,
  "estimated_time": 120,
  "created_at": "2026-04-10T14:30:00Z"
}

A geração é assíncrona. Você recebe um task_id imediatamente e monitora a conclusão por polling ou webhooks.

O endpoint de imagem para vídeo

Anime uma imagem de origem com um prompt de movimento.

POST /v1/generate/image-to-video
Content-Type: multipart/form-data

Prefere não fazer upload de um arquivo? Passe um image_url em vez disso:

{
  "model": "seedance-2.0",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "The woman turns her head slowly and smiles, wind gently blowing her hair",
  "duration": 8,
  "aspect_ratio": "16:9"
}

Verificando o status da geração

Consulte o endpoint de tarefas para verificar o progresso.

GET /v1/tasks/{task_id}

Resposta em andamento

{
  "task_id": "task_abc123def456",
  "status": "processing",
  "progress": 65,
  "model": "seedance-2.0",
  "created_at": "2026-04-10T14:30:00Z",
  "estimated_completion": "2026-04-10T14:31:30Z"
}

Resposta de conclusão

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "seedance-2.0",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true,
    "file_size": 8542310
  },
  "credits_charged": 607,
  "created_at": "2026-04-10T14:30:00Z",
  "completed_at": "2026-04-10T14:31:28Z"
}

Valores de status

As URLs dos vídeos expiram em 24 horas. Faça o download e armazene-os na sua própria infraestrutura o quanto antes.

Quer gerar resultados como este de forma programática? Você está a 30 segundos da sua primeira chamada de API. Obtenha sua chave de API gratuitamente →

Exemplo completo em Python pronto para produção

Aqui está um script completo que envia uma geração, monitora a conclusão e faz o download do resultado.

import os
import time
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def generate_video(prompt, duration=8, aspect_ratio="16:9"):
    """Envia uma tarefa de texto para vídeo. Retorna task_id."""
    response = requests.post(
        f"{BASE_URL}/generate/text-to-video",
        headers=HEADERS,
        json={
            "model": "seedance-2.0",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            "audio": True,
        },
    )
    response.raise_for_status()
    return response.json()["task_id"]


def wait_for_completion(task_id, poll_interval=5, timeout=300):
    """Faz polling até a tarefa ser concluída. Retorna o dicionário de resultado."""
    elapsed = 0
    while elapsed < timeout:
        response = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["result"]
        if data["status"] == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


def download_video(video_url, output_path):
    """Faz o stream do vídeo para o disco."""
    response = requests.get(video_url, stream=True)
    response.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)


if __name__ == "__main__":
    task_id = generate_video(
        prompt="A cat sitting on a windowsill watching rain fall outside, cozy indoor lighting, shallow depth of field",
        duration=10,
    )
    print(f"Task submitted: {task_id}")

    result = wait_for_completion(task_id)
    print(f"Video ready: {result['video_url']}")

    download_video(result["video_url"], "output.mp4")
    print("Downloaded to output.mp4")

Exemplo em JavaScript (Node.js)

O mesmo fluxo de trabalho em Node.js moderno com fetch nativo.

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

async function generateVideo(prompt, duration = 8, aspectRatio = "16:9") {
  const response = await fetch(`${BASE_URL}/generate/text-to-video`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "seedance-2.0",
      prompt,
      duration,
      aspect_ratio: aspectRatio,
      audio: true,
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  const data = await response.json();
  return data.task_id;
}

async function waitForCompletion(taskId, pollMs = 5000, timeoutMs = 300000) {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const response = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const data = await response.json();

    if (data.status === "completed") return data.result;
    if (data.status === "failed") {
      throw new Error(`Generation failed: ${data.error}`);
    }

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

  throw new Error(`Task ${taskId} timed out`);
}

// Uso
const taskId = await generateVideo(
  "Timelapse of a flower blooming, macro lens, soft natural lighting",
  12
);
console.log(`Task submitted: ${taskId}`);

const result = await waitForCompletion(taskId);
console.log(`Video ready: ${result.video_url}`);

Imagem para vídeo em Python

Quando precisar fazer upload de uma imagem de origem, use multipart/form-data:

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Gera vídeo a partir de um arquivo de imagem local."""
    with open(image_path, "rb") as img_file:
        response = requests.post(
            f"{BASE_URL}/generate/image-to-video",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": img_file},
            data={
                "model": model,
                "prompt": prompt,
                "duration": duration,
                "aspect_ratio": "16:9",
                "audio": "true",
            },
        )
    response.raise_for_status()
    return response.json()["task_id"]

Tratamento de erros que não derruba tudo

A API usa códigos de status HTTP padrão com corpos de erro estruturados.

Formato da resposta de erro

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 8 credits but this generation requires 24 credits.",
    "required_credits": 24,
    "available_credits": 8
  }
}

Padrão recomendado

try:
    task_id = generate_video(prompt)
except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    if status == 402:
        error = e.response.json()["error"]
        print(f"Need {error['required_credits']} credits, have {error['available_credits']}")
        # Redirecionar o usuário para /pricing
    elif status == 429:
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retry after {retry_after}s.")
    else:
        raise

Limites de requisição e boas práticas em produção

Os limites

Cinco práticas que importam em produção

1. Use webhooks, não polling, em escala. O polling desperdiça chamadas de API. Os webhooks disparam exatamente uma vez.
2. Implemente backoff exponencial em respostas 429. Não tente novamente imediatamente.
3. Faça o download das URLs de vídeo o quanto antes. Elas expiram em 24 horas. Armazene-as no seu próprio CDN.
4. Valide os dados no lado do cliente. Detecte problemas com o tamanho do prompt e do arquivo antes de chamar a API.
5. Verifique o saldo de créditos antes de jobs em lote. Receber um erro 402 no meio de um lote é chato. Consulte /account/credits primeiro.

Integração com webhooks

Inclua webhook_url na sua requisição de geração e a Arteza fará um POST nessa URL quando a tarefa for concluída.

{
  "model": "seedance-2.0",
  "prompt": "...",
  "webhook_url": "https://yourapp.com/api/seedance/webhook"
}

Payload do webhook

{
  "event": "task.completed",
  "task_id": "task_abc123def456",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true
  },
  "metadata": {
    "campaign_id": "summer-2026",
    "variant": "A"
  },
  "timestamp": "2026-04-10T14:31:28Z"
}

As requisições de webhook incluem um cabeçalho X-Seedance-Signature, uma assinatura HMAC-SHA256 do corpo assinada com o seu segredo de webhook. Sempre verifique a assinatura antes de processar os eventos.

Geração em lote

Quando você precisa de vários clipes, envie-os como um lote e receba um único webhook quando tudo terminar.

POST /v1/generate/batch

{
  "tasks": [
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 1 description...",
      "duration": 8
    },
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 2 description...",
      "duration": 10
    },
    {
      "type": "image-to-video",
      "model": "seedance-1.0-pro",
      "image_url": "https://example.com/product.jpg",
      "prompt": "Slow rotation revealing product details",
      "duration": 6
    }
  ],
  "webhook_url": "https://yourapp.com/api/seedance/batch-complete"
}

As tarefas de um lote são processadas de forma simultânea até o limite de concorrência da sua conta.

Quatro casos de uso que vale a pena construir

1. Vídeos de produtos para e-commerce em escala

Automatize a animação de produtos para todo o seu catálogo. Percorra seu banco de dados de produtos, dispare uma chamada de imagem para vídeo por item e armazene as URLs resultantes junto ao registro do produto.

products = get_products_from_database()

for product in products:
    task_id = generate_from_image(
        image_path=product["hero_image"],
        prompt=f"Slow 360 rotation of {product['name']}, studio lighting, white background",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

Combine isso com o guia de vídeo para e-commerce para dicas de fluxo de trabalho.

2. Pipelines automatizados para redes sociais

Alimente tópicos em alta em geradores de prompt, gere vídeos verticais diários e envie para uma fila de revisão:

for topic in get_trending_topics():
    prompt = build_prompt(topic)
    task_id = generate_video(prompt, duration=6, aspect_ratio="9:16")
    queue_for_review(task_id, topic)

3. Testes A/B de marketing

Gere múltiplas variantes criativas com rastreamento por metadados:

variants = [
    "Product hero shot with warm lighting, luxury feel",
    "Product hero shot with bright lighting, energetic feel",
    "Product hero shot with moody lighting, premium feel",
]

for i, variant in enumerate(variants):
    generate_video(
        prompt=variant,
        duration=6,
        metadata={"variant": chr(65 + i), "campaign": "spring-launch"},
    )

O campo metadata é retornado no payload de conclusão, então você pode encaminhar os resultados automaticamente para o bucket de campanha correto.

4. Aplicações interativas

Integre a geração de vídeo diretamente no seu próprio app. O usuário digita um prompt, seu backend chama a API, o webhook entrega o clipe finalizado. O ciclo completo leva cerca de 90 segundos.

Conclusão

A API da Arteza é simples de integrar e pronta para produção. Autenticação simples, semântica REST limpa, webhooks para trabalho assíncrono e endpoints em lote para escala. Se você já usou o Stripe ou qualquer API REST moderna, vai se sentir em casa em dez minutos.

Para preços e otimização de créditos, veja o guia de preços. Para uma visão geral mais ampla do produto, leia o guia completo do Seedance 2.0.

Pronto para começar a construir? Crie sua conta gratuita →

Continue lendo: Guia completo do Seedance 2.0 • Guia de preços • Seedance 2.0 vs Seedance 1.0 • Seedance 2.0 vs Runway Gen-4