API de Seedance 2.0: cómo generar videos con IA de forma programática

Genera un video de IA cinematográfico con una sola solicitud HTTP. La API de Seedance 2.0 es la misma canalización de generación que usa la plataforma web, expuesta como una interfaz REST limpia con autenticación Bearer, webhooks y endpoints de lotes. Si sabes hacer una solicitud POST, puedes construir una canalización de generación de video.

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 rápido: la 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 y consulta el estado o usa webhooks para la finalización
• Límites de velocidad: 60 solicitudes/minuto, 5 generaciones simultáneas
• Modelos: Seedance 2.0, 1.0 Pro, 1.0 Lite, Seedream v3/v4.5/v5, todos en una sola API
• Costo en créditos: El mismo precio dinámico por segundo que la interfaz web (19-351 créditos para 2.0)

Qué puede hacer realmente la API

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

Modelos compatibles

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

Autenticación en 30 segundos

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

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

Respuesta:

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

Reglas de seguridad importantes:

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

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

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 de inmediato y consultas el estado hasta la finalización (o usas 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": "The woman turns her head slowly and smiles, wind gently blowing her hair",
  "duration": 8,
  "aspect_ratio": "16:9"
}

Consultar el estado de la generación

Consulta el endpoint de la tarea para verificar el progreso.

GET /v1/tasks/{task_id}

Respuesta en curso

{
  "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 de finalización

{
  "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 URL de video caducan en 24 horas. Descárgalas y almacénalas en tu propia infraestructura sin demora.

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

Ejemplo completo en Python listo para producción

Aquí tienes un script completo que envía una generación, consulta el estado hasta la finalizació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 el estado hasta que la tarea finalice. Devuelve el dict 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):
    """Descarga el video al disco en streaming."""
    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")

Ejemplo en 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(`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}`);

Imagen a video en Python

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

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Genera video a partir de 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 falla

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

Estructura de la respuesta de error

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

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"Need {error['required_credits']} credits, have {error['available_credits']}")
        # Redirige al usuario a /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

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

Los límites

Cinco prácticas que importan en producción

1. Usa webhooks, no consultas de estado, a escala. Las consultas de estado desperdician llamadas a la API. Los webhooks se disparan exactamente una vez.
2. Implementa retroceso exponencial en respuestas 429. No reintentes de inmediato.
3. Descarga las URL de video sin demora. Caducan en 24 horas. Almacénalas en tu propio CDN.
4. Valida las entradas en el lado del cliente. Detecta problemas de longitud del prompt y tamaño del archivo antes de llamar a la API.
5. Verifica el saldo de créditos antes de trabajos en lote. Un error 402 a mitad de un lote es molesto. Consulta /account/credits primero.

Integración de webhooks

Incluye webhook_url en tu solicitud de generación y Arteza hará un POST a esa URL cuando la tarea finalice.

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

Payload 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. Verifica siempre la firma antes de procesar los eventos.

Generación en lote

Cuando necesitas varios clips, envíalos como un lote y recibe un solo webhook cuando todo finalice.

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

Las tareas de un lote se procesan de forma simultánea hasta el límite de concurrencia.

Cuatro casos de uso que vale la pena desarrollar

1. Videos de productos de e-commerce a escala

Automatiza la animación de productos para todo tu catálogo. Recorre tu base de datos de productos, lanza una llamada de imagen a video por artículo y almacena las URL 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"Slow 360 rotation of {product['name']}, studio lighting, white background",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

Combina esto con guía de video para e-commerce para consejos sobre el flujo de trabajo.

2. Pipelines automatizados para redes sociales

Alimenta temas de tendencia en generadores de prompts, genera video vertical diario y envíalo 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 = [
    "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"},
    )

El campo metadata se devuelve en el payload de finalización, por lo que puedes enrutar los resultados al bucket de campaña correcto de forma automática.

4. Aplicaciones interactivas

Integra la generación de video directamente en tu propia aplicación. Un usuario escribe un prompt, tu backend llama a la API y el webhook entrega el clip terminado. Todo el ciclo tarda unos 90 segundos.

Conclusión

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

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

¿Listo para empezar a construir? Crea tu cuenta gratis →

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