API de referencia de Seedance 2.0: vídeo multimodal programático

El acceso programático a video con IA multimodal cambia lo que es posible. Los clips únicos son ideales para marketing y creación de contenido, pero los flujos de trabajo automatizados (generación de video para catálogos, personalización por usuario, operaciones de contenido en lote) requieren acceso por API.

La API de referencia de Seedance 2.0 expone la capacidad multimodal completa: hasta 9 imágenes, 3 videos y 3 clips de audio por solicitud, de forma programática, con el mismo precio por segundo que la interfaz web.

Resumen rápido

• Endpoint: bytedance/seedance-2.0/reference-to-video
• Entradas: prompt de texto + hasta 9 imágenes + 3 videos + 3 clips de audio
• Precio: $0.3024/seg de salida, igual que la interfaz web
• Salida: video 720p, 4-15 segundos, sincronización de audio nativa
• Tiempo de generación: 60-180 segundos por solicitud
• Ideal para automatización de catálogos, flujos de trabajo en lote y contenido programático
• Prueba la API gratis con 10 créditos

Cuándo usar la API

La interfaz web es ideal para trabajo creativo manual, de uno en uno. La API es para todo lo demás.

La API es la opción adecuada cuando necesitas:

• Generación en lote de cientos de recursos
• Integración con pipelines de contenido o producto existentes
• Video personalizado por usuario dentro de una aplicación
• Pruebas A/B automatizadas de variantes de creatividades publicitarias
• Generación de contenido programada para publicación diaria
• Flujos de trabajo de catalogación vinculados a registros de base de datos

Quédate con la interfaz web cuando:

• Estás iterando creativamente y necesitas ver y ajustar cada resultado
• El volumen es bajo (menos de 10-20 clips por sesión)
• Estás explorando la herramienta por primera vez

El endpoint

El endpoint de referencia a video es:

bytedance/seedance-2.0/reference-to-video

Este es el único endpoint que necesitas para generaciones en modo de referencia multimodal. Una sola solicitud gestiona texto, hasta 9 imágenes, hasta 3 videos y hasta 3 clips de audio. El modelo fusiona todas las entradas y devuelve un video generado.

Para flujos de trabajo de texto a video o de imagen única, usa los endpoints de API estándar de Seedance 2.0 en su lugar.

Estructura de la solicitud

Una solicitud típica de referencia a video incluye:

• prompt: Descripción en texto del sujeto y la acción (obligatorio)
• reference_images: Array de hasta 9 URLs de imágenes o referencias de archivos
• reference_videos: Array de hasta 3 URLs de video (opcional)
• reference_audio: Array de hasta 3 URLs de audio (opcional)
• duration: Duración de la salida en segundos, de 4 a 15 (obligatorio)
• aspect_ratio: Uno de 16:9, 9:16, 1:1 (obligatorio)

Los archivos de entrada pueden proporcionarse como URLs (de acceso público) o cargarse directamente según tu patrón de integración.

Precios a través de la API

Los precios de la API coinciden exactamente con los de la interfaz web:

No hay tarifa de acceso a la API ni cargo adicional por la carga de referencias. Solo pagas por los segundos de salida generados.

Los créditos funcionan de la misma manera en la API y en la interfaz web. Recarga a través de página de precios y el mismo fondo de créditos es utilizado por ambas interfaces. Para uso intensivo de la API, el plan Studio de $120 (1 800 créditos al mes) ofrece la mejor tarifa por crédito, y cualquier recarga adicional que añadas nunca caduca.

Empieza a desarrollar con la API. Obtén acceso a la API con 10 créditos gratis al registrarte. Empieza gratis.

Casos de uso de ejemplo

Automatización de video para catálogos

Para plataformas de ecommerce con cientos o miles de referencias, la API te permite generar un video corto de producto para cada artículo a partir de las imágenes de producto existentes.

Flujo de trabajo:

