# FastSaverAPI - full reference

Base URL: https://api.fastsaver.io/v1
Auth: every request carries the header `X-Api-Key: <your key>`.
MCP server for AI assistants: https://mcp.fastsaver.io/mcp (see "MCP server" at the end).

Every JSON body the API sends has `ok`, except the 422 for a missing
parameter. Success is 200 with `ok: true`; a failure carries `ok: false`
and a `detail` string. Read `ok`, not the status code. Running out of
credits is a 400 - there is no 402.

Status codes (the same table as https://api.fastsaver.io/docs/errors):

- 200: it worked
- 400: everything else, including running out of credits
- 401: the key is unknown (detail: "Invalid API key")
- 422: a required parameter is missing - this body has no `ok`
- 429: you are over your requests-per-minute limit (detail: "Rate limit exceeded. Please try again in a few seconds or contact support to increase your limit.")
- 500: our bug - the body carries a `request_id`, send it to support (detail: "internal error")
- 503: we are overloaded - retry after `Retry-After` (1 second), it costs nothing (detail: "Service is busy. Please retry in a moment.")

A 5xx without a JSON body comes from a proxy or from load shedding, not
from the API. Treat it like a 503: wait, then retry.

A failed fetch still costs 0.1 credit.

## Plans

| plan | price | credits | requests/minute |
|---|---|---|---|
| Free | $0 for the first month | 1,000 | 10 |
| Pro | $9 per month | 100,000 | 60 |
| Ultra | $39 per month | 500,000 | 250 |
| Mega | $99 per month | 1,500,000 | 900 |

New accounts start on Free with 1,000 credits and no card.
Paid plans cost $9 to $99 a month and run for one month.
Changing plan resets your credits to the new allowance - unused credits do not carry over.
The requests/minute limit is one bucket per key, shared by every billed endpoint.
Custom plans above Mega: https://api.fastsaver.io/support

## Platforms handled by /fetch

- instagram.com - 1.5 credits. posts, reels, carousels
- instagram.com/stories/ - 5 credits. stories and highlights
- tiktok.com - 1.5 credits. the no-watermark file first; 2+ photos come back as an album
- pinterest.com - 1.5 credits. pin.it short links and country domains work too
- facebook.com - 1.5 credits. fb.com and fb.watch work too
- x.com - 1.5 credits. twitter.com works too
- rutube.ru - 3 credits. rutube.com works too; the link is an hls playlist (.m3u8), not an mp4
- likee.video - 3 credits. share links only (/v/<code>); likee.com works too

## core

### GET /fetch

paste a link from any supported platform. every response starts with `ok`, `id`, `source` and `type`, then the media. the media fields differ a little by platform. multi-item posts (carousels, tiktok photo posts, pinterest idea pins) come back as `type: "album"` with an `items` array. they have no top-level `download_url`, so check `type` first. tiktok adds `music_url` and `music`. an unsupported host still costs 0.1 credit.

Credits: vary by platform. A failed call costs 0.1 credit.

#### Parameters

- `url` (string, required) - the media url. the scheme is optional. (example: `https://www.instagram.com/p/DRsmm9UjKfH/`)

#### Request

```http
GET https://api.fastsaver.io/v1/fetch?url=https://www.instagram.com/p/DRsmm9UjKfH/
```

#### Response

```json
{
  "ok": true,
  "id": "DRsmm9UjKfH",
  "source": "instagram.com",
  "type": "video",
  "download_url": "https://scontent-dfw6-2.cdninstagram.com/o1/v/t2/f2/m412/AQOqB7ZktoNZKYvIUuQU6ptpi3.mp4",
  "width": 1080,
  "height": 1920,
  "thumbnail_url": "https://scontent-dfw6-1.cdninstagram.com/v/t51.71878-15/588206701_85850229606866_n.jpg",
  "duration": 46,
  "caption": "Ferrari 296 GTS top speed run"
}
```

#### See also

- [instagram downloader api](https://fastsaver.io/blog/instagram-downloader-api) - reels, posts and albums end to end, on fastsaver.io
- [tiktok downloader api](https://fastsaver.io/blog/tiktok-downloader-api) - the video without a watermark plus its mp3, on fastsaver.io


## youtube

### GET /youtube/info

metadata for a youtube video, including every downloadable format with its file size. use it to show the user what they are about to download. a community post link (`youtube.com/post/...`) works too, at the same price: then `is_post` is `true` and the body describes the post (see below). check `is_post` first.

Credits: 2 credits. A failed call costs 0.1 credit.

#### Parameters

- `url` (string, required) - youtube video or community post url (example: `https://www.youtube.com/watch?v=HanBb8FonWs`)

#### Request

```http
GET https://api.fastsaver.io/v1/youtube/info?url=https://www.youtube.com/watch?v=HanBb8FonWs
```

#### Response

```json
{
  "ok": true,
  "is_post": false,
  "video_id": "HanBb8FonWs",
  "title": "Snails - Frogbass",
  "author": "DubstepGutter",
  "author_url": "https://www.youtube.com/channel/UCG6QEHCBfWZOnv7UVxappyw",
  "thumbnail": "https://i.ytimg.com/vi/HanBb8FonWs/sddefault.jpg",
  "duration": 234,
  "thumbnails": {
    "low": "https://i.ytimg.com/vi/HanBb8FonWs/mqdefault.jpg",
    "max": "https://i.ytimg.com/vi/HanBb8FonWs/maxresdefault.jpg"
  },
  "formats": [
    {
      "type": "video",
      "format": "144p",
      "filesize": 6967209
    },
    {
      "type": "video",
      "format": "360p",
      "filesize": 21096358
    },
    {
      "type": "video",
      "format": "720p",
      "filesize": 60448393
    }
  ]
}
```

#### response for a post

`is_post` is `true` and the body has its own shape: no `title` or `formats`, and `author` is an object here, not a string. `type` is one of `image`, `video`, `text`, `poll`, `quiz`, `playlist` or `shared`. every image in `media`, and in the `choices` of an image poll, has a direct `download_url`: no key, no headers. a video in `media` with `available: true` gives its watch page in `url` instead - pass that to `/youtube/download`; one with `available: false` has only a `title` and cannot be downloaded. a repost carries the original post in `shared_post`, and its media is in the top-level `media` too.

```json
{
  "ok": true,
  "is_post": true,
  "post_id": "UgkxB7POmB4C7U0I3kIEWRZpYfE2t-ieP9CA",
  "url": "https://www.youtube.com/post/UgkxB7POmB4C7U0I3kIEWRZpYfE2t-ieP9CA",
  "type": "image",
  "author": {
    "name": "MrBeast",
    "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
    "handle": "@MrBeast",
    "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
    "avatar": "https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s900-c-k-c0x00ffffff-no-rj-mo"
  },
  "text": "Some more fun wedding photos 🥰",
  "links": [],
  "hashtags": [],
  "published_at": "2026-07-23T17:56:09Z",
  "published_text": "2 months ago",
  "edited": false,
  "likes": 3432414,
  "media": [
    {
      "type": "image",
      "download_url": "https://lh3.googleusercontent.com/bFmb7RbyvsNTUS3otE4oc2tqI5CZyl3apwKmjnqnTjFuv1mwxWG7hWlZCuiWlRYrd3oCd_nAtBWVsw=s0",
      "preview_url": "https://yt3.ggpht.com/bFmb7RbyvsNTUS3otE4oc2tqI5CZyl3apwKmjnqnTjFuv1mwxWG7hWlZCuiWlRYrd3oCd_nAtBWVsw=s1024-rj",
      "width": 2641,
      "height": 3734
    },
    {
      "type": "image",
      "download_url": "https://lh3.googleusercontent.com/1Oxcyk2wshlCOoZYiTWUFoixDaomfdtlcIKiGv_ozoT4Lfs9CZx-3VTxbNeQlJOOV_h7CdWjWF8QIA=s0",
      "preview_url": "https://yt3.ggpht.com/1Oxcyk2wshlCOoZYiTWUFoixDaomfdtlcIKiGv_ozoT4Lfs9CZx-3VTxbNeQlJOOV_h7CdWjWF8QIA=s1024-rj",
      "width": 1536,
      "height": 2048
    }
  ],
  "poll": null,
  "playlist": null,
  "shared_post": null
}
```

#### See also

- [youtube download api](https://fastsaver.io/blog/youtube-download-api) - from picking a format to the file, on fastsaver.io

### GET /youtube/search

paged search results with thumbnails and durations.

Credits: 2 credits. A failed call costs 0.1 credit.

#### Parameters

- `query` (string, required) - what to search for (example: `the weeknd`)
- `page` (integer, required) - 1-based page number (example: `1`)

#### Request

```http
GET https://api.fastsaver.io/v1/youtube/search?query=the%20weeknd&page=1
```

#### Response

```json
{
  "ok": true,
  "page": 1,
  "results": [
    {
      "video_id": "HgLfYfJtc8M",
      "title": "The Weeknd - One Of The Girls",
      "duration": "4:05",
      "thumbnail": "https://i.ytimg.com/vi/HgLfYfJtc8M/mqdefault.jpg",
      "thumbnail_max": "https://i.ytimg.com/vi/HgLfYfJtc8M/maxresdefault.jpg"
    },
    {
      "video_id": "p8_ugAjWI5I",
      "title": "The Weeknd - São Paulo",
      "duration": "5:02",
      "thumbnail": "https://i.ytimg.com/vi/p8_ugAjWI5I/mqdefault.jpg",
      "thumbnail_max": "https://i.ytimg.com/vi/p8_ugAjWI5I/maxresdefault.jpg"
    }
  ]
}
```

### POST /youtube/download

one POST turns a youtube video into a direct link to the file. pick a quality from 144p to 2160p, or audio only. the `download_url` needs no api key, so you can hand it straight to your user.

returns a `download_url` to the file itself. open it right away: it lives 5 to 10 minutes. 1440p and 2160p cost 25 credits instead of 15 - they are bigger files and heavier to prepare.

Credits: 15 credits, 25 for 1440p and 2160p. A failed call costs 0.1 credit.

#### Parameters

- `url` (string, required) - youtube video url (example: `https://www.youtube.com/watch?v=6dG1WWjew8s`)
- `format` (string, required) - audio, mp3, m4a, 144p, 240p, 360p, 480p, 720p, 1080p, 1440p or 2160p (example: `1080p`)

#### Request

```http
POST https://api.fastsaver.io/v1/youtube/download
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=6dG1WWjew8s",
  "format": "1080p"
}
```

#### Response

```json
{
  "ok": true,
  "video_id": "6dG1WWjew8s",
  "duration": 577,
  "filename": "THE POWER OF TESTOSTERONE - LITVINOV FIT (1080p, h264).mp4",
  "download_url": "https://drogon.fastsaver.io/dl?id=6dG1WWjew8s&format=mp4&quality=1080&exp=1794387900&n=k3Jq9wZt&sig=Qm4xT7vR2pLs8NcY",
  "thumbnails": {
    "low": "https://i.ytimg.com/vi/6dG1WWjew8s/mqdefault.jpg",
    "max": "https://i.ytimg.com/vi/6dG1WWjew8s/maxresdefault.jpg"
  }
}
```

#### Errors

| status | detail | when | credits |
|---|---|---|---|
| 400 | `Invalid format, available formats: audio, 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p` | `format` is not one of the values above. nothing is charged. | 0 |
| 400 | `Insufficient credits. Please top up to your account.` | your credits are at 0. a balance below the price is not refused: the call runs and takes what is left. | 0 |
| 400 | `download.failed` | the link has no youtube video id, or we could not get the file. | 0.1 |
| 400 | `fetch.timeout` | the whole call ran past 30 seconds. a backstop: the sources give up sooner, with `download.failed`. | 0.1 |
| 400 | `Invalid URL` | `url` is longer than 2048 characters. nothing is charged. | 0 |
| 404 | `tunnel.not_found` | you opened a `/v1/tunnel` link after 10 minutes, or its ~90-second source expired and we could not renew it. every 1440p and 2160p link is one, and so is any link our fallback served. call the endpoint again. | 0 |

#### Limits

- a `download_url` on `*.fastsaver.io/dl` works for 5 minutes and opens up to 3 times. a late or 4th open answers 403 or 410. a `/v1/tunnel` link (every 1440p and 2160p, and any fallback link) works for 10 minutes. after that, call the endpoint again.
- the file streams from the start: there is no `Range` and no resume, and `Content-Length` is usually missing. download it in one GET, not with a segmented downloader.
- `audio`, `mp3` and `m4a` ask for the same thing: the audio track as an mp3.
- if a video has no file at the quality you asked for, you get the next lower one. for video, `filename` usually names the quality you got. the price follows the quality you ask for: 2160p of a 1080p video still costs 25 credits.
- we give the file about 15 seconds (1440p and 2160p: 10). if it is not ready by then, the call fails with `download.failed` and costs 0.1.

#### See also

- [youtube info](https://api.fastsaver.io/docs/youtube/info) - every format with its file size, before you pick one
- [youtube audio to your bot](https://api.fastsaver.io/docs/youtube/audio-tg-bot) - a telegram `file_id` instead of a file
- [credits](https://api.fastsaver.io/docs/credits) - what every call costs
- [errors](https://api.fastsaver.io/docs/errors) - every status code and what to do about it
- [youtube download api](https://fastsaver.io/blog/youtube-download-api) - from picking a format to the file, on fastsaver.io

### POST /youtube/audio/tg-bot

we send the audio to your bot and hand back a `file_id`, so your bot forwards a file it already owns instead of uploading one. 7 credits when we have the track cached, 15 when we have to fetch it first. send `X-Return-File-Id: false` to get `channel_id` and `message_id` instead.

Credits: 7 credits, 15 when it is not cached. A failed call costs 0.1 credit.

#### Parameters

- `video_id` (string, required) - youtube video id (not the full url) (example: `vk6014HuxcE`)
- `bot_username` (string, required) - your bot, with the @ (example: `@your_bot`)

#### Request

```http
POST https://api.fastsaver.io/v1/youtube/audio/tg-bot
Content-Type: application/json

{
  "video_id": "vk6014HuxcE",
  "bot_username": "@your_bot"
}
```

#### Response

```json
{
  "ok": true,
  "file_id": "CQACAgIAAxkDAAIVKWkx3L9mZp2QeHn0Ae4Wq3S1hGm8AAJZRwACfY7wSW1kq3tQcb9INgQ"
}
```

#### response with X-Return-File-Id: false

`channel_id` and `message_id` instead of `file_id`, at the same price. pass them to `copyMessage`.

```json
{
  "ok": true,
  "channel_id": -1001234567890,
  "message_id": 48213
}
```

#### what to do with the file_id

the audio is already sitting in your bot. `file_id` is telegram's own handle for it, so `sendAudio` delivers it without uploading anything - no bandwidth from you and no wait. a `file_id` only works for the bot that received the file, which is why we ask for `bot_username`: hand it to another bot and telegram answers `wrong file identifier`. reuse it as often as you like.

```http
POST https://api.telegram.org/bot<your_bot_token>/sendAudio
Content-Type: application/json

{
  "chat_id": 123456789,
  "audio": "CQACAgIAAxkDAAIVKWkx3L9mZp2QeHn0Ae4Wq3S1hGm8AAJZRwACfY7wSW1kq3tQcb9INgQ"
}
```

with `X-Return-File-Id: false` you get `channel_id` and `message_id` instead - pass those to `copyMessage` when you would rather forward the original message than send a fresh one.

See: telegram bot api: sendAudio - https://core.telegram.org/bots/api#sendaudio


## shazam

### GET /shazam/top

the current chart for a country, paged.

Credits: 1 credit. A failed call costs 0.1 credit.

#### Parameters

- `country` (string, required) - iso country code, or `world` (example: `world`)
- `page` (integer, required) - 1-based page number (example: `1`)

#### Request

```http
GET https://api.fastsaver.io/v1/shazam/top?country=world&page=1
```

#### Response

```json
{
  "ok": true,
  "results": [
    {
      "video_id": "7nVctvQVz0U",
      "title": "Taylor Swift - The Fate of Ophelia",
      "duration": "3:47",
      "thumbnail_url": "https://i.ytimg.com/vi/7nVctvQVz0U/mqdefault.jpg"
    },
    {
      "video_id": "9_bTl2vvYQg",
      "title": "HUNTR/X - Golden",
      "duration": "3:15",
      "thumbnail_url": "https://i.ytimg.com/vi/9_bTl2vvYQg/mqdefault.jpg"
    },
    {
      "video_id": "ZhM1BddhZ1c",
      "title": "El Bogueto - Cuando No Era Cantante",
      "duration": "3:32",
      "thumbnail_url": "https://i.ytimg.com/vi/ZhM1BddhZ1c/mqdefault.jpg"
    }
  ]
}
```

### POST /shazam/identify

send an audio clip as multipart form data and get the track back. up to 50 mb; a few seconds of audio is enough.

Credits: 5 credits. A failed call costs 0.1 credit.

#### Parameters

- `file` (file, required) - audio clip, multipart/form-data

#### Request

```http
POST https://api.fastsaver.io/v1/shazam/identify
Content-Type: multipart/form-data

file=@clip.m4a
```

#### Response

```json
{
  "ok": true,
  "id": "102147933",
  "title": "Сердце пацана",
  "artist": "YARMAK",
  "thumbnail": "https://is1-ssl.mzstatic.com/image/thumb/Music116/v4/8e/4b/0f/cover.jpg/400x400cc.jpg",
  "lyrics": null,
  "results": [
    {
      "video_id": "Qm4tXw8LpZc",
      "title": "YARMAK - Сердце пацана",
      "duration": "3:24",
      "thumbnail": "https://i.ytimg.com/vi/Qm4tXw8LpZc/mqdefault.jpg",
      "thumbnail_max": "https://i.ytimg.com/vi/Qm4tXw8LpZc/maxresdefault.jpg"
    }
  ]
}
```

#### Errors

| status | detail | when | credits |
|---|---|---|---|
| 400 | `File too large (max 50MB).` | the file is over 50 mb. nothing is charged. | 0 |
| 413 | `Request body too large` | the upload is over 52 mb. nothing is charged. | 0 |


## account

### GET /balance

free, and deliberately not written to your request log. poll it as often as you like, within its own 60/min budget.

Credits: free - it is never charged, not even when it fails.

#### Request

```http
GET https://api.fastsaver.io/v1/balance
```

#### Response

```json
{
  "ok": true,
  "plan": "Pro",
  "credits": 98500,
  "plan_credits": 100000,
  "rpm_limit": 60,
  "balance": "12.50",
  "auto_renew": true,
  "plan_expires_at": "2026-08-19T19:56:37.481203+00:00",
  "expire_label": "Ends in 30 days"
}
```

#### Errors

| status | detail | when | credits |
|---|---|---|---|
| 429 | `Rate limit exceeded. Please slow down.` | over 60 calls a minute with one key. nothing is charged. | 0 |
| 401 | `Invalid API key` | the key is unknown. nothing is charged. | 0 |


## MCP server

URL: https://mcp.fastsaver.io/mcp (Streamable HTTP).

AI assistants can use the same key with our MCP server at `https://mcp.fastsaver.io/mcp`: send it as `X-Api-Key`, or as `Authorization: Bearer <key>`. The REST API itself reads only `X-Api-Key`. An MCP server at any other URL is not ours.

A tool returns the same JSON as its REST endpoint and costs the same; a call that fails costs
0.1, even for an unsupported link or one with no post or video id. Listing the tools
and `list_supported_platforms` work without a key. Tool calls share the REST credits and
requests-per-minute bucket.
Setup for each client: https://api.fastsaver.io/docs/mcp.md

| tool | what it does | REST endpoint | credits |
|---|---|---|---|
| `fetch_media` | direct links and metadata for one post, reel, story, video or pin | `GET /v1/fetch` | 1.5; instagram stories 5, rutube and likee 3 |
| `youtube_info` | title, author, duration and every format with its file size | `GET /v1/youtube/info` | 2 |
| `youtube_search` | search youtube videos, one page at a time | `GET /v1/youtube/search` | 2 |
| `youtube_download` | a temporary direct link: audio, or 144p to 2160p | `POST /v1/youtube/download` | 15; 1440p and 2160p 25 |
| `music_charts` | the shazam top chart for a country or the world | `GET /v1/shazam/top` | 1 |
| `get_balance` | plan, credits left and rate limit | `GET /v1/balance` | free |
| `list_supported_platforms` | platforms, link forms and prices, without a key | none | free |

Agent skill for coding agents (Agent Skills format): https://api.fastsaver.io/.well-known/agent-skills/fastsaver-api/SKILL.md
Claude Code plugin (the server and the agent skill in one install): `/plugin marketplace add coder2077/fastsaver_mcp`, then `/plugin install fastsaver-api@fastsaver`. Source: https://github.com/coder2077/fastsaver_mcp