Guia da API Seedance para Desenvolvedores 2026: Integração, Endpoints e Melhores Práticas

Construir aplicações com geração de vídeo por IA requer acesso confiável à API, documentação clara e preços previsíveis. Este guia cobre tudo que os desenvolvedores precisam saber para integrar a Seedance em suas aplicações — desde autenticação e endpoints até limites de taxa, tratamento de erros e melhores práticas de produção.

O que é a API Seedance?

A API Seedance fornece acesso programático às capacidades de geração de vídeo por IA da Seedance. Os desenvolvedores podem integrar a Seedance em aplicações web, aplicativos móveis, serviços de backend e fluxos de trabalho automatizados através de uma API RESTful que aceita entradas de texto ou imagem e retorna conteúdo de vídeo gerado.

A API suporta a mesma funcionalidade principal da interface web:

• Texto para vídeo: Gere vídeo a partir de prompts de texto
• Imagem para vídeo: Anime uma imagem estática em um vídeo
• Controle de estilo: Aplique parâmetros de estilo visual via prompt
• Opções de resolução: Saída em 720p e 1080p

Primeiros Passos: Autenticação

Configuração da Chave de API

Acesse a API Seedance através do painel da sua conta:

1. Faça login em seedance.tv
2. Navegue até Configurações → API
3. Gere uma chave de API
4. Armazene a chave com segurança — ela concede acesso total à sua conta

Nunca exponha sua chave de API em código do lado do cliente. Sempre faça chamadas de API a partir do seu servidor backend.

Cabeçalhos de Autenticação

Todas as requisições à API devem incluir sua chave de API no cabeçalho de autorização:

Authorization: Bearer SUA_CHAVE_API
Content-Type: application/json

Endpoints Principais

Geração de Texto para Vídeo

POST /api/v1/generate/text-to-video

Corpo da requisição:

{
  "prompt": "Vista aérea de uma cordilheira na hora dourada, câmera lenta de drone, cinematográfico",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "style": "cinematic"
}

Resposta:

{
  "job_id": "job_abc123",
  "status": "queued",
  "estimated_completion": "2026-04-20T10:00:30Z",
  "credits_used": 10
}

A geração de vídeo é assíncrona. A resposta inclui um job_id para consultar a conclusão.

Geração de Imagem para Vídeo

POST /api/v1/generate/image-to-video

Corpo da requisição:

{
  "image_url": "https://seu-storage.com/imagem-origem.jpg",
  "prompt": "A câmera se afasta lentamente para revelar a cena completa",
  "duration": 6,
  "resolution": "1080p",
  "motion_intensity": 0.7
}

Alternativamente, faça upload da imagem diretamente:

{
  "image_base64": "DADOS_DA_IMAGEM_CODIFICADOS_EM_BASE64",
  "prompt": "...",
  "duration": 6
}

Verificação de Status do Job

GET /api/v1/jobs/{job_id}

Resposta:

{
  "job_id": "job_abc123",
  "status": "completed",
  "created_at": "2026-04-20T10:00:00Z",
  "completed_at": "2026-04-20T10:00:45Z",
  "output": {
    "video_url": "https://cdn.seedance.tv/output/job_abc123.mp4",
    "thumbnail_url": "https://cdn.seedance.tv/output/job_abc123_thumb.jpg",
    "duration": 8,
    "resolution": "1080p",
    "file_size_mb": 24.5
  }
}

Valores de status: queued → processing → completed / failed

Listar Jobs

GET /api/v1/jobs?limit=20&offset=0&status=completed

Retorna uma lista paginada de jobs de geração para sua conta.

Tratamento de Erros

Formato Padrão de Resposta de Erro

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de taxa da API excedido. Tente novamente após 60 segundos.",
    "retry_after": 60
  }
}

Códigos de Erro Comuns

Estratégia de Retry

Implemente backoff exponencial para erros que podem ser repetidos:

