Cómo usar la API de Seedance 2.5: una guía rápida

Puedes ir de la clave de API al MP4 terminado en cuatro pasos: envía una solicitud POST autenticada, guarda el request_id, consulta el endpoint de resultados cada 10 a 20 segundos y descarga el video antes de que el enlace expire, a menudo dentro de 24 horas.

Si quisiera la versión corta, esto es lo que tendría en mente:

• Usa el endpoint correcto
  • seedance-2.5-text-to-video para prompts de texto
  • seedance-2.5-image-to-video para animar una URL de imagen pública
• Envía los encabezados correctos
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• Elige los ajustes principales de salida
  • resolution: 480p a 4K
  • aspect_ratio: como 16:9 o 9:16
  • duration: hasta 16 segundos
  • generate_audio: true para sonido y líneas habladas
• Consulta en lugar de reenviar
  • Comprueba predictions/{request_id}/result
  • Vigila queued, running, succeeded o failed
• Controla el costo
  • Empieza en 480p o 720p
  • Mantén el mismo seed
  • Vuelve a correr en 1080p o 4K solo cuando la toma se vea bien

También vigilaría los puntos de falla más comunes: 401 por un encabezado de autenticación incorrecto, 402 por falta de créditos, 429 por demasiados trabajos activos y 400 por JSON incorrecto o campos faltantes. En APIMart, los créditos se reservan cuando un trabajo comienza y se cobran solo si termina; los trabajos fallidos se reembolsan.

Si estás eligiendo entre modelos, Seedance 2.5 es la opción de gama alta en esta línea: hasta 16s, hasta 3,840 × 2,160 y hasta 50 entradas de referencia. Seedance 2.0 se sitúa en el medio, y Seedance 2 Mini es mejor para borradores de menor costo.

En resumen: si puedes hacer una solicitud POST válida y almacenar un ID, puedes ejecutar todo el flujo de trabajo. El resto es ajuste del prompt, consulta paciente y descargar el archivo antes de que la URL caduque. Para el posprocesamiento, puedes usar el AI Canvas para escalar o editar tus clips generados.

Paso 1: configura el acceso a APIMart y autentica las solicitudes

Cada solicitud de Seedance 2.5 necesita una clave de API válida y los encabezados correctos. Empieza ahí. Una vez que eso esté en su lugar, puedes pasar a los payloads de generación de video y al seguimiento de trabajos.

Crea y almacena tu clave de API de forma segura

Crea tu clave en el panel de la cuenta bajo Settings o API Keys. Luego guárdala en un archivo .env o una variable de entorno, no en el control de código fuente ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

Si la clave se pierde, revócala y crea una nueva ^[3]. Para las pruebas de integración, usa una clave sk_test_ separada para no tocar el uso de producción ^[3].

A continuación, incluye esa clave en cada solicitud con el encabezado Authorization.

Añade el encabezado Authorization correctamente

Envía las solicitudes a https://muapi.ai/api/v1/ con estos encabezados:

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

Un pequeño desliz de formato puede romper la solicitud. El más común es omitir el prefijo Bearer, o que falte el espacio antes de la clave ^[3][7]. Eso suele llevar a una respuesta 401 Unauthorized. Omitir Content-Type: application/json también puede hacer que la solicitud falle ^[3][7].

Con la autenticación lista, puedes pasar al payload de la solicitud de video.

Paso 2: construye una solicitud de generación de video con Seedance 2.5

Con tu clave de API configurada, el siguiente movimiento es construir un cuerpo de solicitud válido. Cada trabajo de Seedance 2.5 comienza con una solicitud POST a uno de dos endpoints, según desde qué estés partiendo. Usa https://muapi.ai/api/v1/seedance-2.5-text-to-video para generación solo con prompt, o https://muapi.ai/api/v1/seedance-2.5-image-to-video si estás animando una imagen de origen ^[1].

Elige el modo de entrada y los parámetros correctos

Tu modo de entrada determina la forma del payload. Texto a video solo necesita un prompt. Imagen a video también necesita un image_url que apunte a un archivo JPG, PNG o WEBP accesible públicamente y menor a 10 MB ^[1].

