---
name: saveanything-downloader
description: Download videos, photos, reels and stories from Instagram (TikTok & YouTube coming soon) via the SaveAnything API. Use when a user asks to download, save, grab, or fetch media from a social link, or wants the direct media/CDN URL behind an Instagram post/reel/story.
license: MIT
metadata:
  homepage: https://saveanything.app
  api_base: https://saveanything.app
---

# SaveAnything Downloader

Resolve a social-media link into downloadable media files through the SaveAnything API. One POST
gives you every video/photo in a post, each with a direct download URL and a suggested filename.

## When to use this skill

- The user pastes an Instagram (later TikTok/YouTube) link and wants to **download / save** it.
- The user wants the **direct media URL** or MP4/JPG behind a post, reel, story, or carousel.
- You're building an automation that archives or reposts social media the user owns.

Do **not** use it to download content the user has no right to save — respect copyright and
platform terms. For private content the user must have the account holder's permission.

## API

Single endpoint. No API key required for the hosted instance.

```
POST {API_BASE}/api/search
Content-Type: application/json

{ "q": "<social media URL>", "t": "media", "lang": "en", "v": "v2" }
```

`API_BASE` defaults to `https://saveanything.app`. If the user runs their own SaveAnything
backend, use their origin instead.

### Response

```json
{
  "status": "ok",
  "p": "instagram",
  "media": [
    {
      "type": "video",
      "url": "/api/download?url=<cdn>&filename=SaveAnything.app_<id>.mp4",
      "thumb": "/api/img?url=<cdn>",
      "filename": "SaveAnything.app_<id>.mp4"
    }
  ]
}
```

- `status`: `"ok"` on success, `"error"` otherwise (with a `msg`).
- `media[]`: one entry per downloadable file. A single reel returns the video **plus** its
  thumbnail image; a carousel returns each photo/video.
- `type`: `"video" | "image" | "audio"`.
- `url`: the download link. **It is relative** — prefix it with `API_BASE` to get an absolute
  URL. Fetching it streams the file with a `Content-Disposition` attachment and the branded
  `filename`.
- `thumb`: relative preview-image URL (also prefix with `API_BASE`).
- `filename`: suggested save name.

### Steps

1. POST the user's URL to `{API_BASE}/api/search`.
2. If `status !== "ok"` or `media` is empty, tell the user (link may be private, deleted, or
   rate-limited) and stop.
3. For each item you want, build the absolute URL: `API_BASE + media[i].url`.
4. Download it (save to disk, stream to the user, or hand back the link) using
   `media[i].filename` as the name.

Pick the primary item by `type` — usually the `video`; for a photo carousel, take every
`image`. Ignore the standalone thumbnail image that accompanies a video unless the user wants it.

## Examples

- `examples/download.sh` — resolve + download with `curl` + `jq`.
- `examples/download.py` — resolve + download in Python (stdlib only).
- `examples/download.js` — resolve + download in Node (fetch).

## Notes & limits

- Supported today: **Instagram** posts, reels, stories, carousels, profile photos. TikTok and
  YouTube are planned (the endpoint shape won't change).
- Download links are time-limited (the underlying CDN URLs expire, ~1 hour). Resolve fresh
  before downloading; don't cache the `url` long-term.
- One link per request. For many links, call the endpoint per link.
- The hosted instance is rate-limited for abuse protection. For heavy use, self-host
  SaveAnything and point `API_BASE` at your backend.
- Files are served from the SaveAnything origin with a `SaveAnything.app_` filename — the tool
  proxies the media, it does not hand out third-party CDN branding.