API de Referencia Seedance 2.0: Vídeo Multimodal Programático

El acceso programático a video de IA multimodal cambia lo que es posible. Los clips únicos son excelentes para marketing y creación de contenido, pero los flujos de trabajo automatizados (generación de catálogos de video, personalización por usuario, operaciones de contenido por lotes) requieren acceso a 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, programáticamente, al mismo precio por segundo que la interfaz web.

Cuándo usar la API

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

La API es adecuada cuando necesitas:

• Generación por lotes en cientos de activos
• Integración con canalizaciones de contenido o producto existentes
• Video personalizado por usuario en una aplicación
• Pruebas A/B automatizadas de variantes creativas de anuncios
• Generación de contenido programado para publicación diaria
• Flujos de trabajo de catalogación vinculados a registros de base de datos

Mantente con la interfaz web cuando:

• Estés iterando creativamente y necesites ver/ajustar cada salida
• 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 Reference multimodal. Una única solicitud maneja 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 imagen única, utiliza los endpoints API estándar Seedance 2.0 en su lugar.

Estructura de Solicitud

Una solicitud típica de referencia a video incluye:

• prompt: Descripción de texto del sujeto y acción (requerido)
• reference_images: Matriz de hasta 9 URLs de imagen o referencias de archivo
• reference_videos: Matriz de hasta 3 URLs de video (opcional)
• reference_audio: Matriz de hasta 3 URLs de audio (opcional)
• duration: Duración de salida en segundos, 4-15 (requerido)
• aspect_ratio: Uno de 16:9, 9:16, 1:1 (requerido)

Los archivos de entrada se pueden proporcionar como URLs (accesibles públicamente) o cargarse directamente dependiendo de tu patrón de integración.

Precios a través de la API

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

No hay tarifa de acceso a API ni cargo adicional por cargas de referencia. Pagas solo por segundos de salida generada.

Los créditos funcionan de la misma manera en API e interfaz web. Recarga a través de página de precios y el mismo grupo de créditos se utiliza en ambas interfaces. Para uso de API de alto volumen, el tier Max de $100 (12,000 créditos) es el punto de partida más económico.

Comienza a construir con la API. Obtén acceso a API con 50 créditos gratuitos al registrarse. Comenzar gratis.

Casos de Uso Ejemplares

Automatización de Video de Catálogo

Para plataformas de ecommerce con cientos o miles de SKUs, la API te permite generar un video corto de producto para cada producto basado en imágenes de producto existentes.

Flujo de trabajo:

1. Consulta tu base de datos de productos
2. Para cada producto, obtén 5-7 imágenes de producto
3. Combina con un paquete de referencia de marca (2-3 imágenes)
4. Llama la API con plantilla de prompt para revelación de producto
5. Almacena la URL del video devuelto en tu registro de producto
6. Sirve en páginas de detalles de producto

Economía: Catálogo de 500 SKU con videos de 5 segundos = 500 × 303 créditos = 151,500 créditos = ~$1,515. Para un lanzamiento de video en todo el catálogo, ese es un valor notable.

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 carga 3-5 fotos personales (con consentimiento)
2. Tu aplicación las combina con un paquete de referencia de estilo
3. La llamada a API genera un clip de video personalizado
4. Entrega al usuario a través de tu aplicación

Esto se escala a decenas de miles de usuarios sin sobrecarga del equipo de contenido.

Generación de Variantes Creativas de Anuncios

Los equipos de marketing que ejecutan redes sociales pagadas necesitan variantes creativas constantes. La API te permite generar variantes de prueba A/B programáticamente.

Flujo de trabajo:

1. Define un paquete de referencia de marca (6-8 imágenes)
2. Escribe plantillas de prompt para diferentes ángulos de anuncios
3. Recorre variantes, llamando la API para cada una
4. Entrega clips generados a tu plataforma de anuncios
5. Rastrea el desempeño y genera ganadores a escala

Puedes producir 50 variantes de anuncios en una ejecución automatizada por ~$150 en costos de API, versus producción tradicional de miles por variante.

Manejo de Respuestas

Las respuestas de API típicamente incluyen:

• Generation ID: Rastrea el estado de la solicitud
• Status: pending, processing, complete, failed
• Output URL: Disponible una vez que el estado es completado
• Metadata: Duración, resolución, tamaño de archivo