import time
import requests

def generate_with_retry(prompt: str, max_retries: int = 3) -> dict:
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://api.seedance.tv/v1/generate/text-to-video',
                headers={'Authorization': f'Bearer {API_KEY}'},
                json={'prompt': prompt, 'duration': 8}
            )
            if response.status_code == 429:
                retry_after = response.json().get('error', {}).get('retry_after', 60)
                time.sleep(retry_after)
                continue
            if response.status_code >= 500:
                delay = base_delay * (2 ** attempt)
                time.sleep(delay)
                continue
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay * (2 ** attempt))
    raise Exception("Máximo de tentativas excedido")

Polling para Conclusão do Job

A geração normalmente leva de 30 a 90 segundos. Implemente polling eficiente:

import time
import requests

def wait_for_completion(job_id: str, timeout: int = 300) -> dict:
    """Poll job status until complete or timeout."""
    start_time = time.time()
    poll_interval = 5  # Comece com intervalos de 5 segundos
    
    while time.time() - start_time < timeout:
        response = requests.get(
            f'https://api.seedance.tv/v1/jobs/{job_id}',
            headers={'Authorization': f'Bearer {API_KEY}'}
        )
        job = response.json()
        
        if job['status'] == 'completed':
            return job['output']
        elif job['status'] == 'failed':
            raise Exception(f"Job {job_id} falhou")
        
        # Aumente o intervalo de polling ao longo do tempo
        poll_interval = min(poll_interval * 1.5, 30)
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Job {job_id} excedeu o tempo limite de {timeout} segundos")

Limites de Taxa

Limites de Taxa do Plano Gratuito

Limites de Taxa de Produção

Limites de taxa mais altos disponíveis para aplicações de produção. Entre em contato com o suporte Seedance para aumentos nos limites de taxa empresariais.

Cabeçalhos de Limite de Taxa

As respostas da API incluem informações de limite de taxa nos cabeçalhos:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1745123456

Exemplo Completo do SDK Python

import time
import requests
from typing import Optional

class SeedanceClient:
    BASE_URL = "https://api.seedance.tv/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def generate_text_to_video(
        self,
        prompt: str,
        duration: int = 8,
        resolution: str = "1080p",
        aspect_ratio: str = "16:9"
    ) -> str:
        """Submete um job de geração de texto para vídeo. Retorna job_id."""
        response = self.session.post(
            f"{self.BASE_URL}/generate/text-to-video",
            json={
                "prompt": prompt,
                "duration": duration,
                "resolution": resolution,
                "aspect_ratio": aspect_ratio
            }
        )
        response.raise_for_status()
        return response.json()['job_id']
    
    def generate_image_to_video(
        self,
        image_url: str,
        prompt: str,
        duration: int = 6,
        motion_intensity: float = 0.5
    ) -> str:
        """Submete um job de geração de imagem para vídeo. Retorna job_id."""
        response = self.session.post(
            f"{self.BASE_URL}/generate/image-to-video",
            json={
                "image_url": image_url,
                "prompt": prompt,
                "duration": duration,
                "motion_intensity": motion_intensity
            }
        )
        response.raise_for_status()
        return response.json()['job_id']
    
    def wait_for_job(self, job_id: str, timeout: int = 300) -> dict:
        """Poll até o job ser concluído. Retorna dicionário de saída."""
        start = time.time()
        interval = 5
        
        while time.time() - start < timeout:
            response = self.session.get(f"{self.BASE_URL}/jobs/{job_id}")
            response.raise_for_status()
            job = response.json()
            
            if job['status'] == 'completed':
                return job['output']
            elif job['status'] == 'failed':
                raise Exception(f"Job falhou: {job_id}")
            
            interval = min(interval * 1.2, 20)
            time.sleep(interval)
        
        raise TimeoutError(f"Job excedeu tempo limite: {job_id}")
    
    def create_video(
        self,
        prompt: str,
        duration: int = 8,
        resolution: str = "1080p"
    ) -> dict:
        """Fim a fim: submete job, aguarda conclusão, retorna saída."""
        job_id = self.generate_text_to_video(prompt, duration, resolution)
        return self.wait_for_job(job_id)


