Guía de la API de Seedance para Desarrolladores 2026: Integración, Endpoints y Mejores Prácticas

Crear aplicaciones con generación de video por IA requiere acceso confiable a la API, documentación clara y precios predecibles. Esta guía cubre todo lo que los desarrolladores necesitan saber para integrar Seedance en sus aplicaciones — desde autenticación y endpoints hasta límites de velocidad, manejo de errores y mejores prácticas de producción.

¿Qué es la API de Seedance?

La API de Seedance proporciona acceso programático a las capacidades de generación de video por IA de Seedance. Los desarrolladores pueden integrar Seedance en aplicaciones web, aplicaciones móviles, servicios backend y flujos de trabajo automatizados a través de una API RESTful que acepta entradas de texto o imagen y devuelve contenido de video generado.

La API admite la misma funcionalidad principal que la interfaz web:

• Texto a video: Generar video a partir de indicaciones de texto
• Imagen a video: Animar una imagen estática en un video
• Control de estilo: Aplicar parámetros de estilo visual mediante indicaciones
• Opciones de resolución: Salida en 720p y 1080p

Primeros Pasos: Autenticación

Configuración de la Clave API

Accede a la API de Seedance a través del panel de tu cuenta:

1. Inicia sesión en seedance.tv
2. Navega a Configuración → API
3. Genera una clave API
4. Almacena la clave de forma segura — otorga acceso completo a tu cuenta

Nunca expongas tu clave API en código del lado del cliente. Siempre realiza las llamadas a la API desde tu servidor backend.

Encabezados de Autenticación

Todas las solicitudes a la API deben incluir tu clave API en el encabezado de autorización:

Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

Endpoints Principales

Generación de Texto a Video

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

Cuerpo de la solicitud:

{
  "prompt": "Vista aérea de una cadena montañosa a la hora dorada, toma lenta con dron, cinematográfica",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "style": "cinematic"
}

Respuesta:

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

La generación de video es asíncrona. La respuesta incluye un job_id para consultar su finalización.

Generación de Imagen a Video

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

Cuerpo de la solicitud:

{
  "image_url": "https://tu-almacenamiento.com/imagen-fuente.jpg",
  "prompt": "La cámara se aleja lentamente para revelar la escena completa",
  "duration": 6,
  "resolution": "1080p",
  "motion_intensity": 0.7
}

Alternativamente, sube la imagen directamente:

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

Verificación del Estado del Trabajo

GET /api/v1/jobs/{job_id}

Respuesta:

{
  "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 estado: queued → processing → completed / failed

Listar Trabajos

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

Devuelve una lista paginada de trabajos de generación para tu cuenta.

Manejo de Errores

Formato de Respuesta de Error Estándar

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite de velocidad de la API excedido. Reintentar después de 60 segundos.",
    "retry_after": 60
  }
}

Códigos de Error Comunes

Estrategia de Reintento

Implementa retroceso exponencial para errores reintentables:

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 reintentos excedido")

Consultar la Finalización del Trabajo

La generación generalmente toma entre 30 y 90 segundos. Implementa una consulta eficiente:

import time
import requests

def wait_for_completion(job_id: str, timeout: int = 300) -> dict:
    """Consultar el estado del trabajo hasta que se complete o se agote el tiempo."""
    start_time = time.time()
    poll_interval = 5  # Comenzar con 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"El trabajo {job_id} falló")
        
        # Aumentar el intervalo de consulta con el tiempo
        poll_interval = min(poll_interval * 1.5, 30)
        time.sleep(poll_interval)
    
    raise TimeoutError(f"El trabajo {job_id} agotó el tiempo después de {timeout} segundos")

Límites de Velocidad

Límites de Velocidad del Nivel Gratuito

Límites de Velocidad de Producción

Límites de velocidad más altos disponibles para aplicaciones de producción. Contacta al soporte de Seedance para aumentos en los límites de velocidad empresariales.

Encabezados de Límite de Velocidad

Las respuestas de la API incluyen información de límite de velocidad en los encabezados:

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

Ejemplo Completo del SDK de 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:
        """Enviar un trabajo de generación de texto a video. Devuelve 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:
        """Enviar un trabajo de generación de imagen a video. Devuelve 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:
        """Consultar hasta que el trabajo se complete. Devuelve el diccionario de salida."""
        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"Trabajo fallido: {job_id}")
            
            interval = min(interval * 1.2, 20)
            time.sleep(interval)
        
        raise TimeoutError(f"Tiempo de espera agotado para el trabajo: {job_id}")
    
    def create_video(
        self,
        prompt: str,
        duration: int = 8,
        resolution: str = "1080p"
    ) -> dict:
        """De extremo a extremo: enviar trabajo, esperar finalización, devolver salida."""
        job_id = self.generate_text_to_video(prompt, duration, resolution)
        return self.wait_for_job(job_id)


