Muse Video API reference

Limits at a glance

Everything Muse Video accepts and everything it does not, in one table. Check it before you build on the model: 720p only, landscape or portrait only, and either one first frame or up to four reference images.

Unsupported values and fields return a 400 before a task is created and cost nothing; the exact messages are listed under Errors below.

Not every request succeeds

Three input modes

One model id and one endpoint; the mode follows from the images you send. All three cost the same.

A first frame and reference images cannot go in the same request; sending both returns a 400. An image array (images, image_urls or reference_image_urls) always means reference images, even with a single item; to send a first frame, use the single-image field image_url.

Quick start

Every request carries the API key in the header:

Authorization: Bearer YOUR_API_KEY

Text-to-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"] } }

Image-to-video (first frame)

Same model id, same endpoint: add one first-frame image. It costs the same as text-to-video. The Node.js sample uses the OpenAI-style field names seconds, size and input_reference, which work too.

# 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.

Reference images (up to 4)

To keep the same person or subject across clips, put 1 to 4 reference images in images (image_urls and reference_image_urls also work). The model keeps the face and look from them, but the clip does not start from any of them. Name "the same person from the reference images" in the prompt, then describe the new scene. Do not add a first frame to the same request; the price is the same as text-to-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.

A task moves through pending → processing → completed or failed. On completed, data.resultUrls[0] is the MP4; on failed, the reason is in data.failMsg and nothing is charged. Clips up to 10 seconds usually take one to two minutes, 15 to 30 seconds usually three to seven; our 4-second launch test requests finished in about 1.5 minutes. Polling every 10-15 seconds is plenty.

Callback (callback_url)

To skip polling, pass callback_url in the create request. When the task reaches completed or failed we send an HTTP POST (JSON) to it. Failed deliveries are retried with backoff for up to 30 minutes, until your endpoint returns a 2xx. The URL must be publicly reachable; localhost and private addresses return a 400 at create time. Polling keeps working either way.

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

Parameters

There is no last-frame, reference-video or reference-audio input, no negative_prompt and no seed: sending any of them returns a 400 instead of being silently ignored. There are no camera-control parameters either; describe camera moves in the prompt.

Clip length comes in steps

Requests of 5, 6, 8, 10, 15, 20, 25 or 30 seconds come back exactly that long; any other whole number rounds up to the next step, so a clip is never shorter than what you paid for. Billing follows the seconds you request, not the clip length.

Sizes and output

• Landscape — aspect_ratio "16:9" or size "1280x720" → 1280×720. This is the default.
• Portrait — aspect_ratio "9:16" or size "720x1280" → 720×1280.
• Not available — Square, 1080p and any other size: a 400 before a task is created.
• Output — H.264 MP4, 24 fps, 720p. Result files are kept for 30 days.
• Sound — Meta describes Muse Video as generating sound together with the picture. In our launch tests, two 4-second requests came back as two 5.0-second clips: the landscape one carried an AAC audio track, the portrait one was silent. If your pipeline needs audio, check each clip for an audio track. Sound cannot be turned off: generate_audio: false returns a 400.

First frame and reference images

First frame

• Exactly one image, and the clip starts from it. Send it as image_url (first_frame_url, image or input_reference also work).
• It works best when the image has the same orientation as the clip: a landscape image with 16:9, a portrait image with 9:16.
• First frame only, no last frame: sending last_frame_url returns a 400.

Reference images

• 1 to 4 images in the images array (image_urls and reference_image_urls also work); more than 4 returns a 400. An image array is always treated as reference images, never as a first frame, even with a single item.
• The model keeps the person, subject or style from them (character consistency), but the clip does not start from any of them; the scene comes from the prompt.
• They cannot go in the same request as a first frame; sending both returns a 400.

Every image

• A URL anyone can download directly, or a base64 data URI (data:image/png;base64,...). For a local file you can also upload it with the Files API and use the public URL it returns.
• PNG, JPEG or WebP, up to 20 MB each. A first frame in another format, or over 20 MB, fails the task when it runs, and nothing is charged.

Pricing

Billed on the requested seconds: a 4-second request costs $0.148 and returns a 5-second clip. A first frame or reference images cost nothing extra: all three modes have the same price. A request rejected with a 400 creates no task and costs nothing; failed generations are not charged.

Errors

Parameter problems come back synchronously as a 400 at creation ({"code": 400, "msg": "..."}): no task is created and nothing is charged. The msg strings below are the current wording; the field name in brackets is the one you actually sent.

• 401: the API key is missing or invalid.
• 402: the balance does not cover the requested seconds (seconds × $0.037).
• A first frame in the wrong format ends the task in failed with data.failMsg first-frame image must be PNG, JPEG or WebP; a file over 20 MB gives first-frame image is larger than 20 MB. Neither is charged.
• Other failures during generation (content refused by the model, a temporary generation error, a timeout, or a finished clip discarded for the wrong orientation or length) also end in failed with the reason in data.failMsg, and are not charged. See "Not every request succeeds" above.

Tips

• Write three things into the prompt: what the subject is, how it moves, and how the camera moves. For example: "an orange cat stretches on a windowsill, sunlight pours in, the camera slowly pushes in". There are no camera-control parameters, so the prompt is the only way to direct the camera.
• Match the orientation: a landscape first frame with 16:9, a portrait one with 9:16.
• For a recurring character, use reference images: send the same set of 1 to 4 photos with every clip (ideally different angles, expressions or gestures), write "the same person from the reference images" in the prompt, then describe the new scene. A first frame means "start from this picture"; reference images mean "the same person, somewhere new".
• Request one of the exact steps (5, 6, 8, 10, 15, 20, 25 or 30 seconds) so the clip length matches what your edit expects.
• Clips over 10 seconds switch shots around the 10-second and 20-second marks, so write a long prompt segment by segment: "First 10 seconds: …, then: …".
• If your pipeline needs audio, check each clip for an audio track first, for example with ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 clip.mp4: it prints aac when there is a track and nothing when the clip is silent.
• Result files are deleted after 30 days, so download or re-host them promptly.
• Only use images, first frames and reference images alike, that you have the rights to use, and the permission of anyone pictured.

Try it in the Playground.

Related