# Exemplo de uso
client = SeedanceClient(api_key="sua_chave_api_aqui")

output = client.create_video(
    prompt="Relógio de luxo em superfície de mármore, iluminação dramática, rotação lenta, cinematográfico",
    duration=8,
    resolution="1080p"
)

print(f"URL do vídeo: {output['video_url']}")
print(f"Duração: {output['duration']}s")
print(f"Tamanho do arquivo: {output['file_size_mb']}MB")

Exemplo Node.js / TypeScript

interface GenerateOptions {
  prompt: string;
  duration?: number;
  resolution?: '720p' | '1080p';
  aspectRatio?: '16:9' | '9:16' | '1:1';
}

interface JobOutput {
  videoUrl: string;
  thumbnailUrl: string;
  duration: number;
  fileSizeMb: number;
}

class SeedanceClient {
  private baseUrl = 'https://api.seedance.tv/v1';
  private headers: Record<string, string>;

  constructor(apiKey: string) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    };
  }

  async generateVideo(options: GenerateOptions): Promise<string> {
    const response = await fetch(`${this.baseUrl}/generate/text-to-video`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        prompt: options.prompt,
        duration: options.duration ?? 8,
        resolution: options.resolution ?? '1080p',
        aspect_ratio: options.aspectRatio ?? '16:9',
      }),
    });
    const data = await response.json();
    return data.job_id;
  }

  async waitForJob(jobId: string, timeoutMs = 300_000): Promise<JobOutput> {
    const start = Date.now();
    let interval = 5000;

    while (Date.now() - start < timeoutMs) {
      const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
        headers: this.headers,
      });
      const job = await response.json();

      if (job.status === 'completed') return job.output;
      if (job.status === 'failed') throw new Error(`Job falhou: ${jobId}`);

      interval = Math.min(interval * 1.2, 20000);
      await new Promise(r => setTimeout(r, interval));
    }
    throw new Error(`Job excedeu tempo limite: ${jobId}`);
  }

  async createVideo(options: GenerateOptions): Promise<JobOutput> {
    const jobId = await this.generateVideo(options);
    return this.waitForJob(jobId);
  }
}

// Uso
const client = new SeedanceClient(process.env.SEEDANCE_API_KEY!);
const output = await client.createVideo({
  prompt: 'Nascer do sol na montanha, câmera lenta aérea de drone, cinematográfico, hora dourada',
  duration: 8,
  resolution: '1080p',
});
console.log('Vídeo pronto:', output.videoUrl);

Integração com Webhook (Notificação Assíncrona)

Em vez de polling, registre uma URL de webhook para receber notificações de conclusão:

POST /api/v1/webhooks

{
  "url": "https://seu-app.com/webhooks/seedance",
  "events": ["job.completed", "job.failed"],
  "secret": "seu_segredo_webhook"
}

Payload do webhook (enviado para seu endpoint na conclusão):

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "timestamp": "2026-04-20T10:01:15Z",
  "output": {
    "video_url": "https://cdn.seedance.tv/output/job_abc123.mp4",
    "duration": 8,
    "resolution": "1080p"
  }
}

Verifique as assinaturas do webhook para evitar falsificação:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Melhores Práticas de Produção

1. Armazene Chaves de API com Segurança

# Use variáveis de ambiente
import os
api_key = os.environ.get('SEEDANCE_API_KEY')
if not api_key:
    raise ValueError("Variável de ambiente SEEDANCE_API_KEY não definida")

2. Implemente Fila de Requisições

Para aplicações de alto volume, implemente uma fila para respeitar os limites de taxa:

from queue import Queue
import threading

