Metadata-Version: 2.4
Name: saverapi-client
Version: 1.1.0
Summary: Official Python SDK for SaverAPI.NET — social media downloader API for Instagram, TikTok, YouTube, Facebook, X, Pinterest, Threads, Vimeo, plus Shazam, music search and NSFW scan. Sync, async and CLI.
Author-email: "SaverAPI.NET" <saverapinet@gmail.com>
License: MIT
Project-URL: Homepage, https://saverapi.net
Project-URL: Documentation, https://saverapi.net/docs
Project-URL: API catalog, https://saverapi.net/all-in-one-downloader-api
Project-URL: YouTube Downloader API, https://saverapi.net/youtube-downloader-api
Project-URL: Instagram Downloader API, https://saverapi.net/instagram-downloader-api
Project-URL: TikTok Downloader API, https://saverapi.net/tiktok-downloader-api
Project-URL: Tutorials, https://saverapi.net/blog
Project-URL: Pricing, https://saverapi.net/pricing
Project-URL: Changelog, https://saverapi.net/whats-new
Project-URL: Telegram, https://t.me/SaverAPI
Keywords: saverapi,social media downloader api,video downloader api,all in one downloader,instagram downloader,instagram reels downloader,instagram api,instagram profile api,tiktok downloader,tiktok video api,tiktok no watermark,youtube downloader,youtube api python,youtube video download,youtube mp3,youtube subtitles,yt-dlp alternative,facebook video downloader,twitter video downloader,x video downloader,pinterest downloader,threads downloader,snapchat downloader,vimeo downloader,soundcloud downloader,shazam api,song recognition,music recognition api,music search api,shazam charts,nsfw scanner,nsfw detection api,photolab api,telegram bot downloader,aiogram,async api client,python sdk,rest api client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Provides-Extra: async
Requires-Dist: httpx>=0.24; extra == "async"
Dynamic: license-file

<div align="center">

# SaverAPI Python SDK

### Social media downloader API for Python — Instagram, TikTok, YouTube, Facebook, X and more

