Seedance 2.0 API: Como Gerar Vídeos com IA Programaticamente

Gere um vídeo de IA cinemático com uma solicitação HTTP. A API Seedance 2.0 usa o mesmo pipeline de geração que a plataforma web, exposto como uma interface REST limpa com autenticação Bearer, webhooks e endpoints de lote. Se você consegue fazer uma solicitação POST, você consegue construir um pipeline de geração de vídeo.

Este guia cobre tudo que você precisa para integrar o Seedance 2.0 em 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.

TL;DR - API em uma Visão Geral

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

O Que a API Realmente Consegue Fazer

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 aspecto, alternâncias de áudio e acesso a cada modelo na plataforma. Endpoints de lote para gerar muitos clipes de uma vez. Notificações webhook para que você não tenha que fazer polling. Metadados personalizados que são ecoados nos resultados para rastrear testes A/B ou variantes de campanha.

Modelos Suportados

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 um 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 coloque sua chave de API em código no lado do cliente ou em repositórios públicos
• Armazene-a em variáveis de ambiente (SEEDANCE_API_KEY)
• Rotacione as chaves periodicamente no painel
• Cada chave herda o saldo de créditos de sua conta pai

O Endpoint Texto para Vídeo

Este é o endpoint que você usará mais.

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 Bem-Sucedida

{
  "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 faz polling para conclusão (ou usa webhooks).

O Endpoint 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 uma 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

Faça polling do endpoint de tarefas para verificar o progresso.

GET /v1/tasks/{task_id}

Resposta em Progresso

{
  "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 Concluída

{
  "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

URLs de vídeos expiram em 24 horas. Baixe e armazene-os em sua própria infraestrutura prontamente.

Quer gerar saída como esta programaticamente? Você está a 30 segundos de sua primeira chamada de API. Obtenha sua chave de API gratuitamente →

Exemplo Python Pronto para Produção

Aqui está um script completo que envia uma geração, faz polling para conclusão e baixa o 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"):
    """Submit a text-to-video task. Returns 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):
    """Poll until the task finishes. Returns result dict."""
    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):
    """Stream the video to disk."""
    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 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`);
}

// Usage
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 você precisa fazer upload de uma imagem de origem, use multipart/form-data:

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Generate video from a local image file."""
    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 Falha

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

Forma de Resposta de Erro

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

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']}")
        # Redirect the user to /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 Taxa e Melhores Práticas de Produção

Os Limites

Cinco Práticas Que Importam em Produção

1. Use webhooks, não polling, em escala. Polling desperdiça chamadas de API. Webhooks acionam exatamente uma vez.
2. Implemente backoff exponencial em respostas 429. Não tente novamente imediatamente.
3. Baixe URLs de vídeos prontamente. Elas expiram em 24 horas. Armazene-as em seu próprio CDN.
4. Valide entradas no lado do cliente. Verifique comprimento de prompt e tamanho de arquivo antes de acessar a API.
5. Verifique saldo de créditos antes de trabalhos em lote. Um 402 no meio de um lote é incômodo. Consulte /account/credits primeiro.

Integração com Webhook

Inclua webhook_url em sua solicitação de geração e a Arteza fará POST nela 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 solicitações de webhook incluem um cabeçalho X-Seedance-Signature - uma assinatura HMAC-SHA256 do corpo assinada com seu segredo de webhook. Sempre verifique a assinatura antes de processar eventos.

Geração em Lote

Quando você precisa de múltiplos clipes, envie-os como um lote e receba um 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 em um lote são processadas simultaneamente até seu limite de concorrência.

Quatro Casos de Uso Que Vale a Pena Construir

1. Vídeos de Produtos de E-commerce em Escala

Automatize a animação de produtos para todo o seu catálogo. Faça loop sobre seu banco de dados de produtos, acione uma chamada de imagem para vídeo por item, armazene as URLs resultantes junto com o 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 guia de vídeo de e-commerce para dicas de fluxo de trabalho.

2. Pipelines Automatizadas de Mídia Social

Alimente tópicos em tendência em geradores de prompts, gere vídeos verticais diários, 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. Teste A/B de Marketing

Gere múltiplas variantes criativas com rastreamento de 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 é ecoado no payload de conclusão, então você pode rotear resultados para o bucket de campanha correto automaticamente.

4. Aplicações Interativas

Construa a geração de vídeo diretamente em seu próprio aplicativo. Um usuário digita um prompt, seu backend chama a API, o webhook fornece o clipe concluído. O loop inteiro leva ~90 segundos.

O Essencial

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

Para precificação e otimização de créditos, veja guia de preços. Para uma visão geral mais ampla do produto, leia 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