A partir de ahí, controlas la salida con unos cuantos campos principales:

• resolution: 480p, 720p, 1080p o 4K
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4 o 21:9
• duration: hasta 16 segundos en Muapi
• generate_audio: un booleano que activa sonido ambiente, efectos y diálogo sincronizados cuando se establece en true ^[1]

Una forma inteligente de trabajar es empezar en 480p con un seed fijo. Si el movimiento, el ritmo y el encuadre se ven bien, corre ese mismo seed de nuevo en 1080p o 4K para la versión final.

Para los prompts, usa este flujo: Sujeto → Acción → Cámara → Escenario → Ambiente ^[4]. Mantén el movimiento, la dirección de cámara y el ambiente dentro del propio prompt, y deja el seed sin cambios mientras pruebas variaciones. Si necesitas sincronización labial, coloca la línea hablada entre comillas dobles justo dentro de la cadena del prompt. Por ejemplo: she turns and says "We launch at dawn." En ese caso, asegúrate de que generate_audio esté establecido en true ^[1].

Una vez que el payload se vea bien, envía el trabajo y guarda el ID de solicitud devuelto. Lo necesitarás para la consulta.

Solicitudes de ejemplo en cURL, Postman, Python y JavaScript

Abajo está el mismo payload de texto a video mostrado en cuatro herramientas comunes.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - Crea una nueva solicitud POST, pega la URL del endpoint, añade Authorization: Bearer <your_key> y Content-Type: application/json en la pestaña Headers, luego pega el JSON de arriba en Body → raw → JSON. Haz clic en Send y guarda el request_id de la respuesta.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

Unos cuantos errores pueden hacerte tropezar rápido. No envíes un image_url que no sea accesible públicamente. No apiles direcciones de cámara que se contradigan entre sí en el mismo prompt. Y en el modo imagen a video, no describas un sujeto de nuevo si la imagen de origen ya lo define ^[1].

Después del envío, consulta el estado del trabajo hasta que la URL del MP4 esté lista.

Cuándo usar Seedance 2.5 en la línea de modelos de video de APIMart

Esta comparación rápida te ayuda a elegir el modelo correcto antes de empezar a ajustar prompts o subir la resolución. Seedance 2.5 te da 4K nativo, hasta 50 entradas de referencia y soporte para clips más largos. Seedance 2 Mini es mejor para borradores ligeros, mientras que Seedance 2.0 se sitúa en el medio como la opción de uso general ^[1][9][4].

Si el proyecto es un entregable final - como un video de lanzamiento de producto, una secuencia cinematográfica de marca o cualquier cosa destinada a la difusión - Seedance 2.5 es la mejor opción. Para proyectos que requieren 高品質音声付きAI動画生成, Veo 3.1 de Google es otro contendiente sólido. Si todavía estás probando ideas, empieza con Mini para comprobar el movimiento y fijar el encuadre a menor costo, luego sube a 2.5 para el render final.

Paso 3: envía el trabajo, sigue el estado y lee la respuesta

Una vez que envías la solicitud POST, la API devuelve un request_id. Guárdalo. Usarás ese ID para comprobar el trabajo más tarde porque la generación corre de forma asíncrona.

Maneja trabajos asíncronos desde la creación hasta la finalización

Después de enviar el trabajo, el siguiente paso es simple: consulta hasta que el video final esté listo.

Envía una solicitud GET a https://muapi.ai/api/v1/predictions/{request_id}/result. Espera alrededor de 10 segundos después del envío antes de la primera consulta, luego comprueba de nuevo cada 10–20 segundos. Si consultas más a menudo que cada 5 segundos, puedes toparte con límites de tasa ^[1][3].

Cada respuesta incluye un campo status. Ese campo te dice qué está pasando y qué deberías hacer a continuación:

Una vez que el trabajo llega a succeeded, toma la URL de salida antes de que expire.

Lee los campos de salida y guarda los resultados

Cuando el estado cambia a succeeded, lee el payload de salida y almacena el resultado.

