Metadata-Version: 2.4
Name: saverapi-client
Version: 1.0.2
Summary: Official Python SDK for SaverAPI.NET — download media from Instagram, TikTok, YouTube, Facebook, Twitter, and more. Includes Shazam recognition, NSFW scanner, music search & charts.
Author-email: "SaverAPI.NET" <saverapinet@gmail.com>
Project-URL: Homepage, https://saverapi.net
Project-URL: Documentation, https://saverapi.net/docs
Project-URL: Repository, https://saverapi.net
Project-URL: Bug Tracker, https://saverapi.net
Keywords: instagram downloader,instagram reel downloader,tiktok downloader,tiktok video api,youtube downloader,youtube api python,social media downloader,video downloader api,media downloader,api client python,python sdk,instagram api,tiktok api,youtube video download,reels downloader,shorts downloader,facebook video downloader,twitter video downloader,x video downloader,scraping api,automation api,fast api client,high performance api,download videos python,python downloader library,saverapi,saverapi client,shazam api,shazam recognize,music recognition,nsfw scanner,nsfw detection,music search api,shazam top charts,youtube info,snapchat downloader,pinterest downloader,threads downloader,soundcloud downloader,spotify downloader,vimeo downloader,twitch downloader,likee downloader,weibo downloader
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.7
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests

<div align="center">

# 🚀 SaverAPI Client

### Official Python SDK for **[SaverAPI.NET](https://saverapi.net)**

**One library — every platform.**
Download media from 13+ social networks, recognize tracks with Shazam, search music, fetch global charts, and scan content for NSFW.

