> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamonster.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API quickstart

> Five minutes from no key to a live run: a free test key, a first call, a dry run for the price, a recipe by name, a webhook, then a live key.

Six steps, and nothing is charged until the last one. Every example has a tab for curl, TypeScript, Python and MCP.

**1. Mint a test key**

Sign in, open [mediamonster.app/keys](https://mediamonster.app/keys), press **New key** and pick **Test**. You get a key that starts `mm_test_`.

A test key goes through every check a live key does — the file is fetched and measured, the options and the plan are checked — then charges nothing and hands back a stand-in file of the right kind at once. Every plan gets test keys, Cyclops included. See [Test mode](https://docs.mediamonster.app/api/authentication.md#test-mode).

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
export MEDIAMONSTER_API_KEY=mm_test_...
```

**2. Make your first call**

Remove the background from a photo. Send a public link to the file; the call waits for the result.

```bash curl theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://mediamonster.app/api/v1/run/background-remover \
  -H "Authorization: Bearer $MEDIAMONSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/photo.jpg" }'
```

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import { Mediamonster } from "@mediamonster/sdk";

const mm = new Mediamonster({ apiKey: process.env.MEDIAMONSTER_API_KEY });

const job = await mm.skills.run("background-remover", {
  url: "https://example.com/photo.jpg",
});
console.log(job.outputs[0].url);
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
from mediamonster import Mediamonster

mm = Mediamonster()  # reads MEDIAMONSTER_API_KEY

job = mm.skills.run("background-remover", url="https://example.com/photo.jpg")
print(job["outputs"][0]["url"])
```

```json MCP theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "name": "run_skill",
  "arguments": {
    "skill": "background-remover",
    "url": "https://example.com/photo.jpg"
  }
}
```

The answer is the job: `status: "complete"`, `livemode: false`, `credits_charged: 0`, and `outputs` with a signed `url` that lasts ten minutes. Swap `example.com` for your file, or send it as a multipart `file`, an `upload_id` from a [direct upload](https://docs.mediamonster.app/api/uploads.md), or a Vault `asset_id`.

Every skill has a page with its options and this call already written: see [Skill reference](https://docs.mediamonster.app/skills/reference/background-remover.md).

**3. Price a run before you spend**

Add `dry_run=true`. The call makes every check and measures the file, then answers with the price, step by step, and your balance after it — without running. Use it with a live key before anything long.

```bash curl theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl "https://mediamonster.app/api/v1/run/captions?dry_run=true" \
  -H "Authorization: Bearer $MEDIAMONSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/clip.mp4", "options": { "style": "karaoke" } }'
```

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const quote = await mm.skills.run("captions", {
  url: "https://example.com/clip.mp4",
  options: { style: "karaoke" },
  dry_run: true,
});
console.log(quote.credits, quote.breakdown);
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
quote = mm.skills.run(
    "captions",
    url="https://example.com/clip.mp4",
    options={"style": "karaoke"},
    dry_run=True,
)
print(quote["credits"], quote["breakdown"])
```

```json MCP theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "name": "run_skill",
  "arguments": {
    "skill": "captions",
    "url": "https://example.com/clip.mp4",
    "options": { "style": "karaoke" },
    "dry_run": true
  }
}
```

See [Dry runs](https://docs.mediamonster.app/api/run-skill.md#dry-runs).

**4. Run a recipe by name**

A recipe is a named sequence of steps; each step is handed what the step above made. Run a ready-made one by its slug — `tiktok-ready` reframes a video to 9:16, burns in captions and picks a cover frame.

```bash curl theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://mediamonster.app/api/v1/runs \
  -H "Authorization: Bearer $MEDIAMONSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipe": "tiktok-ready", "url": "https://example.com/clip.mp4" }'
```

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const run = await mm.recipes.run("tiktok-ready", {
  url: "https://example.com/clip.mp4",
});
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
run = mm.recipes.run("tiktok-ready", url="https://example.com/clip.mp4")
```

```json MCP theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "name": "run_recipe",
  "arguments": { "recipe": "tiktok-ready", "url": "https://example.com/clip.mp4" }
}
```

`GET /api/v1/recipes` lists every ready-made recipe, and yours with a key. To change a setting, send `steps` inline instead. See [Recipe reference](https://docs.mediamonster.app/recipes/tiktok-ready.md) and [Run a recipe](https://docs.mediamonster.app/api/runs.md).

**5. Get a webhook when it finishes**

Long runs shouldn't hold a connection open. Send `wait: false` and a `webhook_url`, and the call answers `202` at once; the result is POSTed to you when it settles, signed with `Mediamonster-Signature`.

```bash curl theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://mediamonster.app/api/v1/runs \
  -H "Authorization: Bearer $MEDIAMONSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "podcast-to-clips",
    "url": "https://example.com/episode.mp3",
    "wait": false,
    "webhook_url": "https://hooks.example.com/mediamonster"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
// In your receiver: check the signature before trusting the body.
const event = mm.webhooks.verify(
  rawBody,
  request.headers.get("mediamonster-signature"),
  process.env.MEDIAMONSTER_WEBHOOK_SECRET,
);
if (event.type === "run.completed") console.log(event.data.outputs);
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
# In your receiver: check the signature before trusting the body.
event = mm.webhooks.verify(
    raw_body,
    request.headers["Mediamonster-Signature"],
    os.environ["MEDIAMONSTER_WEBHOOK_SECRET"],
)
if event["type"] == "run.completed":
    print(event["data"]["outputs"])
```

```bash CLI theme={"theme":{"light":"github-dark","dark":"github-dark"}}
# Forward webhooks to your laptop while you build.
mm listen --forward http://localhost:3000/webhooks
```

Test runs are delivered too, marked `"livemode": false`, so you can build the receiving end for free. For a standing address, add a [webhook endpoint](https://docs.mediamonster.app/api/webhooks.md#webhook-endpoints) instead of passing a URL each time. Or skip webhooks and poll `poll_url` — `mm.runs.wait(id)` does it for you.

**6. Switch to a live key**

Mint a **Live** key on the same page — `mm_live_` — and swap it in. The calls don't change. Runs now spend [credits](https://docs.mediamonster.app/getting-started/credits-and-plans.md), call the real models and hand back real files; a failed skill's credits go back.

Before you ship:

* Give the key only the [scopes](https://docs.mediamonster.app/api/authentication.md#scopes) it needs, and an [address allow-list](https://docs.mediamonster.app/api/authentication.md#address-allow-list) if it runs from fixed servers.
* Send an `Idempotency-Key` on every `POST`, so a retry after a timeout never runs twice. See [Idempotency](https://docs.mediamonster.app/api/overview.md#idempotency).
* Watch the `X-RateLimit-*` headers. See [Rate limits](https://docs.mediamonster.app/api/authentication.md#rate-limits).
* Keep [Errors](https://docs.mediamonster.app/api/errors.md) handy: every error carries a `code`, a `request_id` and a `doc_url` to its fix.

## Next

> [card] [SDKs and tools](https://docs.mediamonster.app/api/sdks.md)
>
> TypeScript, Python, the `mm` CLI, and Postman and Bruno collections.

> [card] [MCP](https://docs.mediamonster.app/mcp.md)
>
> Hand the whole catalogue to Claude, ChatGPT, Cursor or VS Code.

> [card] [Skill reference](https://docs.mediamonster.app/skills/reference/background-remover.md)
>
> Every skill: options, price, where it can sit in a recipe, and the call.

> [card] [Status](https://docs.mediamonster.app/api/status.md)
>
> Live health of every component, as a page and as JSON.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.