1. Consulta tu base de datos de productos
2. Para cada producto, obtén entre 5 y 7 imágenes del producto
3. Combínalas con un paquete de referencia de marca (2-3 imágenes)
4. Llama a la API con una plantilla de prompt para presentación del producto
5. Almacena la URL del video devuelto en el registro del producto
6. Muéstralo en las páginas de detalle del producto

Economía: Un catálogo de 500 referencias a 5 segundos por video = 500 × 303 créditos = 151 500 créditos = ~$1 515. Para un despliegue de video a escala de catálogo, eso representa un valor extraordinario.

Generación de video personalizado

Para aplicaciones que entregan video personalizado por usuario (tarjetas de felicitación, contenido de celebración, intros de incorporación), la API te permite generar videos bajo demanda con referencias específicas del usuario.

Flujo de trabajo:

1. El usuario sube entre 3 y 5 fotos personales (con consentimiento)
2. Tu aplicación las combina con un paquete de referencia de estilo
3. La llamada a la API genera un clip de video personalizado
4. Se lo entrega al usuario a través de tu aplicación

Esto escala a decenas de miles de usuarios sin necesidad de un equipo de contenido.

Generación de variantes de creatividades publicitarias

Los equipos de marketing que gestionan publicidad en redes sociales necesitan variantes creativas constantemente. La API te permite generar variantes de pruebas A/B de forma programática.

Flujo de trabajo:

1. Define un paquete de referencia de marca (6-8 imágenes)
2. Escribe plantillas de prompt para diferentes enfoques publicitarios
3. Itera por las variantes llamando a la API para cada una
4. Entrega los clips generados a tu plataforma publicitaria
5. Mide el rendimiento y genera los ganadores a escala

Puedes producir 50 variantes de anuncios en una ejecución automatizada por ~$150 en costos de API, frente a la producción tradicional que supone miles de dólares por variante.

Gestión de respuestas

Las respuestas de la API suelen incluir:

• ID de generación: Rastrea el estado de la solicitud
• Estado: pending, processing, complete, failed
• URL de salida: Disponible una vez que el estado es complete
• Metadatos: Duración, resolución, tamaño de archivo

Las generaciones en modo de referencia tardan 60-180 segundos, por lo que tu integración debe gestionar respuestas asíncronas. Consulta el endpoint de estado o usa webhooks (si están disponibles en tu cuenta) para recibir una notificación al completarse.

No bloquees los flujos orientados al usuario esperando la finalización de la generación. Encola la solicitud, notifica al usuario cuando esté lista y entrega de forma asíncrona.

Límites de velocidad y concurrencia

Para la mayoría de los niveles de cuenta se aplican límites de generación concurrente. Planifica tus flujos de trabajo en lote respetando los límites: encola las solicitudes y procésalas con la concurrencia permitida.

Para flujos de trabajo de producción de alto volumen, contacta con el soporte de la plataforma para consultar los límites de concurrencia empresarial. La mayoría de las cuentas estándar pueden gestionar trabajo en lote moderado (10-30 generaciones concurrentes) sin problemas.

Autenticación y claves

El acceso a la API utiliza autenticación estándar basada en claves. Genera tu clave de API en la configuración de tu cuenta después de registrarte. Guarda las claves únicamente en el servidor: nunca las expongas en el código del cliente.

Idempotencia y reintentos

Las generaciones de la API no son nativas idempotentes porque cada llamada consume créditos. Si una generación falla a mitad del proceso, la lógica de reintentos debe verificar el estado de la generación fallida antes de volver a solicitarla. Una generación fallida normalmente no consume créditos, pero siempre compruébalo en el panel de tu cuenta.

Para flujos de trabajo en producción, implementa:

• Lógica de reintentos con retroceso exponencial ante fallos transitorios
• Consulta de estado o gestión de webhooks para la finalización asíncrona
• Registro de errores para detectar problemas sistemáticos
• Monitoreo del saldo de créditos para recibir alertas antes de quedarte sin ellos

