API de Seedance 2.0: Cómo generar videos con IA mediante programación

Genera un video de IA cinematográfico con una única solicitud HTTP. La API de Seedance 2.0 utiliza la misma canalización de generación que la plataforma web, expuesta como una interfaz REST limpia con autenticación Bearer, webhooks y endpoints de lote. Si puedes hacer una solicitud POST, puedes crear una canalización de generación de videos.

Esta guía cubre todo lo que necesitas para integrar Seedance 2.0 en tus propias aplicaciones: autenticación, endpoints, parámetros, manejo de errores y ejemplos de código listos para producción en Python y JavaScript.

Resumen ejecutivo: API de un vistazo

• URL base: https://api.arteza.ai/v1
• Autenticación: Token Bearer en el encabezado Authorization
• Generación: Asíncrona: envía una tarea, consulta o espera webhooks para completarla
• Límites de velocidad: 60 solicitudes por minuto, 5 generaciones concurrentes
• Modelos: Seedance 2.0, 1.0 Pro, 1.0 Lite, Seedream v3/v4.5/v5 todo en una sola API
• Costo de créditos: Los mismos precios dinámicos por segundo que en la interfaz web (~243-910 créditos para 2.0)

Qué puede hacer realmente la API

Todo lo que hace la interfaz web, también lo hace la API. Texto a video, imagen a video, selección de modelo, control de duración, relación de aspecto, controles de audio y acceso a cada modelo de la plataforma. Endpoints de lote para generar muchos clips a la vez. Notificaciones por webhook para que no tengas que hacer consultas. Metadatos personalizados que se devuelven en los resultados para rastrear pruebas A/B o variantes de campañas.

Modelos soportados

Todos los modelos utilizan la misma superficie de API, solo con identificadores diferentes.

Autenticación en 30 segundos

Genera una clave de API desde el panel bajo Configuración > Claves de API. Envíala como un token Bearer:

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

Respuesta:

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

Reglas de seguridad que importan:

• Nunca envíes tu clave de API en código del lado del cliente o repositorios públicos
• Guárdala en variables de entorno (SEEDANCE_API_KEY)
• Rota las claves periódicamente desde el panel
• Cada clave hereda el saldo de créditos de su cuenta padre

El endpoint de texto a video

Este es el endpoint que usarás con más frecuencia.

POST /v1/generate/text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Toma aérea de una ciudad costera al atardecer, luz dorada reflejándose en rascacielos de cristal, video de dron cinematográfico",
  "duration": 10,
  "aspect_ratio": "16:9",
  "audio": true
}

Referencia de parámetros

Respuesta exitosa

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

La generación es asíncrona. Recibes un task_id inmediatamente y consulta para la completación (o usa webhooks).

El endpoint de imagen a video

Anima una imagen de origen con un prompt de movimiento.

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

¿Prefieres no subir un archivo? Pasa una image_url en su lugar:

{
  "model": "seedance-2.0",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "La mujer gira lentamente su cabeza y sonríe, el viento sopla suavemente su cabello",
  "duration": 8,
  "aspect_ratio": "16:9"
}

Verificar el estado de la generación

Consulta el endpoint de tarea para verificar el progreso.

GET /v1/tasks/{task_id}

Respuesta en progreso

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

Respuesta completada

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

Las URLs de video expiran en 24 horas. Descárgalas y almacénalas en tu propia infraestructura rápidamente.

¿Quieres generar resultados como este programáticamente? Estás a 30 segundos de tu primera llamada a la API. Obtén tu clave API gratis →

Ejemplo de Python listo para producción

Aquí hay un script completo que envía una generación, consulta la completación y descarga el 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"):
    """Envía una tarea de texto a video. Devuelve 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):
    """Consulta hasta que la tarea termine. Devuelve el diccionario 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"Generación fallida: {data.get('error')}")

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"La tarea {task_id} no se completó dentro de {timeout}s")


