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

# Run a skill

> Run one skill by slug. Options come from GET /api/v1/skills. Credits are charged first.

`POST /api/v1/run/{skill}`

Run one skill. The slug is the same one the site uses — `/api/v1/run/background-remover`.

Option ids come from `GET /api/v1/skills`. An option the skill does not have is an error, not a default.

Credits come off before the provider is called and go back if the run fails. The response includes `credits_charged`. Text results — alt text, transcripts — ride back inline rather than as a file.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/run/background-remover \
  -H "Authorization: Bearer mm_live_…" \
  -F "file=@portrait.jpg" \
  -F "output=transparent"
```

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/run/alt-text \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hero.jpg", "options": {"tone": "plain"}}'
```

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/run/swap \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/campaign.jpg",
    "reference_url": "https://example.com/this-years-bottle.jpg",
    "prompt": "the bottle on the left",
    "options": {"mode": "object"}
  }'
```

| Field              | Type    | What it does                                             |
| ------------------ | ------- | -------------------------------------------------------- |
| `skill`            | path    | Slug, for example `background-remover`                   |
| `file`             | file    | Multipart field name `file`                              |
| `url`              | string  | A public URL instead of `file`                           |
| `job_id`           | string  | Reuse a previous upload                                  |
| `prompt`           | string  | Required when the skill needs one. Cap 2,000 characters  |
| `options`          | object  | Option ids from `GET /api/v1/skills`                     |
| `model`            | string  | Generator model id. See [Generators](/skills/generators) |
| `reference_url`    | string  | Second image for `swap` and `try-on`                     |
| `reference_job_id` | string  | Second image, already uploaded                           |
| `wait`             | boolean | Default `true`. Set `false` to poll                      |

A skill flagged `needs_reference` edits with a second image. Today that is **swap** and **virtual try-on**. Those two have no Workbench page.

To run several skills as a line, use [POST /api/v1/runs](/api/runs).