Una respuesta exitosa incluye video_url. También puede incluir last_frame_url si lo pediste. Guarda video_url, el opcional last_frame_url y metadatos como seed, duration, resolution, aspect_ratio y usage. Esos datos importan para la facturación y para reproducir la misma corrida más tarde ^[11][13].

Las URL de salida a menudo expiran dentro de 24 horas, así que descarga el archivo a tu propio almacenamiento de inmediato ^[11][12][13]. Si un trabajo falla, registra error.code y error.message. Y si la falla está vinculada a comprobaciones de seguridad, no lo reintentes automáticamente ^[2][11][12].

Paso 4: soluciona errores, controla el costo y cierra

Arregla errores de autenticación, validación y límite de tasa

Después de enviar un trabajo y consultar los resultados, unas cuantas comprobaciones simples pueden evitar que las corridas de producción se descarrilen. La mayoría de las fallas de Seedance tienden a aparecer del mismo puñado de formas.

Para los activos de referencia, asegúrate de que la URL sea pública, el archivo sea JPG, PNG o WEBP, y se mantenga bajo el límite de tamaño listado ^[12][4].

Reduce costos y mejora la fiabilidad

Una vez que el manejo de errores está listo, el siguiente paso es simple: prueba barato, luego renderiza en grande.

Empieza tu prompt en 480p o 720p. Eso te da una forma de bajo costo de comprobar el encuadre, el movimiento y si el prompt está haciendo lo que quieres. Si la toma se ve bien, vuelve a correr el mismo valor de seed en 4K para la salida final ^[1][4].

La duración del clip también importa. Los videos más cortos cuestan menos, así que mantén la duración al mínimo que aún haga el trabajo ^[1][10].

También hay una forma sigilosa en la que los equipos queman dinero: envíos duplicados tras un tiempo de espera de red. Un arreglo limpio es hacer un hash del prompt, el ID del modelo y las URL de medios antes de cada solicitud POST. Si ese hash ya se mapea a un ID de tarea, omite el nuevo envío por completo ^[11]. Y una vez que un trabajo llega a succeeded, guarda el archivo terminado en almacenamiento duradero para que no tengas que depender del registro de la tarea más tarde ^[12][11].

Conclusión: de los documentos de la API a la generación de video funcional

Con la autenticación, los payloads, la consulta y el manejo de errores en su lugar, ahora tienes un flujo de trabajo completo de Seedance 2.5 en APIMart.

Preguntas frecuentes

¿Cuánto tarda Seedance 2.5 en terminar un video?

Seedance 2.5 puede generar un clip de video continuo de hasta 30 segundos de duración. Los documentos, sin embargo, no listan un tiempo exacto de finalización.

La API corre de forma asíncrona. Envías una tarea, obtienes un ID de tarea, y luego consultas el endpoint de estado o esperas un webhook para obtener el video terminado.

El tiempo de procesamiento puede variar según cosas como la resolución y la complejidad de la escena.

¿Qué debería hacer si mi URL de video expira antes de descargarla?

Si tu URL de video expira antes de que la descargues, no podrás obtener el archivo desde ese enlace. Seedance mantiene estas URL temporales activas durante 24 horas.

El movimiento seguro es simple: copia el video a tu propio almacenamiento de objetos seguro tan pronto como la tarea aparezca como completada. Como la API corre de forma asíncrona y no conserva la salida para siempre, tu aplicación debería obtener el video y moverlo a almacenamiento a largo plazo de inmediato.

¿Cómo puedo evitar cargos duplicados al reintentar solicitudes fallidas?

Usa el manejo idempotente de solicitudes vinculado a tus propios registros de trabajo duraderos, no solo al cliente HTTP.

Antes de enviar nada, construye un hash de solicitud determinista a partir de entradas como el prompt, el ID del modelo, los ID de activos y el identificador del usuario. Luego guarda ese hash con un estado submitting en tu propia base de datos.

Si ese mismo hash aparece de nuevo, devuelve el trabajo existente en lugar de crear uno nuevo.

Una vez que hayas almacenado un ID de trabajo del proveedor, no envíes la solicitud de nuevo. Simplemente reanuda la consulta con ese ID de trabajo.