def download_video(video_url, output_path):
    """Transmite el video al 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="Un gato sentado en el alféizar de una ventana mirando caer la lluvia afuera, iluminación acogedora en interiores, profundidad de campo reducida",
        duration=10,
    )
    print(f"Tarea enviada: {task_id}")

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

    download_video(result["video_url"], "output.mp4")
    print("Descargado a output.mp4")

Ejemplo de JavaScript (Node.js)

El mismo flujo de trabajo en Node.js moderno con 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(`Generación fallida: ${data.error}`);
    }

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

  throw new Error(`La tarea ${taskId} agotó el tiempo de espera`);
}

// Uso
const taskId = await generateVideo(
  "Lapso de tiempo de una flor floreciendo, lente macro, iluminación natural suave",
  12
);
console.log(`Tarea enviada: ${taskId}`);

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

Imagen a video en Python

Cuando necesites subir una imagen de origen, usa multipart/form-data:

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Genera video desde un archivo de imagen 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"]

Manejo de errores que no se desmorona

La API utiliza códigos de estado HTTP estándar con cuerpos de error estructurados.

Forma de respuesta de error

{
  "error": {
    "code": "insufficient_credits",
    "message": "Tu cuenta tiene 150 créditos pero esta generación requiere 607 créditos.",
    "required_credits": 607,
    "available_credits": 150
  }
}

Patrón 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"Necesitas {error['required_credits']} créditos, tienes {error['available_credits']}")
        # Redirige al usuario a /pricing
    elif status == 429:
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Límite de velocidad excedido. Reintentar después de {retry_after}s.")
    else:
        raise

Límites de velocidad y mejores prácticas de producción

Los límites

Cinco prácticas que importan en producción

1. Usa webhooks, no polling, a escala. El polling desperdicia llamadas a la API. Los webhooks se disparan exactamente una vez.
2. Implementa retardo exponencial en respuestas 429. No reintentas inmediatamente.
3. Descarga URLs de video rápidamente. Expiran en 24 horas. Guárdalas en tu propio CDN.
4. Valida entradas del lado del cliente. Detecta problemas de longitud de prompt y tamaño de archivo antes de llamar a la API.
5. Verifica el saldo de créditos antes de trabajos por lote. Un 402 a mitad de lote es molesto. Consulta /account/credits primero.

Integración de Webhook

Incluye webhook_url en tu solicitud de generación y Arteza enviará una POST cuando la tarea se complete.

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

Carga del 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"
}

Las solicitudes de webhook incluyen un encabezado X-Seedance-Signature: una firma HMAC-SHA256 del cuerpo firmada con tu secreto de webhook. Siempre verifica la firma antes de procesar eventos.

Generación por lote

Cuando necesites múltiples clips, envíalos como un lote y obtén un webhook cuando todo se complete.

POST /v1/generate/batch

{
  "tasks": [
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Descripción de escena 1...",
      "duration": 8
    },
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Descripción de escena 2...",
      "duration": 10
    },
    {
      "type": "image-to-video",
      "model": "seedance-1.0-pro",
      "image_url": "https://example.com/product.jpg",
      "prompt": "Rotación lenta revelando detalles del producto",
      "duration": 6
    }
  ],
  "webhook_url": "https://yourapp.com/api/seedance/batch-complete"
}

Las tareas en un lote se procesan de forma concurrente hasta tu límite de concurrencia.

Cuatro casos de uso que vale la pena crear

1. Videos de productos de comercio electrónico a escala

Automatiza la animación de productos para todo tu catálogo. Recorre tu base de datos de productos, haz una llamada de imagen a video por artículo, guarda las URLs resultantes junto al registro del producto.

products = get_products_from_database()

for product in products:
    task_id = generate_from_image(
        image_path=product["hero_image"],
        prompt=f"Rotación lenta de 360 grados de {product['name']}, iluminación de estudio, fondo blanco",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

Combina esto con el guía de video de comercio electrónico para obtener consejos de flujo de trabajo.

2. Canalizaciones automatizadas de redes sociales

Alimenta temas tendencia en generadores de prompts, genera video vertical diario, envía a una cola de revisión:

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. Pruebas A/B de marketing

Genera múltiples variantes creativas con seguimiento de metadatos:

variants = [
    "Toma de héroe del producto con iluminación cálida, sensación de lujo",
    "Toma de héroe del producto con iluminación brillante, sensación energética",
    "Toma de héroe del producto con iluminación de humor, sensación premium",
]

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

El campo metadata se devuelve en la carga de completación, por lo que puedes enrutar resultados al depósito de campaña correcto automáticamente.

4. Aplicaciones interactivas

Construye generación de video directamente en tu propia aplicación. Un usuario escribe un prompt, tu backend llama a la API, el webhook entrega el clip terminado. Todo el bucle toma ~90 segundos.

La conclusión

La API de Arteza es sencilla de integrar y lista para producción. Autenticación simple, semántica REST limpia, webhooks para trabajo asíncrono y endpoints de lote para escala. Si has usado Stripe o cualquier API REST moderna, te sentirás como en casa en diez minutos.

Para precios y optimización de créditos, consulta el guía de precios. Para la descripción general del producto más amplio, lee el guía completa de Seedance 2.0.

¿Listo para comenzar a crear? Crea tu cuenta gratuita →

Sigue leyendo: Guía completa de Seedance 2.0 • Guía de precios • Seedance 2.0 vs Seedance 1.0 • Seedance 2.0 vs Runway Gen-4