Referencia de la API de Muse Video

Límites en resumen

Todo lo que Muse Video acepta y todo lo que no, en una sola tabla. Revísala antes de construir sobre el modelo: solo 720p, solo horizontal o vertical, y un primer fotograma o hasta cuatro imágenes de referencia, pero no ambas cosas.

Los valores y campos no admitidos devuelven un 400 antes de crear la tarea y no cuestan nada; los mensajes exactos están en Errores, más abajo.

No todas las peticiones tienen éxito

Tres modos de entrada

Un único id de modelo y un único endpoint; el modo depende de las imágenes que envíes. Los tres cuestan lo mismo.

Un primer fotograma y las imágenes de referencia no pueden ir en la misma petición; enviar ambos devuelve un 400. Un array de imágenes (images, image_urls o reference_image_urls) siempre se trata como imágenes de referencia, aunque tenga un solo elemento; para enviar un primer fotograma, usa el campo de imagen única image_url.

Inicio rápido

Todas las peticiones llevan la clave API en la cabecera:

Authorization: Bearer YOUR_API_KEY

Texto a video

# Muse Video — text-to-video. model and prompt are required; everything else is optional.
# duration: whole seconds 4-30 (default 5). aspect_ratio: 16:9 (default, 1280x720) or 9:16 (720x1280).
# Billed $0.037 per requested second: this 10 s request is $0.37.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "An orange cat stretches on a sunny windowsill, sunlight pours in, the camera slowly pushes in",
    "duration": 10,
    "aspect_ratio": "16:9"
  }'

# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-video" } }

# Poll every 10-15 s until completed (result files are kept 30 days)
curl "https://api.apimodels.app/v1/video/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed",
#     "resultUrls": ["https://r2.apimodels.app/videos/clxxx.mp4"] } }

Imagen a video (primer fotograma)

Mismo id de modelo y mismo endpoint: añade una imagen de primer fotograma. Cuesta lo mismo que texto a video. El ejemplo de Node.js usa los nombres de campo al estilo OpenAI seconds, size e input_reference, que también funcionan.

# Muse Video — image-to-video: the same request plus ONE first-frame image.
# PNG, JPEG or WebP, up to 20 MB, as a public URL or a base64 data URI.
# Same price as text-to-video. Use an image with the same orientation as the clip.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "She turns toward the window and smiles, the curtains drift in the breeze, slow push-in",
    "image_url": "https://example.com/first-frame-portrait.jpg",
    "duration": 6,
    "aspect_ratio": "9:16"
  }'

# first_frame_url, image or input_reference work in place of image_url. Do not put a first frame in image_urls:
# an image array (images, image_urls, reference_image_urls) always means reference images, see the next example.
# Poll the returned taskId exactly as in the text-to-video example.

Imágenes de referencia (hasta 4)

Para mantener a la misma persona o el mismo elemento principal en varios clips, pon de 1 a 4 imágenes de referencia en images (también valen image_urls y reference_image_urls). El modelo conserva la cara y el aspecto, pero el clip no arranca desde ninguna de ellas. Menciona en el prompt "la misma persona de las imágenes de referencia" y luego describe la escena nueva. No añadas un primer fotograma a la misma petición; el precio es el mismo que el de texto a video.

# Muse Video — reference images: 1 to 4 images of the same person or subject in "images".
# The model keeps the face and look from them, but the clip does not start from any of them.
# image_urls and reference_image_urls work in place of images. Do not add a first frame to the same request.
# PNG, JPEG or WebP, up to 20 MB each, public URLs or base64 data URIs. Same price as text-to-video.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "The same young woman from the reference images walks barefoot along a beach at sunset, smiling back at the camera, handheld vertical shot",
    "images": [
      "https://example.com/ref-1.jpg",
      "https://example.com/ref-2.jpg",
      "https://example.com/ref-3.jpg",
      "https://example.com/ref-4.jpg"
    ],
    "duration": 5,
    "aspect_ratio": "9:16"
  }'

# Poll the returned taskId exactly as in the text-to-video example.

Una tarea pasa por pending → processing → completed o failed. Con completed, data.resultUrls[0] es el MP4; con failed, el motivo está en data.failMsg y no se cobra nada. Los clips de hasta 10 segundos suelen tardar de uno a dos minutos, y los de 15 a 30 segundos, de tres a siete; nuestras peticiones de prueba de 4 segundos en el lanzamiento terminaron en unos 1.5 minutos. Basta con consultar cada 10-15 segundos.

Callback (callback_url)

Para no tener que consultar, pasa callback_url en la petición de creación. Cuando la tarea llega a completed o failed, enviamos un HTTP POST (JSON) a esa URL. Si la entrega falla, se reintenta con esperas crecientes durante hasta 30 minutos, hasta que tu endpoint responda con un 2xx. La URL debe ser accesible públicamente; localhost y las direcciones privadas devuelven un 400 al crear la tarea. La consulta sigue funcionando igual.

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "muse-video",
    "state": "completed",                 // or "failed"
    "param": "<JSON string>",             // your request, JSON.parse once
    "resultJson": "<JSON string> | null", // {"resultUrls": ["https://...mp4"]}, JSON.parse once
    "failCode": null,
    "failMsg": null
  }
}

Parámetros

No hay entrada de último fotograma, video de referencia ni audio de referencia, ni negative_prompt ni seed: si envías alguno, recibes un 400 en lugar de que se ignore en silencio. Tampoco hay parámetros de control de cámara; describe los movimientos de cámara en el prompt.