class VideoGenerationQueue:
    def __init__(self, client: SeedanceClient, max_concurrent: int = 2):
        self.client = client
        self.queue = Queue()
        self.semaphore = threading.Semaphore(max_concurrent)
    
    def submit(self, prompt: str) -> str:
        """Adiciona um job de geração à fila. Retorna job_id."""
        with self.semaphore:
            job_id = self.client.generate_text_to_video(prompt)
            return job_id

3. Armazene em Cache os Vídeos Gerados

Evite regenerar conteúdo idêntico:

import hashlib
import json
from functools import lru_cache

def get_cache_key(prompt: str, duration: int, resolution: str) -> str:
    params = json.dumps({'prompt': prompt, 'duration': duration, 'resolution': resolution}, sort_keys=True)
    return hashlib.sha256(params.encode()).hexdigest()

# Verifique o cache antes de gerar
cache_key = get_cache_key(prompt, duration, resolution)
if cached_url := video_cache.get(cache_key):
    return cached_url

# Gere e armazene em cache
output = client.create_video(prompt=prompt, duration=duration)
video_cache.set(cache_key, output['video_url'], ttl=86400)
return output['video_url']

4. Lide com Usuários Concorrentes

Para aplicações com múltiplos usuários gerando vídeos simultaneamente:

import asyncio
import aiohttp

async def generate_videos_concurrent(prompts: list[str]) -> list[dict]:
    """Gera múltiplos vídeos concorrentemente com limitação de taxa."""
    semaphore = asyncio.Semaphore(5)  # Máximo de 5 jobs simultâneos
    
    async def generate_one(prompt: str) -> dict:
        async with semaphore:
            # Submeter job
            job_id = await submit_job_async(prompt)
            # Aguardar conclusão
            return await wait_for_job_async(job_id)
    
    return await asyncio.gather(*[generate_one(p) for p in prompts])

Perguntas Frequentes

Existe um plano gratuito para a API Seedance? Sim. A Seedance oferece acesso à API no plano gratuito com limites de taxa. Para aplicações de produção que exigem maior throughput, entre em contato com a Seedance sobre planos de API de produção.

Quais formatos de vídeo a API retorna? A API retorna arquivos MP4 com codificação H.264 por padrão. A URL de saída é um link de download direto válido por 24 horas.

Por quanto tempo os vídeos gerados ficam disponíveis? As URLs dos vídeos de saída ficam disponíveis para download por 24 horas. Baixe e armazene os vídeos em seu próprio armazenamento para acesso permanente.

Posso usar vídeos gerados pela API comercialmente? Sim. O plano gratuito da Seedance inclui direitos de uso comercial. Os vídeos gerados via API estão sujeitos à mesma licença comercial que o conteúdo gerado pela web.

Qual é a duração máxima do vídeo via API? 8 segundos por geração no plano padrão. Entre em contato com a Seedance para opções de duração estendida.

Como lidar com erros em produção? Implemente retry com backoff exponencial para erros 429 e 5xx. Registre todas as falhas com job_id para depuração. Configure alertas para taxas de erro elevadas.

Comece a construir com Seedance em seedance.tv →

Padrões Avançados de Integração

Pipeline de Geração em Lote de Vídeos

Para equipes de conteúdo que precisam gerar muitos vídeos regularmente, um pipeline em lote é mais eficiente do que requisições individuais:

import csv
import time
from pathlib import Path
from dataclasses import dataclass

@dataclass
class VideoJob:
    id: str
    prompt: str
    output_filename: str
    status: str = "pending"
    video_url: str = ""