Official client for **[SaverAPI.NET](https://saverapi.net)**: download videos, Reels and audio, read YouTube metadata and subtitles, look up Instagram profiles, recognise songs with Shazam and scan media for NSFW content — with one API key, from sync code, `asyncio` or the command line.

[![PyPI](https://img.shields.io/pypi/v/saverapi-client.svg?color=6f42c1&label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/saverapi-client/)
[![Python](https://img.shields.io/pypi/pyversions/saverapi-client.svg?color=3776ab&logo=python&logoColor=white)](https://pypi.org/project/saverapi-client/)
[![License](https://img.shields.io/badge/license-MIT-success.svg)](#license)
[![Docs](https://img.shields.io/badge/docs-saverapi.net-4f46e5)](https://saverapi.net/docs)

</div>

```bash
pip install -U saverapi-client            # sync client + CLI
pip install -U "saverapi-client[async]"   # + AsyncSaverAPI (httpx)
```

Get a free API key at **[saverapi.net](https://saverapi.net/auth/register)** — no card needed.

---

## Quick start

```python
from saverapi import SaverAPI

api = SaverAPI(api_key="YOUR_API_KEY")   # or export SAVERAPI_KEY=...

media = api.download("https://www.instagram.com/reel/DPOi9V-CAqH/")
print(media["hosting"], media["type"], media["download_url"])

api.save_file(media["download_url"], "downloads/reel.mp4")
```

One call, one parameter: the **All-in-One downloader** recognises the platform from the link. The response's `hosting` field tells you which network it was, `type` is `video` or `image`, and `download_url` points at the file.

## Supported platforms

| Platform | Method | REST endpoint |
|---|---|---|
| Instagram (posts, Reels) | `api.download(url)` | [`/all-in-one-downloader-api`](https://saverapi.net/instagram-downloader-api) |
| TikTok | `api.download(url)` | [`/all-in-one-downloader-api`](https://saverapi.net/tiktok-downloader-api) |
| Facebook | `api.download(url)` | [`/all-in-one-downloader-api`](https://saverapi.net/facebook-video-api) |
| Twitter / X | `api.download(url)` | [`/all-in-one-downloader-api`](https://saverapi.net/twitter-video-api) |
| Snapchat, Pinterest, Likee, Threads, Twitch, Weibo, Vimeo, SoundCloud, Spotify | `api.download(url)` | [`/all-in-one-downloader-api`](https://saverapi.net/all-in-one-downloader-api) |
| YouTube video / MP3 | `api.youtube(url, format)` | [`/youtube-api`](https://saverapi.net/youtube-downloader-api) |
| YouTube for Telegram bots | `api.youtube_telegram(url, format)` | `/youtube-telegram-base` |
| YouTube metadata | `api.youtube_info(url)` · `api.youtube_info_basic(url)` | `/youtube-info-v2` · `/youtube-info` |
| YouTube subtitles | `api.youtube_subtitles(url)` | `/youtube-subtitles` |
| Instagram profile | `api.instagram_profile(username)` | `/instagram-profile` |
| Shazam song recognition | `api.shazam_recognize(url)` | [`/shazam-recognize`](https://saverapi.net/shazam-api) |
| Shazam top charts | `api.shazam_top(country)` | `/shazam-music-top` |
| Music search | `api.music_search(query, limit)` | `/music-search` |
| PhotoLab effects | `api.photolab(effect_id, photo_url)` | `/photolab-api` |
| NSFW scanner | `api.nsfw_scan(url)` | `/nsfw-scanner-api` |
| Account balance (free) | `api.info_balance()` | `/infobalans` |
| Key statistics (free) | `api.api_keys_statistics()` | `/api-keys/all-statistics` |

Full parameter reference and response samples: **[saverapi.net/docs](https://saverapi.net/docs)**. Endpoints added to the catalog later can be called with `api.request("/endpoint-path", {"param": "value"})`.

## Examples

### Download a YouTube video or MP3

```python
video = api.youtube("https://youtu.be/OORSiK8ScTI", format="720")   # 1080|720|480|360|240|144|mp3
api.save_file(video["url"], "video.mp4")

info = api.youtube_info("https://youtu.be/OORSiK8ScTI")
print(info["title"], info["duration"])
```

### Download TikTok, Facebook or X videos

```python
for link in [
    "https://www.tiktok.com/@user/video/7300000000000000000",
    "https://www.facebook.com/watch/?v=1234567890",
    "https://x.com/user/status/1234567890",
]:
    media = api.download(link)
    print(media["hosting"], media["download_url"])
```

### Instagram profile

```python
profile = api.instagram_profile("cristiano")
print(profile["user"]["full_name"], profile["user"]["is_verified"])
```

### Recognise a song, search music, read charts

```python
song = api.shazam_recognize("https://example.com/clip.mp3")
print(song["track"]["title"], "—", song["track"]["subtitle"])

results = api.music_search("Hello Adele", limit=5)
top = api.shazam_top("united-states")
```

### Check your plan and credits (free)

```python
print(api.info_balance())
```

## Async (aiogram, FastAPI, asyncio)

```python
import asyncio
from saverapi import AsyncSaverAPI

async def main():
    async with AsyncSaverAPI() as api:   # reads SAVERAPI_KEY
        results = await asyncio.gather(
            api.download("https://www.instagram.com/reel/DPOi9V-CAqH/"),
            api.youtube_info("https://youtu.be/OORSiK8ScTI"),
        )
        print(results)

asyncio.run(main())
```

### Telegram downloader bot (aiogram 3)

```python
from aiogram import Bot, Dispatcher, F
from aiogram.types import Message
from saverapi import AsyncSaverAPI, SaverAPIError

bot = Bot("TELEGRAM_BOT_TOKEN")
dp = Dispatcher()
api = AsyncSaverAPI()   # SAVERAPI_KEY from the environment

@dp.message(F.text.startswith("http"))
async def on_link(message: Message):
    try:
        media = await api.download(message.text.strip())
    except SaverAPIError as exc:
        await message.answer(f"Could not download: {exc.message}")
        return
    if media.get("type") == "image":
        await message.answer_photo(media["download_url"])
    else:
        await message.answer_video(media["download_url"])

dp.run_polling(bot)
```

Step-by-step guide: **[Build a Telegram video downloader bot](https://saverapi.net/blog/build-telegram-video-downloader-bot)**.

## Command line

```bash
export SAVERAPI_KEY=your_key
saverapi download https://www.instagram.com/reel/DPOi9V-CAqH/
saverapi youtube https://youtu.be/OORSiK8ScTI --format mp3
saverapi youtube-info https://youtu.be/OORSiK8ScTI
saverapi instagram cristiano
saverapi shazam https://example.com/clip.mp3
saverapi balance
```

Prints the JSON response; exits with status 1 on an API error.

## Errors and retries

Rate limits (`429`) and temporary server errors (`5xx`) are retried automatically with exponential backoff (`max_retries=2` by default). Failed 5xx calls are not charged. Everything else raises a specific exception:

```python
from saverapi import (
    SaverAPIError, AuthenticationError, InsufficientCreditsError,
    RateLimitError, NotFoundError, ServerError, NetworkError,
)

try:
    api.download(link)
except AuthenticationError:        # 401/403 — wrong or disabled key
    ...
except InsufficientCreditsError:   # 402 — top up or upgrade at saverapi.net/pricing
    ...
except RateLimitError as exc:      # 429 after retries
    ...
except SaverAPIError as exc:       # anything else; exc.status_code, exc.message, exc.payload
    ...
```

Options: `SaverAPI(api_key=None, timeout=60, base_url=None, session=None, max_retries=2, backoff=1.0)`. Use it as a context manager (`with SaverAPI() as api:`) to close the HTTP session.

## Tips

- Media links (`download_url`) come from the networks' CDNs and **expire** — download them right after the call.
- Only public content can be resolved; private accounts and deleted posts fail.
- Keep the API key on your server; mobile and web apps should call your backend.
- Respect each platform's terms of service and creators' rights.

## Links

- Website and free API key: https://saverapi.net
- API documentation: https://saverapi.net/docs
- YouTube Downloader API: https://saverapi.net/youtube-downloader-api
- Instagram Downloader API: https://saverapi.net/instagram-downloader-api
- TikTok Downloader API: https://saverapi.net/tiktok-downloader-api
- All-in-One Downloader API: https://saverapi.net/all-in-one-downloader-api
- Tutorials: https://saverapi.net/blog
- Pricing: https://saverapi.net/pricing
- Telegram: https://t.me/SaverAPI

## Changelog

**1.1.0**
- New methods covering the whole catalog: `youtube_telegram`, `youtube_info_basic`, `youtube_subtitles`, `instagram_profile`, `photolab`, and `request()` for any endpoint.
- `AsyncSaverAPI` for asyncio (`pip install "saverapi-client[async]"`).
- `saverapi` command line tool.
- Automatic retries with backoff for 429 and 5xx; specific exception classes.
- API key from the `SAVERAPI_KEY` environment variable; context-manager support; type hints (`py.typed`).
- Fully backwards compatible with 1.0.x.

## License

MIT © SaverAPI.NET
