# VideoResolver: agent guide

VideoResolver downloads public videos and audio from a link (YouTube, X, LinkedIn, Instagram, TikTok, Facebook, Reddit, Twitch and more) and returns a private download link. Human-readable documentation: https://www.videoresolver.com/docs

## Connect

- MCP endpoint (Streamable HTTP, stateless JSON): `https://www.videoresolver.com/api/mcp`
- Auth: `Authorization: Bearer <API_KEY>`, or `?key=<API_KEY>` for clients that only accept a URL
- Get a key: https://www.videoresolver.com/app#api (one key per tool, revocable at any time)

Claude Code:

```bash
claude mcp add --transport http videoresolver https://www.videoresolver.com/api/mcp --header "Authorization: Bearer <API_KEY>"
```

Any client that reads an `mcpServers` JSON config:

```json
{ "mcpServers": { "videoresolver": { "url": "https://www.videoresolver.com/api/mcp", "headers": { "Authorization": "Bearer <API_KEY>" } } } }
```

## Tools

| Tool | Arguments | Returns |
| --- | --- | --- |
| `get_account` | none | plan, plan_name, credits, renews_at, manage_url |
| `get_media_info` | `url` | title, channel, platform, thumbnail, duration_seconds, credits_required |
| `download_media` | `url`, `format?`, `quality?` | download_id, status, progress and the media details |
| `get_download` | `download_id` | status, progress, download_url when ready |
| `list_downloads` | `limit?` | items: the downloads, as get_download returns them |

## Recommended flow

1. If the user wants to know first, call `get_media_info`: it shows the title and the cost in credits, for free.
2. Call `download_media`. Only ask for `format` or `quality` when the user wants them.
3. Call `get_download` about every 10 seconds until `status` is `ready` (or `failed`: nothing is charged then).
4. Give the user `download_url`. It is valid for 1 hour; call `get_download` again for a fresh link while the file is kept (48 hours).

When a tool fails, its text ends with the error code in parentheses, e.g. `(insufficient_credits)`: then tell the user how many credits are missing and send them to https://www.videoresolver.com/app.

## Formats and qualities

Downloads cost 1 credit per started minute of media. Choosing anything other than `mp4` at `best` needs a paid plan or credits from a pack (`paid_option` otherwise).

| Format | Kind | Qualities |
| --- | --- | --- |
| `mp4` | video | best, 1080p, 720p, 480p, 360p |
| `mp3` | audio | best, 320kbps, 128kbps |
| `m4a` | audio | best, 320kbps, 128kbps |
| `wav` | audio | best |

## Download statuses

| Status | Meaning |
| --- | --- |
| `analyzed` | Looked up but not started (e.g. after a 402). Not charged. |
| `processing` | Charged and downloading; progress goes from 0 to 98. |
| `storing` | Downloaded, being saved to private storage. |
| `ready` | download_url is set: a signed link valid for 1 hour. |
| `failed` | Couldn't be downloaded; the credits were refunded. |
| `expired` | The file was deleted after 48 hours. |

## Errors

| HTTP | Code | When |
| --- | --- | --- |
| 400 | `invalid_url` | The url is missing or isn't an http(s) link. |
| 400 | `invalid_option` | The format or quality isn't supported. Qualities depend on the format (mp4: best, 1080p, 720p, 480p, 360p; mp3: best, 320kbps, 128kbps; m4a: best, 320kbps, 128kbps; wav: best). |
| 401 | `unauthorized` | The API key is missing, revoked or invalid. |
| 402 | `insufficient_credits` | The balance doesn't cover the media. The message says how many credits are missing; nothing is charged. |
| 403 | `paid_option` | Anything other than mp4 at best quality needs a paid plan or credits from a pack. |
| 404 | `not_found` | No download with this id on your account. |
| 422 | `unreadable_video` | The media is private, deleted, age-restricted or from an unsupported site. |
| 422 | `unsupported_live` | Live streams and media without a duration can't be downloaded. |
| 429 | `rate_limited` | More than 60 lookups in an hour, or too many at once. Retry later. |
| 502 | `unreadable_video` | The media couldn't be read right now. Retry in a moment. |
| 500 | `generic` | Unexpected error on our side. Retry in a moment. |

Lookups (`get_media_info`, `download_media`) are limited to 60 per hour per account.

## REST API

The same key works with the REST API: `https://www.videoresolver.com/api/v1`. OpenAPI schema: https://www.videoresolver.com/openapi.json