Skip to main content
ModelRunner
mmaudio avatar

MMAudio V2 API

mmaudio/v2

Add realistic, synchronized sound effects, Foley, ambience, or music to a silent video from a text prompt, returning the video with a new audio track.

0.001 per second of output video
OpenAPI

Model Input

Input

URL of the input video to add a generated audio track to.

Text description of the sound to generate (sound effects, Foley, ambience, or music).

Audio characteristics to steer away from.

Random seed for reproducible generation. Leave unset for a random result.

Min: 4 - Max: 50

Number of diffusion inference steps.

Min: 1 - Max: 30

Duration of the generated audio in seconds.

Min: 0 - Max: 20

Classifier-free guidance strength; higher follows the prompt more strictly.

Whether to mask away the input video's visual conditioning during generation.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

Loading
Generated in 9.342 seconds
Logs (1 lines)

Model Example Requests

Examples

Example output 1

MMAudio V2 API

MMAudio V2 is a video-to-video AI model by mmaudio. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.001 per second of video.

POST https://queue.modelrunner.run/mmaudio/v2

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/mmaudio/v2 \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "thunderstorm with heavy rain and distant rumbling thunder",
    "duration": 8,
    "num_steps": 25,
    "video_url": "https://media.modelrunner.ai/DzktjWqZAqCS1iWBKGhlm.mp4",
    "cfg_strength": 4.5,
    "mask_away_clip": false,
    "negative_prompt": "",
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/mmaudio/v2/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/mmaudio/v2/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("mmaudio/v2", {
  input: {
    "prompt": "thunderstorm with heavy rain and distant rumbling thunder",
    "duration": 8,
    "num_steps": 25,
    "video_url": "https://media.modelrunner.ai/DzktjWqZAqCS1iWBKGhlm.mp4",
    "cfg_strength": 4.5,
    "mask_away_clip": false,
    "negative_prompt": ""
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/mmaudio/v2",
    headers=headers,
    json={
      "prompt": "thunderstorm with heavy rain and distant rumbling thunder",
      "duration": 8,
      "num_steps": 25,
      "video_url": "https://media.modelrunner.ai/DzktjWqZAqCS1iWBKGhlm.mp4",
      "cfg_strength": 4.5,
      "mask_away_clip": false,
      "negative_prompt": ""
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
video_urlstring (uri)yesURL of the input video to add a generated audio track to.
promptstringyesText description of the sound to generate (sound effects, Foley, ambience, or music).
negative_promptstringnoAudio characteristics to steer away from. Default: "".
seedintegernoRandom seed for reproducible generation. Leave unset for a random result.
num_stepsintegernoNumber of diffusion inference steps. Default: 25.
durationnumbernoDuration of the generated audio in seconds. Default: 8.
cfg_strengthnumbernoClassifier-free guidance strength; higher follows the prompt more strictly. Default: 4.5.
mask_away_clipbooleannoWhether to mask away the input video's visual conditioning during generation. Default: false.

Machine-readable: OpenAPI schema · llms.txt

Use MMAudio V2 from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and MMAudio V2 becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint mmaudio/v2.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run mmaudio/v2 on ModelRunner to generate video”. MCP setup guide.

Model Details

Model Details

MMAudio V2 gives an existing or silent video a soundtrack: supply a video and a short text prompt describing the sound you want, and it generates a synchronized audio track — Foley, sound effects, ambience, or music — muxed back into the video and returned as a single MP4 with the new audio. The audio is timed to the on-screen action, so footsteps, splashes, engine noise, wind, or a musical bed line up with what's happening in the frame. Drive the result entirely from the `prompt`; use `negative_prompt` to steer away from sounds you don't want.

## Best for - Adding Foley and sound effects to silent footage so actions (footsteps, impacts, water, machinery) are audible and in sync - Laying down ambience or a room tone — rain, forest, crowd, wind — over B-roll and establishing shots - Generating a quick music bed or atmospheric score for a clip from a text description - Sound-designing animation, game capture, or AI-generated video that comes out silent

## Choose another model when - You want to re-sync a talking person's mouth to new speech — this generates ambient/effect audio, not lip-synced dialogue, so use a lip-sync model - You need spoken narration or dialogue from text — use a text-to-speech model, then mux it yourself - You want a standalone audio file rather than a video with the audio muxed in — use a dedicated text-to-audio model - You need to generate the video itself from a prompt or image — use a text-to-video or image-to-video model first, then add sound here

## Tips - Describe the sound you want concretely in `prompt` (\"gentle rain on leaves with distant thunder\", \"upbeat acoustic guitar\") rather than describing the visuals - Set `duration` (seconds, 1–30) to match your clip; cost is billed per output second - Raise `num_steps` for slightly cleaner audio at the expense of speed; raise `cfg_strength` to follow the prompt more strictly

## Advanced Configuration - `mask_away_clip` (default `false`) is a research toggle that masks away the input video's visual conditioning during generation; leave it off for normal video-conditioned audio.

To run via the ModelRunner JavaScript client: ```js import { modelrunner } from \"@modelrunner/client\";

const result = await modelrunner.subscribe(\"mmaudio/v2\", { input: { video_url: \"https://media.modelrunner.ai/your-silent-clip.mp4\", prompt: \"gentle ambient nature sounds with birds and wind\", duration: 8, }, }); ```