# Ejemplo de uso
client = SeedanceClient(api_key="tu_clave_api_aqui")

output = client.create_video(
    prompt="Reloj de lujo sobre superficie de mármol, iluminación dramática, rotación lenta, cinematográfico",
    duration=8,
    resolution="1080p"
)

print(f"URL del video: {output['video_url']}")
print(f"Duración: {output['duration']}s")
print(f"Tamaño del archivo: {output['file_size_mb']}MB")

Ejemplo en 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(`Trabajo fallido: ${jobId}`);

      interval = Math.min(interval * 1.2, 20000);
      await new Promise(r => setTimeout(r, interval));
    }
    throw new Error(`Tiempo de espera agotado para el trabajo: ${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: 'Amanecer en la montaña, dron aéreo lento, cinematográfico, hora dorada',
  duration: 8,
  resolution: '1080p',
});
console.log('Video listo:', output.videoUrl);

Integración de Webhooks (Notificación Asíncrona)

En lugar de consultar, registra una URL de webhook para recibir notificaciones de finalización:

POST /api/v1/webhooks

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

Carga útil del webhook (enviada a tu endpoint al completarse):

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

Verifica las firmas del webhook para evitar suplantación:

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)

Mejores Prácticas de Producción

1. Almacena las Claves API de Forma Segura

# Usa variables de entorno
import os
api_key = os.environ.get('SEEDANCE_API_KEY')
if not api_key:
    raise ValueError("La variable de entorno SEEDANCE_API_KEY no está configurada")

2. Implementa Colas de Solicitudes

Para aplicaciones de alto volumen, implementa una cola para respetar los límites de velocidad:

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:
        """Agregar un trabajo de generación a la cola. Devuelve job_id."""
        with self.semaphore:
            job_id = self.client.generate_text_to_video(prompt)
            return job_id

3. Almacena en Caché los Videos Generados

Evita regenerar contenido 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()

# Verificar caché antes de generar
cache_key = get_cache_key(prompt, duration, resolution)
if cached_url := video_cache.get(cache_key):
    return cached_url

# Generar y almacenar en caché
output = client.create_video(prompt=prompt, duration=duration)
video_cache.set(cache_key, output['video_url'], ttl=86400)
return output['video_url']

4. Maneja Usuarios Concurrentes

Para aplicaciones con múltiples usuarios generando videos simultáneamente:

import asyncio
import aiohttp

async def generate_videos_concurrent(prompts: list[str]) -> list[dict]:
    """Generar múltiples videos concurrentemente con limitación de velocidad."""
    semaphore = asyncio.Semaphore(5)  # Máximo 5 trabajos concurrentes
    
    async def generate_one(prompt: str) -> dict:
        async with semaphore:
            # Enviar trabajo
            job_id = await submit_job_async(prompt)
            # Esperar finalización
            return await wait_for_job_async(job_id)
    
    return await asyncio.gather(*[generate_one(p) for p in prompts])

Preguntas Frecuentes

¿Hay un nivel gratuito para la API de Seedance? Sí. Seedance ofrece acceso a la API en el nivel gratuito con límites de velocidad. Para aplicaciones de producción que requieren mayor rendimiento, contacta a Seedance para conocer los planes de API de producción.

¿Qué formatos de video devuelve la API? La API devuelve archivos MP4 con codificación H.264 por defecto. La URL de salida es un enlace de descarga directa válido por 24 horas.

¿Por cuánto tiempo están disponibles los videos generados? Las URL de los videos de salida están disponibles para descarga durante 24 horas. Descarga y almacena los videos en tu propio almacenamiento para acceso permanente.

¿Puedo usar videos generados por la API con fines comerciales? Sí. El nivel gratuito de Seedance incluye derechos de uso comercial. Los videos generados a través de la API están sujetos a la misma licencia comercial que el contenido generado por web.

¿Cuál es la duración máxima del video a través de la API? 8 segundos por generación en el nivel estándar. Contacta a Seedance para opciones de duración extendida.

¿Cómo manejo errores en producción? Implementa reintentos con retroceso exponencial para errores 429 y 5xx. Registra todos los fallos con job_id para depuración. Configura alertas para tasas de error elevadas.

Comienza a construir con Seedance en seedance.tv →

Patrones de Integración Avanzados

Pipeline de Generación de Video por Lotes

Para equipos de contenido que necesitan generar muchos videos regularmente, un pipeline por lotes es más eficiente que las solicitudes individuales:

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:
    """Leer indicaciones de un CSV, generar videos, guardar resultados."""
    client = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    jobs = []
    
    # Leer indicaciones
    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")
            ))
    
    # Enviar todos los trabajos
    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"Enviado: {job.id} → {job_id}")
            time.sleep(0.1)  # Amortiguador de límite de velocidad
        except Exception as e:
            job.status = "submission_failed"
            print(f"Error al enviar {job.id}: {e}")
    
    # Consultar todos los trabajos pendientes
    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"Completado: {job.id}")
                elif output['status'] == 'failed':
                    job.status = "failed"
                    completed.append(api_job_id)
            except Exception as e:
                print(f"Error al consultar {api_job_id}: {e}")
        
        for job_id in completed:
            del pending_jobs[job_id]
        
        if pending_jobs:
            time.sleep(10)
    
    # Guardar 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 guardados en {results_file}")
    successful = sum(1 for j in jobs if j.status == 'completed')
    print(f"Completados: {successful}/{len(jobs)}")

Integración con Sistemas de Gestión de Contenidos

Para equipos que usan plataformas CMS, integra Seedance en tu pipeline de contenido:

# Ejemplo: Integración con WordPress a través de la API REST
import requests

def publish_post_with_video(
    wp_url: str,
    wp_credentials: tuple,
    title: str,
    content: str,
    video_prompt: str
) -> dict:
    """Generar un video y publicarlo junto con una entrada de WordPress."""
    
    # Generar video
    seedance = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    output = seedance.create_video(prompt=video_prompt)
    video_url = output['video_url']
    
    # Incrustar video en el contenido de la entrada
    video_embed = f'<video controls src="{video_url}" style="max-width:100%"></video>'
    full_content = f"{video_embed}\n\n{content}"
    
    # Publicar en 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()

Integración Serverless (AWS Lambda / Vercel)

Para arquitecturas serverless, usa procesamiento asíncrono:

# Manejador de AWS Lambda
import json
import boto3

def lambda_handler(event, context):
    """Función Lambda activada por mensaje SQS con solicitud de generación de video."""
    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)
        )
        
        # Almacenar job_id para seguimiento asíncrono de finalización
        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)})}

Monitoreo y Observabilidad

Para aplicaciones de producción, implementa un monitoreo integral:

import logging
from datetime import datetime

# Configurar registro estructurado
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

Realiza un seguimiento de estas métricas clave en producción:

• Latencia de generación: Tiempos de finalización P50, P95, P99
• Tasas de error: Por código de error, con umbrales de alerta
• Consumo de créditos: Uso diario vs. presupuesto
• Profundidad de la cola: Número de trabajos pendientes en cualquier momento
• Tasa de éxito: Porcentaje de trabajos que se completan exitosamente

La API de Seedance está diseñada para desarrolladores que desean incorporar generación de video por IA profesional en sus aplicaciones. Con autenticación sencilla, códigos de error claros y patrones de integración flexibles, puedes agregar generación de video por IA a cualquier aplicación en un solo sprint de desarrollo.

Comienza a construir con la API gratuita de Seedance en seedance.tv →

Construir aplicaciones de calidad de producción con generación de video por IA requiere atención a los mismos fundamentos de ingeniería que cualquier integración de API: gestión segura de credenciales, manejo robusto de errores, patrones eficientes de consulta o webhooks, y observabilidad integral. Seedance proporciona una API amigable para desarrolladores que hace que estas integraciones sean sencillas. Ya sea que estés construyendo un pipeline de automatización de contenido, una herramienta de creación de video orientada al usuario o un flujo de trabajo de producción interno, los patrones en esta guía proporcionan la base para una integración confiable y escalable de la API de Seedance.

La combinación de generaciones gratuitas ilimitadas, derechos comerciales y una API limpia hace que Seedance sea excepcionalmente accesible entre las plataformas de video por IA. Puedes prototipar, probar y lanzar una aplicación de producción sin incurrir en costos de API — una ventaja significativa en comparación con los modelos de precios basados en uso que hacen que los costos sean impredecibles durante el desarrollo. Comienza con el nivel gratuito, construye tu integración, mide tus patrones de uso y escala con confianza sabiendo que la plataforma respalda tu crecimiento.

Para equipos que evalúan APIs de video por IA, la decisión a menudo se reduce a tres factores: calidad, costo y experiencia del desarrollador. Seedance cumple en los tres aspectos — salida de video de calidad profesional, un nivel gratuito sin marcas de agua y con derechos comerciales, y una API RESTful limpia con comportamiento predecible. Los patrones de monitoreo e integración descritos en esta guía aseguran que tu integración con Seedance sea mantenible y observable a medida que tu aplicación crece en complejidad y escala. La API de Seedance está diseñada para ser amigable para desarrolladores — autenticación clara, códigos de error predecibles y patrones de integración flexibles que funcionan con cualquier pila tecnológica. La inversión en una integración sólida es típicamente un solo sprint, y el retorno es capacidad ilimitada de generación de video por IA integrada directamente en tu aplicación o flujo de trabajo. Comienza a construir con la API gratuita hoy en seedance.tv para experimentar de primera mano cómo la generación de video por IA puede transformar tu aplicación o flujo de trabajo.