Buenas prácticas para flujos de trabajo programáticos

1. Usa paquetes de referencia coherentes. Para trabajos de catálogo o en serie, aplica un hash a tus paquetes de referencia para que los paquetes idénticos entre solicitudes produzcan un estilo más consistente.

2. Mantén las plantillas de prompt simples. Los prompts programáticos deben generarse a partir de datos estructurados, no escribirse a mano en cada llamada. El patrón correcto es plantilla + campos de datos.

3. Almacena en caché las URLs de archivos de referencia. Si usas referencias basadas en URL, asegúrate de que las URLs sean estables y accesibles. Las URLs de S3 caducadas o los archivos movidos harán que las generaciones fallen.

4. Gestiona la seguridad de contenido de forma adecuada. La plataforma cuenta con filtros de seguridad de contenido. Incorpora a tu flujo de trabajo un manejo apropiado para las solicitudes rechazadas por los filtros.

5. Registra los metadatos de generación. Rastrea cada generación (prompt, conjunto de referencias, duración, créditos consumidos, URL de salida) en la base de datos de tu aplicación. Esto facilita mucho la depuración y los informes.

Flujo de trabajo en lote de ejemplo

Pseudocódigo para un flujo de trabajo de generación de video de producto en lote:

for product in product_catalog:
    references = build_reference_bundle(
        brand_images,
        product.photo_urls[:4]
    )
    prompt = f"{product.name} product rotates slowly on a clean surface, soft studio lighting, 5 seconds"

    response = seedance_api.generate(
        endpoint="bytedance/seedance-2.0/reference-to-video",
        prompt=prompt,
        reference_images=references,
        duration=5,
        aspect_ratio="16:9"
    )

    generation_id = response.id
    queue_poll_task(generation_id, product.id)

Un proceso de consulta de seguimiento gestiona la finalización y almacena la URL de salida junto al registro del producto.

Monitoreo y control de costos

Para el uso de la API en producción, configura el monitoreo de costos:

• Alertas de presupuesto diario: Avisa cuando el gasto diario en la API supere un umbral
• Límites por flujo de trabajo: Limita los trabajos en lote a un gasto máximo de créditos para evitar automatizaciones descontroladas
• Paneles de uso: Rastrea qué flujos de trabajo consumen más créditos
• Alertas de saldo de créditos: Recarga antes de quedarte sin saldo

Estas salvaguardas evitan sorpresas cuando escalas la automatización.

Paridad de precios: API frente a interfaz web

Una pregunta frecuente: ¿hay descuento por usar la API? No. Tanto la API como la interfaz web cobran los mismos $0.3024 por segundo. La API tiene un precio acorde al trabajo que realiza, no a la interfaz que utilizas.

Donde los usuarios de alto volumen ahorran es en la selección de su nivel. Los usuarios intensivos de la API deberían usar el $120 Studio plan para obtener el mejor valor por dólar.

Primeros pasos con la API

1. Regístrate en arteza.ai (10 créditos gratis)
2. Genera tu clave de API en la configuración de la cuenta
3. Recarga un paquete de créditos acorde a tu volumen esperado
4. Integra el endpoint en tu aplicación
5. Empieza con lotes de prueba pequeños para validar tu flujo de trabajo
6. Escala a producción una vez completadas las pruebas

La primera llamada a la API puede estar activa en menos de una hora tras el registro en la mayoría de las integraciones.

Lecturas relacionadas

Para conocer el conjunto completo de funciones de referencia, lee Guía completa de Seedance 2.0 Reference. Para el flujo de trabajo de la interfaz web, consulta tutorial de estilo consistente. Para los detalles estándar de la API de Seedance 2.0, revisa Guía de la API de Seedance 2.0.

El video multimodal programático ya está aquí. Construye algo nuevo con él.