def batch_generate_from_csv(input_csv: str, output_dir: str) -> None:
    """Lê prompts de um CSV, gera vídeos, salva resultados."""
    client = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    jobs = []
    
    # Ler prompts
    with open(input_csv) as f:
        reader = csv.DictReader(f)
        for row in reader:
            jobs.append(VideoJob(
                id=row['id'],
                prompt=row['prompt'],
                output_filename=row.get('filename', f"video_{row['id']}.mp4")
            ))
    
    # Submeter todos os jobs
    pending_jobs = {}
    for job in jobs:
        try:
            job_id = client.generate_text_to_video(job.prompt)
            pending_jobs[job_id] = job
            job.status = "submitted"
            print(f"Submetido: {job.id} → {job_id}")
            time.sleep(0.1)  # Buffer de limite de taxa
        except Exception as e:
            job.status = "submission_failed"
            print(f"Falha ao submeter {job.id}: {e}")
    
    # Poll de todos os jobs pendentes
    while pending_jobs:
        completed = []
        for api_job_id, job in pending_jobs.items():
            try:
                output = client.check_job(api_job_id)
                if output['status'] == 'completed':
                    job.video_url = output['output']['video_url']
                    job.status = "completed"
                    completed.append(api_job_id)
                    print(f"Concluído: {job.id}")
                elif output['status'] == 'failed':
                    job.status = "failed"
                    completed.append(api_job_id)
            except Exception as e:
                print(f"Erro ao verificar {api_job_id}: {e}")
        
        for job_id in completed:
            del pending_jobs[job_id]
        
        if pending_jobs:
            time.sleep(10)
    
    # Salvar resultados
    results_file = Path(output_dir) / "results.csv"
    with open(results_file, 'w', newline='') as f:
        writer = csv.DictWriter(f, fieldnames=['id', 'status', 'video_url', 'filename'])
        writer.writeheader()
        for job in jobs:
            writer.writerow({
                'id': job.id,
                'status': job.status,
                'video_url': job.video_url,
                'filename': job.output_filename
            })
    
    print(f"Resultados salvos em {results_file}")
    successful = sum(1 for j in jobs if j.status == 'completed')
    print(f"Concluídos: {successful}/{len(jobs)}")

Integração com Sistemas de Gerenciamento de Conteúdo

Para equipes que usam plataformas CMS, integre a Seedance ao seu pipeline de conteúdo:

# Exemplo: Integração WordPress via REST API
import requests

def publish_post_with_video(
    wp_url: str,
    wp_credentials: tuple,
    title: str,
    content: str,
    video_prompt: str
) -> dict:
    """Gera um vídeo e o publica junto com um post do WordPress."""
    
    # Gerar vídeo
    seedance = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    output = seedance.create_video(prompt=video_prompt)
    video_url = output['video_url']
    
    # Incorporar vídeo no conteúdo do post
    video_embed = f'<video controls src="{video_url}" style="max-width:100%"></video>'
    full_content = f"{video_embed}\n\n{content}"
    
    # Publicar no WordPress
    response = requests.post(
        f"{wp_url}/wp-json/wp/v2/posts",
        auth=wp_credentials,
        json={
            "title": title,
            "content": full_content,
            "status": "publish"
        }
    )
    return response.json()

Integração Serverless (AWS Lambda / Vercel)

Para arquiteturas serverless, use processamento assíncrono:

# Manipulador AWS Lambda
import json
import boto3

def lambda_handler(event, context):
    """Função Lambda acionada por mensagem SQS com solicitação de geração de vídeo."""
    body = json.loads(event['Records'][0]['body'])
    
    client = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    
    try:
        job_id = client.generate_text_to_video(
            prompt=body['prompt'],
            duration=body.get('duration', 8)
        )
        
        # Armazenar job_id para rastreamento assíncrono de conclusão
        dynamodb = boto3.resource('dynamodb')
        table = dynamodb.Table('VideoJobs')
        table.put_item(Item={
            'job_id': job_id,
            'request_id': body['request_id'],
            'status': 'processing',
            'created_at': int(time.time())
        })
        
        return {'statusCode': 200, 'body': json.dumps({'job_id': job_id})}
    
    except Exception as e:
        return {'statusCode': 500, 'body': json.dumps({'error': str(e)})}