Las generaciones en modo de referencia toman 60-180 segundos, por lo que tu integración debe manejar respuestas asincrónicas. Sondea el endpoint de estado o usa webhooks (si están disponibles en tu cuenta) para ser notificado sobre la finalización.

No bloquees flujos enfrentados al usuario en la finalización de la generación. Coloca la solicitud en cola, notifica al usuario cuando esté lista y entrega de forma asincrónica.

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 por lotes para respetar los límites: coloca solicitudes en cola y procésalas en la concurrencia permitida.

Para flujos de trabajo de producción de alto volumen, contacta soporte de plataforma sobre límites de concurrencia empresariales. La mayoría de cuentas estándar pueden manejar trabajo por lotes moderado (10-30 generaciones concurrentes) sin problema.

Autenticación y Claves

El acceso a API usa autenticación estándar basada en claves. Genera tu clave de API en la configuración de tu cuenta después de registrarte. Mantén las claves solo del lado del servidor - nunca las expongas en código de cliente.

Idempotencia y Reintentos

Las generaciones de API no son nativas de idempotentes porque cada llamada cuesta créditos. Si una generación falla en el proceso, la lógica de reintentos debe verificar el estado de la generación fallida antes de volver a solicitar. Una generación fallida típicamente no consume créditos, pero siempre verifica en tu panel de control de cuenta.

Para flujos de trabajo de producción, implementa:

• Lógica de reintentos con retroceso exponencial en fallos transitorios
• Sondeo de estado o manejo de webhook para finalización asincrónica
• Registro de errores para detectar problemas sistemáticos
• Monitoreo de saldo de créditos para alertar antes de quedarte sin créditos

Mejores Prácticas para Flujos de Trabajo Programáticos

1. Utiliza paquetes de referencia consistentes. Para trabajo de catálogo o serie, hash tus paquetes de referencia para que paquetes idénticos en solicitudes produzcan estilo más consistente.

2. Mantén plantillas de prompt simples. Los prompts programáticos deben generarse a partir de datos estructurados, no escritos a mano por llamada. Plantilla + campos de datos es el patrón correcto.

3. Cachea URLs de archivos de referencia. Si estás usando referencias basadas en URL, asegúrate de que las URLs sean estables y accesibles. Las URLs de S3 caducadas o archivos movidos fallarán en generaciones.

4. Maneja la seguridad del contenido apropiadamente. La plataforma tiene filtros de seguridad de contenido. Construye manejo elegante para solicitudes rechazadas por filtro en tu flujo de trabajo.

5. Registra metadatos de generación. Rastrea cada generación - prompt, conjunto de referencia, duración, créditos consumidos, URL de salida - en tu base de datos de aplicación. Esto hace debugging y reporte mucho más fácil.

Ejemplo de Flujo de Trabajo por Lotes

Pseudocódigo para un flujo de trabajo de generación de video de producto por lotes:

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 poller de seguimiento maneja la finalización y almacena la URL de salida contra el registro de producto.

Monitoreo y Control de Costos

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

• Alertas de presupuesto diario: Alerta cuando el gasto de API diario excede un umbral
• Límites por flujo de trabajo: Limita trabajos por lotes a un gasto máximo de créditos para prevenir automatización fuera de control
• Paneles de uso: Rastrea qué flujos de trabajo consumen más créditos
• Alertas de saldo de créditos: Recarga antes de quedarte sin créditos

Estas barreras de contención previenen sorpresas cuando escales automatización.

Paridad de Precios API vs Interfaz Web

Una pregunta común: ¿hay descuento para uso de API? No - API e interfaz web ambas cobran los mismos $0.3024 por segundo. La API tiene precio por el trabajo que hace, no por la interfaz que uses.

Donde los usuarios de alto volumen ahorran es en su selección de tier. Los usuarios de API pesados deben ejecutar en el Nivel máximo de $100 para el mejor valor por dólar.

Primeros Pasos con la API

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

La primera llamada a API puede estar activa dentro de una hora del registro para la mayoría de integraciones.

Lecturas Siguientes

Para el conjunto completo de características de Reference, lee Guía completa Seedance 2.0 Reference. Para el flujo de trabajo de interfaz web, consulta tutorial de consistencia de estilo. Para detalles estándar de API de Seedance 2.0, revisa Guía de API Seedance 2.0.

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