[![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/)
[![Downloads](https://img.shields.io/pypi/dm/saverapi-client.svg?color=00C7B7&label=installs)](https://pypi.org/project/saverapi-client/)
[![License](https://img.shields.io/badge/license-MIT-success.svg)](#-license)
[![Website](https://img.shields.io/badge/saverapi.net-ff4081?logo=googlechrome&logoColor=white)](https://saverapi.net)

</div>

---

## 📦 Installation

```bash
pip install -U saverapi-client
```

Get your free API key at **[saverapi.net](https://saverapi.net)**.

---

## ⚡ Initialize the client (once)

```python
from saverapi import SaverAPI

api = SaverAPI(api_key="YOUR_API_KEY")
```

> All examples below use this single `api` instance.

---

## 🧭 API map

| # | Method | Endpoint |
|:-:|---|---|
| 1 | `api.nsfw_scan(url)` | `/nsfw-scanner-api` |
| 2 | `api.shazam_recognize(url)` | `/shazam-recognize` |
| 3 | `api.youtube_info(url)` | `/youtube-info-v2` |
| 4 | `api.shazam_top(country)` | `/shazam-music-top` |
| 5 | `api.music_search(query, limit)` | `/music-search` |
| 6 | `api.youtube(url, format)` | `/youtube-api` |
| 7 | `api.download(url)` | `/all-in-one-downloader-api` |

---

## 1️⃣ NSFW Scanner — `nsfw_scan`

```python
result = api.nsfw_scan("https://example.com/video.mp4")
print(result)
```

**Response**

```json
{
  "nsfw_percentage": "99.96%",
  "is_nsfw": "YES 🔞"
}
```

---

## 2️⃣ Shazam Recognize — `shazam_recognize`

Identify any track from a public audio/video URL.

```python
result = api.shazam_recognize(
    "https://codeskulptor-demos.commondatastorage.googleapis.com/GalaxyInvaders/theme_01.mp3"
)

print(result["track"]["title"], "—", result["track"]["subtitle"])
print(result["track"]["url"])
```

**Response (excerpt)**

```json
{
  "matches": [
    { "id": "850879048", "offset": 111.537570312 }
  ],
  "track": {
    "key": "850879048",
    "title": "Que Tengo Que Hacer",
    "subtitle": "Robert G",
    "images": {
      "coverart": "https://is1-ssl.mzstatic.com/.../400x400cc.jpg"
    },
    "url": "https://www.shazam.com/track/850879048/que-tengo-que-hacer",
    "genres": { "primary": "Modern Dancehall" },
    "isrc": "QZW9L2519842"
  }
}
```

---

## 3️⃣ YouTube Info — `youtube_info`

Metadata + every available format/size for a YouTube URL.

```python
info = api.youtube_info("https://youtu.be/bICMVAhktBE?list=RDT_tyeZfxoXE")

print(info["title"], "·", info["author"])
for f in info["formats"]:
    print(f["type"], f["format"], f["filesize"])
```

**Response**

```json
{
  "ok": true,
  "video_id": "YA8PBoIRkIg",
  "title": "【DLEJ】Vaqtinchalik shamol ✦ 나는 잠시 머문 바람",
  "author": "Dreams by dlej",
  "thumbnail": "https://i.ytimg.com/vi/YA8PBoIRkIg/sddefault.jpg",
  "duration": 201,
  "formats": [
    { "type": "video", "format": "144p",  "filesize": 4681719 },
    { "type": "video", "format": "240p",  "filesize": 5796762 },
    { "type": "video", "format": "360p",  "filesize": 8343828 },
    { "type": "video", "format": "480p",  "filesize": 11329839 },
    { "type": "video", "format": "720p",  "filesize": 19039410 },
    { "type": "video", "format": "1080p", "filesize": 67305699 },
    { "type": "audio", "format": "audio", "filesize": 3253320 }
  ]
}
```

---

## 4️⃣ Shazam Top 200 chart — `shazam_top`

```python
chart = api.shazam_top(country="us")   # us · uz · ru · gb · tr · de · ...

print(chart["chart"], "—", chart["total_songs"], "songs")
for s in chart["songs"][:5]:
    print(f"{s['position']:>3}. {s['title']} — {s['artist']}")
```

**Response (excerpt)**

```json
{
  "status": "success",
  "country": "Uzbekistan",
  "country_code": "UZ",
  "chart": "Top 200 Uzbekistan",
  "total_songs": 200,
  "songs": [
    { "position": 1, "title": "Vaqtinchalik Shamol", "artist": "DLEJ" },
    { "position": 2, "title": "Мальборо", "artist": "SAYAN" },
    { "position": 3, "title": "Her E Gul", "artist": "Strane Kurdi" }
  ]
}
```

---

## 5️⃣ Music Search — `music_search`

```python
results = api.music_search("Hello!", limit=10)

for t in results["results"]:
    print(t["title"], "—", t["artist"], f"({t['duration']})")
```

**Response**

```json
{
  "query": "hello",
  "total_results": 2,
  "results": [
    {
      "id": "YQHsXMglC9A",
      "title": "Adele - Hello (Official Music Video)",
      "artist": "Adele",
      "duration": "6:07",
      "thumbnail": "https://i.ytimg.com/vi/YQHsXMglC9A/mqdefault.jpg"
    },
    {
      "id": "kK42LZqO0wA",
      "title": "Martin Solveig & Dragonette - Hello (Official Short Video Version HD)",
      "artist": "Kontor.TV",
      "duration": "4:13",
      "thumbnail": "https://i.ytimg.com/vi/kK42LZqO0wA/mqdefault.jpg"
    }
  ]
}
```

---

## 6️⃣ YouTube Downloader — `youtube`

Returns a direct, ready-to-stream tunnel URL.

```python
yt = api.youtube("https://youtu.be/OORSiK8ScTI", format="720")
# format: "144" | "240" | "360" | "480" | "720" | "1080" | "audio"

print(yt["title"], "·", yt["author"])
print("→", yt["url"])

# Optional: stream-save to disk
api.save_file(yt["url"], "downloads/video.mp4")
```

**Response**

```json
{
  "status": "tunnel",
  "url": "https://dl.saverapi.net/tunnel/fef2ca53-6fa7-401c-bd0c-4b303e58ac77.mp4",
  "filename": "【DLEJ】Vaqtinchalik shamol - DLEJ (1080p, h264).mp4",
  "width": 1920,
  "height": 1080,
  "thumbnail": "https://i.ytimg.com/vi/YA8PBoIRkIg/hqdefault.jpg",
  "title": "【DLEJ】Vaqtinchalik shamol ✦ 나는 잠시 머문 바람",
  "author": "DLEJ"
}
```

---

## 7️⃣ All-in-One Downloader — `download`

> One endpoint for **every** platform below.

```python
data = api.download(
    "https://www.instagram.com/reel/DPOi9V-CAqH/?utm_source=ig_web_copy_link"
)

print(data["hosting"], "·", data["type"])
print("→", data["download_url"])
```

**Response**

```json
{
  "error": false,
  "hosting": "instagram",
  "shortcode": "DYEZ4_FIlWf",
  "caption": "1-kun zalni to'ldirib o'tirgan barcha muhlislarimga kattakon raxmat🤗",
  "type": "video",
  "download_url": "https://instagram.fsgn5-5.fna.fbcdn.net/.../video.mp4",
  "thumb": "https://instagram.fsgn5-5.fna.fbcdn.net/.../cover.jpg"
}
```

### 📥 Supported platforms

| | Platform | Content |
|:-:|---|---|
| 📸 | Instagram | posts, reels, stories, albums |
| 🎵 | TikTok | videos |
| 📘 | Facebook | videos, photos |
| 🐦 | Twitter (X) | videos, photos, GIFs |
| 👻 | Snapchat | stories, spotlight |
| 📌 | Pinterest | images, videos |
| 💖 | Likee | videos |
| 🎧 | SoundCloud | audio tracks |
| 🎶 | Spotify | audio tracks |
| 🧵 | Threads | images, videos |
| 🎬 | Twitch | clips, videos |
| 🌐 | Weibo | images, videos |
| 🎬 | Vimeo | videos |

---

## 🔁 Run them all in sequence

```python
from saverapi import SaverAPI, SaverAPIError

api = SaverAPI(api_key="YOUR_API_KEY")

calls = [
    ("NSFW",       lambda: api.nsfw_scan("https://example.com/video.mp4")),
    ("Shazam",     lambda: api.shazam_recognize("https://example.com/audio.mp3")),
    ("YT info",    lambda: api.youtube_info("https://youtu.be/bICMVAhktBE")),
    ("Top chart",  lambda: api.shazam_top("us")),
    ("Search",     lambda: api.music_search("Hello!", limit=10)),
    ("YT dl",      lambda: api.youtube("https://youtu.be/OORSiK8ScTI", format="720")),
    ("All-in-one", lambda: api.download("https://www.instagram.com/reel/DPOi9V-CAqH/")),
]

for name, fn in calls:
    try:
        print(f"✅ {name}:", fn())
    except SaverAPIError as e:
        print(f"❌ {name}: [{e.status_code}] {e.message}")
```

---

## 🛡️ Error handling

```python
from saverapi import SaverAPI, SaverAPIError

api = SaverAPI(api_key="YOUR_API_KEY")

try:
    api.download("https://broken-link/")
except SaverAPIError as e:
    print(e.status_code, e.message, e.payload)
```

---

## 🧰 Advanced usage

```python
import requests
from saverapi import SaverAPI

session = requests.Session()
session.proxies = {"https": "http://127.0.0.1:8080"}

api = SaverAPI(
    api_key="YOUR_API_KEY",
    timeout=60,
    session=session,                    # bring your own session
    base_url="https://saverapi.net/api" # custom base URL if needed
)
```

---

## 📞 Support

- 🌍 Website — <https://saverapi.net>
- 📧 Email — saverapinet@gmail.com
- 💬 Telegram — [@BizBotSupport](https://t.me/BizBotSupport)

---

## 📝 License

MIT © [SaverAPI.NET](https://saverapi.net)