Monitoramento e Observabilidade

Para aplicações de produção, implemente monitoramento abrangente:

import logging
from datetime import datetime

# Configure logging estruturado
logging.basicConfig(
    format='%(asctime)s %(levelname)s %(name)s %(message)s',
    level=logging.INFO
)
logger = logging.getLogger('seedance.api')

class MonitoredSeedanceClient(SeedanceClient):
    def create_video(self, **kwargs) -> dict:
        start = datetime.now()
        try:
            result = super().create_video(**kwargs)
            duration_ms = (datetime.now() - start).total_seconds() * 1000
            logger.info("video_generated", extra={
                'prompt_length': len(kwargs.get('prompt', '')),
                'duration_ms': duration_ms,
                'resolution': kwargs.get('resolution', '1080p')
            })
            return result
        except Exception as e:
            logger.error("video_generation_failed", extra={
                'error': str(e),
                'prompt': kwargs.get('prompt', '')[:100]
            })
            raise

Acompanhe estas métricas principais em produção:

• Latência de geração: Tempos de conclusão P50, P95, P99
• Taxas de erro: Por código de erro, com limites de alerta
• Consumo de créditos: Uso diário vs. orçamento
• Profundidade da fila: Número de jobs pendentes a qualquer momento
• Taxa de sucesso: Percentual de jobs concluídos com sucesso

A API Seedance foi projetada para desenvolvedores que desejam trazer geração profissional de vídeo por IA para suas aplicações. Com autenticação direta, códigos de erro claros e padrões de integração flexíveis, você pode adicionar geração de vídeo por IA a qualquer aplicação em um único sprint de desenvolvimento.

Comece a construir com a API gratuita da Seedance em seedance.tv →

Construir aplicações de qualidade de produção com geração de vídeo por IA requer atenção aos mesmos fundamentos de engenharia de qualquer integração de API: gerenciamento seguro de credenciais, tratamento robusto de erros, padrões eficientes de polling ou webhook e observabilidade abrangente. A Seedance fornece uma API amigável para desenvolvedores que torna essas integrações diretas. Seja construindo um pipeline de automação de conteúdo, uma ferramenta de criação de vídeo voltada para o usuário ou um fluxo de trabalho de produção interno, os padrões neste guia fornecem a base para uma integração confiável e escalável com a API Seedance.

A combinação de gerações gratuitas ilimitadas, direitos comerciais e uma API limpa torna a Seedance exclusivamente acessível entre as plataformas de vídeo por IA. Você pode prototipar, testar e lançar uma aplicação de produção sem incorrer em custos de API — uma vantagem significativa em comparação com modelos de preços baseados em uso que tornam os custos imprevisíveis durante o desenvolvimento. Comece com o plano gratuito, construa sua integração, meça seus padrões de uso e escale com confiança sabendo que a plataforma suporta seu crescimento.

Para equipes avaliando APIs de vídeo por IA, a decisão geralmente se resume a três fatores: qualidade, custo e experiência do desenvolvedor. A Seedance oferece todos os três — saída de vídeo de qualidade profissional, um plano gratuito sem marcas d'água e direitos comerciais, e uma API RESTful limpa com comportamento previsível. Os padrões de monitoramento e integração descritos neste guia garantem que sua integração Seedance será sustentável e observável à medida que sua aplicação cresce em complexidade e escala. A API Seedance é amigável para desenvolvedores por design — autenticação clara, códigos de erro previsíveis e padrões de integração flexíveis que funcionam com qualquer pilha de tecnologia. O investimento em uma integração sólida é tipicamente um único sprint, e o retorno é capacidade ilimitada de geração de vídeo por IA integrada diretamente em sua aplicação ou fluxo de trabalho. Comece a construir com a API gratuita hoje em seedance.tv para experimentar em primeira mão como a geração de vídeo por IA pode transformar sua aplicação ou fluxo de trabalho.