La duración del clip va por escalones

Si pides 5, 6, 8, 10, 15, 20, 25 o 30 segundos, el clip dura exactamente eso; cualquier otro número entero sube al siguiente escalón, así que el clip nunca es más corto que lo que pagaste. Se factura por los segundos que pides, no por la duración del clip.

Tamaños y salida

• Horizontal — aspect_ratio "16:9" o size "1280x720" → 1280×720. Es el valor por defecto.
• Vertical — aspect_ratio "9:16" o size "720x1280" → 720×1280.
• No disponible — Cuadrado, 1080p y cualquier otro tamaño: un 400 antes de crear la tarea.
• Salida — MP4 H.264, 24 fps, 720p. Los archivos de resultado se guardan 30 días.
• Sonido — Meta describe Muse Video como un modelo que genera el sonido junto con la imagen. En nuestras pruebas de lanzamiento, dos peticiones de 4 segundos devolvieron dos clips de 5.0 segundos: el horizontal traía una pista de audio AAC y el vertical llegó sin sonido. Si tu flujo necesita audio, comprueba que cada clip tenga pista de audio. El sonido no se puede desactivar: generate_audio: false devuelve un 400.

Primer fotograma e imágenes de referencia

Primer fotograma

• Una sola imagen, y el clip arranca desde ella. Envíala como image_url (también valen first_frame_url, image o input_reference).
• Funciona mejor cuando la imagen tiene la misma orientación que el clip: una imagen horizontal con 16:9 y una vertical con 9:16.
• Solo primer fotograma, sin último fotograma: enviar last_frame_url devuelve un 400.

Imágenes de referencia

• De 1 a 4 imágenes en el array images (también valen image_urls y reference_image_urls); más de 4 devuelve un 400. Un array de imágenes siempre se trata como imágenes de referencia, nunca como primer fotograma, aunque tenga un solo elemento.
• El modelo mantiene la persona, el elemento principal o el estilo (coherencia de personaje), pero el clip no arranca desde ninguna de ellas; la escena sale del prompt.
• No pueden ir en la misma petición que un primer fotograma; enviar ambos devuelve un 400.

Cada imagen

• Una URL que cualquiera pueda descargar directamente, o un data URI en base64 (data:image/png;base64,...). Si es un archivo local, también puedes subirlo con la Files API y usar la URL pública que devuelve.
• PNG, JPEG o WebP, hasta 20 MB cada una. Un primer fotograma en otro formato, o de más de 20 MB, hace fallar la tarea al ejecutarse, sin ningún cobro.

Precios

Se factura por los segundos solicitados: una petición de 4 segundos cuesta $0.148 y devuelve un clip de 5 segundos. El primer fotograma y las imágenes de referencia no cuestan nada extra: los tres modos tienen el mismo precio. Una petición rechazada con un 400 no crea tarea y no cuesta nada; las generaciones fallidas no se cobran.

Errores

Los problemas de parámetros vuelven de forma síncrona como un 400 al crear la tarea ({"code": 400, "msg": "..."}): no se crea ninguna tarea y no se cobra nada. Los textos de msg de abajo son la redacción actual; el nombre de campo entre paréntesis es el que enviaste.

• 401: falta la clave API o no es válida.
• 402: el saldo no cubre los segundos solicitados (segundos × $0.037).
• Un primer fotograma en un formato no admitido termina la tarea en failed con data.failMsg first-frame image must be PNG, JPEG or WebP; un archivo de más de 20 MB da first-frame image is larger than 20 MB. Ninguno de los dos se cobra.
• Los demás fallos durante la generación (contenido rechazado por el modelo, un error temporal de generación, tiempo agotado o un clip terminado que se descarta por orientación o duración incorrectas) también terminan en failed con el motivo en data.failMsg, y no se cobran. Consulta "No todas las peticiones tienen éxito", más arriba.

Consejos

• Escribe tres cosas en el prompt: qué es el sujeto, cómo se mueve y cómo se mueve la cámara. Por ejemplo: "un gato naranja se estira en el alféizar, entra la luz del sol, la cámara se acerca despacio". No hay parámetros de control de cámara, así que el prompt es la única forma de dirigirla.
• Haz coincidir la orientación: un primer fotograma horizontal con 16:9 y uno vertical con 9:16.
• Para un personaje recurrente, usa imágenes de referencia: envía el mismo juego de 1 a 4 fotos en cada clip (mejor si muestran ángulos, expresiones o gestos distintos), escribe en el prompt "la misma persona de las imágenes de referencia" y luego describe la escena nueva. El primer fotograma sirve para "empezar desde esta imagen"; las referencias, para "la misma persona en otro lugar".
• Pide uno de los escalones exactos (5, 6, 8, 10, 15, 20, 25 o 30 segundos) para que la duración del clip sea la que espera tu montaje.
• Los clips de más de 10 segundos cambian de plano hacia los segundos 10 y 20, así que escribe un prompt largo por tramos: "Primeros 10 segundos: …, después: …".
• Si tu flujo necesita audio, comprueba primero que cada clip tenga pista de audio, por ejemplo con ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 clip.mp4: imprime aac si hay pista y nada si el clip no tiene sonido.
• Los archivos de resultado se borran a los 30 días, así que descárgalos o guárdalos en otro sitio a tiempo.
• Usa solo imágenes (primer fotograma o referencias) sobre las que tengas derechos y, si aparece alguien, con su permiso.

Pruébalo en el Playground.

Relacionado