saveapi 0.1.0__tar.gz

saveapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saveapi.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saveapi-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: saveapi
+Version: 0.1.0
+Summary: Official Python client for saveapi.org — download media from Instagram, TikTok, YouTube, Facebook, X, Pinterest and 7 more platforms with one API.
+Project-URL: Homepage, https://saveapi.org/
+Project-URL: Documentation, https://saveapi.org/en/docs/
+Project-URL: Pricing, https://saveapi.org/en/pricing/
+Project-URL: Source, https://github.com/akhroruz/saveapi-sdk
+Project-URL: Changelog, https://saveapi.org/en/changelog/
+Author-email: "saveapi.org" <hello@saveapi.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: instagram api,instagram downloader api,reels downloader,saveapi,social media downloader,tiktok api,tiktok downloader api,video downloader,youtube downloader api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Video
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: typing-extensions>=4.5
+Description-Content-Type: text/markdown
+
+# saveapi — Python client for saveapi.org
+
+Download videos, photos and audio from **Instagram, TikTok, YouTube, Facebook, X (Twitter), Pinterest, Likee, Snapchat, Threads, VK, Rutube, 9GAG and Twitch** with one API call. Send a public post link, get back direct media URLs and metadata in one JSON shape.
+
+- Docs: <https://saveapi.org/en/docs/>
+- Free key (1,000 credits, no card): <https://saveapi.org/en/signup/>
+- Pricing: <https://saveapi.org/en/pricing/>
+
+```bash
+pip install saveapi
+```
+
+## Quick start
+
+```python
+from saveapi import SaveAPI
+
+api = SaveAPI("sk_live_...")          # or set SAVEAPI_KEY and call SaveAPI()
+
+post = api.download("https://www.tiktok.com/@zachking/video/6768504823336815877")
+print(post["platform"], post["meta"]["title"])
+for media in post["medias"]:
+    print(media["type"], media["ext"], media["url"])
+```
+
+`download()` detects the platform from the link. To call one platform's endpoint directly use `api.platform("instagram", url)`.
+
+## Async
+
+```python
+import asyncio
+from saveapi import AsyncSaveAPI
+
+async def main():
+    async with AsyncSaveAPI() as api:
+        post = await api.download("https://www.instagram.com/reel/DdwXSSkMvJz/")
+        print(post["medias"][0]["url"])
+
+asyncio.run(main())
+```
+
+## YouTube
+
+YouTube is two steps: read the available qualities, then create a link for one of them.
+
+```python
+info = api.youtube_info("https://youtu.be/dQw4w9WgXcQ")          # 2 credits
+print([f["quality"] for f in info["formats"]])
+
+link = api.youtube_create("https://youtu.be/dQw4w9WgXcQ", "mp3")  # 10 credits
+print(link["url"], link["filename"])
+```
+
+Video qualities are H.264 MP4 `144p`–`1080p`; `mp3` and `m4a` are audio. The link is short-lived — download it right away.
+
+## Errors
+
+Every failed call raises `SaveAPIError`. Match on `error.code`, not on the message:
+
+```python
+from saveapi import SaveAPI, SaveAPIError
+
+try:
+    post = api.download(url)
+except SaveAPIError as error:
+    if error.code in ("PRIVATE_CONTENT", "MEDIA_NOT_FOUND"):
+        print("The post is private or gone")      # final answer, costs 0.1 credit
+    elif error.code == "QUOTA_EXCEEDED":
+        print("Top up at https://saveapi.org/en/dashboard/billing/")
+    else:
+        raise
+```
+
+The client retries only what a retry can fix: `UPSTREAM_TIMEOUT` and `UPSTREAM_ERROR` (once by default, `max_retries=`), and `RATE_LIMITED` after the `Retry-After` delay. Private, deleted and unsupported links are never retried. Full list of codes: <https://saveapi.org/en/docs/#errors>.
+
+## All methods
+
+| Method | Endpoint | Cost |
+|---|---|---|
+| `download(url, full_meta=False, limit_mb=None)` | `/v1/download` | 1.5 credits |
+| `platform(name, url, ...)` | `/v1/{platform}` | 1.5 credits |
+| `youtube_info(url)` | `/v1/youtube/info` | 2 credits |
+| `youtube_create(url, quality="720p")` | `/v1/youtube/create` | 10 credits |
+| `instagram_profile(username=None, url=None)` | `/v1/instagram/profile` | 3 credits |
+| `detect(url)` | `/v1/detect` | free |
+| `platforms()` | `/v1/platforms` | free |
+| `me()` | `/v1/me` | free |
+| `usage(days=30)` | `/v1/usage` | free |
+
+Instagram stories cost 5 credits, Rutube 3, and a link the source refuses 0.1. Current prices: <https://saveapi.org/en/pricing/>.
+
+## Guides
+
+- [Telegram downloader bot](https://saveapi.org/en/guides/telegram-bot/)
+- [Download social media videos in Python](https://saveapi.org/en/guides/python/)
+- [TikTok without watermark](https://saveapi.org/en/guides/no-watermark/)
+- [YouTube to MP3 API](https://saveapi.org/en/guides/youtube-mp3-api/)
+
+## License
+
+MIT

saveapi-0.1.0/README.md

@@ -0,0 +1,101 @@
+# saveapi — Python client for saveapi.org
+
+Download videos, photos and audio from **Instagram, TikTok, YouTube, Facebook, X (Twitter), Pinterest, Likee, Snapchat, Threads, VK, Rutube, 9GAG and Twitch** with one API call. Send a public post link, get back direct media URLs and metadata in one JSON shape.
+
+- Docs: <https://saveapi.org/en/docs/>
+- Free key (1,000 credits, no card): <https://saveapi.org/en/signup/>
+- Pricing: <https://saveapi.org/en/pricing/>
+
+```bash
+pip install saveapi
+```
+
+## Quick start
+
+```python
+from saveapi import SaveAPI
+
+api = SaveAPI("sk_live_...")          # or set SAVEAPI_KEY and call SaveAPI()
+
+post = api.download("https://www.tiktok.com/@zachking/video/6768504823336815877")
+print(post["platform"], post["meta"]["title"])
+for media in post["medias"]:
+    print(media["type"], media["ext"], media["url"])
+```
+
+`download()` detects the platform from the link. To call one platform's endpoint directly use `api.platform("instagram", url)`.
+
+## Async
+
+```python
+import asyncio
+from saveapi import AsyncSaveAPI
+
+async def main():
+    async with AsyncSaveAPI() as api:
+        post = await api.download("https://www.instagram.com/reel/DdwXSSkMvJz/")
+        print(post["medias"][0]["url"])
+
+asyncio.run(main())
+```
+
+## YouTube
+
+YouTube is two steps: read the available qualities, then create a link for one of them.
+
+```python
+info = api.youtube_info("https://youtu.be/dQw4w9WgXcQ")          # 2 credits
+print([f["quality"] for f in info["formats"]])
+
+link = api.youtube_create("https://youtu.be/dQw4w9WgXcQ", "mp3")  # 10 credits
+print(link["url"], link["filename"])
+```
+
+Video qualities are H.264 MP4 `144p`–`1080p`; `mp3` and `m4a` are audio. The link is short-lived — download it right away.
+
+## Errors
+
+Every failed call raises `SaveAPIError`. Match on `error.code`, not on the message:
+
+```python
+from saveapi import SaveAPI, SaveAPIError
+
+try:
+    post = api.download(url)
+except SaveAPIError as error:
+    if error.code in ("PRIVATE_CONTENT", "MEDIA_NOT_FOUND"):
+        print("The post is private or gone")      # final answer, costs 0.1 credit
+    elif error.code == "QUOTA_EXCEEDED":
+        print("Top up at https://saveapi.org/en/dashboard/billing/")
+    else:
+        raise
+```
+
+The client retries only what a retry can fix: `UPSTREAM_TIMEOUT` and `UPSTREAM_ERROR` (once by default, `max_retries=`), and `RATE_LIMITED` after the `Retry-After` delay. Private, deleted and unsupported links are never retried. Full list of codes: <https://saveapi.org/en/docs/#errors>.
+
+## All methods
+
+| Method | Endpoint | Cost |
+|---|---|---|
+| `download(url, full_meta=False, limit_mb=None)` | `/v1/download` | 1.5 credits |
+| `platform(name, url, ...)` | `/v1/{platform}` | 1.5 credits |
+| `youtube_info(url)` | `/v1/youtube/info` | 2 credits |
+| `youtube_create(url, quality="720p")` | `/v1/youtube/create` | 10 credits |
+| `instagram_profile(username=None, url=None)` | `/v1/instagram/profile` | 3 credits |
+| `detect(url)` | `/v1/detect` | free |
+| `platforms()` | `/v1/platforms` | free |
+| `me()` | `/v1/me` | free |
+| `usage(days=30)` | `/v1/usage` | free |
+
+Instagram stories cost 5 credits, Rutube 3, and a link the source refuses 0.1. Current prices: <https://saveapi.org/en/pricing/>.
+
+## Guides
+
+- [Telegram downloader bot](https://saveapi.org/en/guides/telegram-bot/)
+- [Download social media videos in Python](https://saveapi.org/en/guides/python/)
+- [TikTok without watermark](https://saveapi.org/en/guides/no-watermark/)
+- [YouTube to MP3 API](https://saveapi.org/en/guides/youtube-mp3-api/)
+
+## License
+
+MIT

saveapi-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "saveapi"
+version = "0.1.0"
+description = "Official Python client for saveapi.org — download media from Instagram, TikTok, YouTube, Facebook, X, Pinterest and 7 more platforms with one API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "saveapi.org", email = "hello@saveapi.org" }]
+keywords = [
+  "instagram downloader api", "tiktok downloader api", "youtube downloader api",
+  "social media downloader", "video downloader", "instagram api", "tiktok api",
+  "reels downloader", "saveapi",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Multimedia :: Video",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24", "typing_extensions>=4.5"]
+
+[project.urls]
+Homepage = "https://saveapi.org/"
+Documentation = "https://saveapi.org/en/docs/"
+Pricing = "https://saveapi.org/en/pricing/"
+Source = "https://github.com/akhroruz/saveapi-sdk"
+Changelog = "https://saveapi.org/en/changelog/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/saveapi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

saveapi-0.1.0/src/saveapi/__init__.py

@@ -0,0 +1,11 @@
+"""Python client for saveapi.org — one REST API to download media from
+Instagram, TikTok, YouTube, Facebook, X, Pinterest, Likee, Snapchat,
+Threads, VK, Rutube, 9GAG and Twitch.
+
+Docs: https://saveapi.org/en/docs/
+"""
+
+from ._client import AsyncSaveAPI, SaveAPI, __version__
+from .errors import RETRYABLE_CODES, SaveAPIError
+
+__all__ = ["SaveAPI", "AsyncSaveAPI", "SaveAPIError", "RETRYABLE_CODES", "__version__"]

saveapi-0.1.0/src/saveapi/_client.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .errors import SaveAPIError
+from .types import Detection, DownloadResult, YouTubeInfo, YouTubeLink, YouTubeQuality
+
+DEFAULT_BASE_URL = "https://api.saveapi.org"
+#: Social links resolve in 1–10 s; a slow source can take up to ~30 s on our side.
+DEFAULT_TIMEOUT = 45.0
+#: Longest ``Retry-After`` the client is willing to sleep through on 429.
+MAX_RATE_LIMIT_WAIT = 60.0
+
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("saveapi")
+except Exception:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0"
+
+
+def _key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("SAVEAPI_KEY")
+    if not key:
+        raise ValueError(
+            "No API key. Pass api_key=... or set SAVEAPI_KEY. "
+            "Get one free at https://saveapi.org/en/signup/"
+        )
+    return key
+
+
+def _clean(params: dict[str, Any]) -> dict[str, Any]:
+    out = {}
+    for name, value in params.items():
+        if value is None:
+            continue
+        out[name] = ("true" if value else "false") if isinstance(value, bool) else value
+    return out
+
+
+def _error(response: httpx.Response) -> SaveAPIError:
+    code, message = "HTTP_ERROR", response.reason_phrase or "Request failed"
+    try:
+        body = response.json()
+        error = body.get("error") or {}
+        code = error.get("code") or code
+        message = error.get("message") or message
+    except ValueError:
+        pass
+    retry_after = response.headers.get("Retry-After")
+    return SaveAPIError(
+        code, message, response.status_code,
+        float(retry_after) if retry_after and retry_after.replace(".", "", 1).isdigit() else None,
+    )
+
+
+def _delay(error: SaveAPIError, attempt: int) -> Optional[float]:
+    """Seconds to wait before retrying, or ``None`` to give up."""
+    if error.code == "RATE_LIMITED":
+        wait = error.retry_after if error.retry_after is not None else 5.0
+        return wait if wait <= MAX_RATE_LIMIT_WAIT else None
+    if error.retryable:
+        return min(1.0 * (2 ** attempt), 8.0)
+    return None
+
+
+class _Base:
+    def __init__(self, api_key: Optional[str], base_url: str, max_retries: int):
+        self._headers = {
+            "Authorization": f"Bearer {_key(api_key)}",
+            "User-Agent": f"saveapi-python/{__version__}",
+            "Accept": "application/json",
+        }
+        self._base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+
+
+class SaveAPI(_Base):
+    """Synchronous client for https://api.saveapi.org.
+
+    >>> from saveapi import SaveAPI
+    >>> api = SaveAPI()                      # reads SAVEAPI_KEY
+    >>> post = api.download("https://www.tiktok.com/@zachking/video/6768504823336815877")
+    >>> post["medias"][0]["url"]
+
+    Args:
+        api_key: Your ``sk_live_...`` key. Defaults to ``$SAVEAPI_KEY``.
+        max_retries: How many times to retry ``UPSTREAM_TIMEOUT`` /
+            ``UPSTREAM_ERROR`` / ``RATE_LIMITED``. Final errors (private,
+            deleted, unsupported) are never retried.
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 1,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        super().__init__(api_key, base_url, max_retries)
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SaveAPI":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _get(self, path: str, **params: Any) -> Any:
+        attempt = 0
+        while True:
+            response = self._http.get(self._base_url + path, params=_clean(params), headers=self._headers)
+            if response.is_success:
+                return response.json()
+            error = _error(response)
+            wait = _delay(error, attempt) if attempt < self.max_retries else None
+            if wait is None:
+                raise error
+            time.sleep(wait)
+            attempt += 1
+
+    # ── Media ──────────────────────────────────────────────────────────────
+
+    def download(self, url: str, *, full_meta: bool = False, limit_mb: Optional[float] = None) -> DownloadResult:
+        """Resolve any supported post link (platform detected from the URL).
+
+        ``full_meta=True`` adds likes, location and music on Instagram (~+0.3 s,
+        same price). ``limit_mb`` skips renditions above that size where the
+        platform reports sizes.
+        """
+        return self._get("/v1/download", url=url, full_meta=full_meta or None, limit_mb=limit_mb)
+
+    def platform(self, platform: str, url: str, *, full_meta: bool = False,
+                 limit_mb: Optional[float] = None) -> DownloadResult:
+        """Resolve through one platform's endpoint, e.g. ``platform("tiktok", url)``."""
+        return self._get(f"/v1/{platform}", url=url, full_meta=full_meta or None, limit_mb=limit_mb)
+
+    def youtube_info(self, url: str) -> YouTubeInfo:
+        """Title, duration and the qualities a YouTube video offers (2 credits)."""
+        return self._get("/v1/youtube/info", url=url)
+
+    def youtube_create(self, url: str, quality: YouTubeQuality = "720p") -> YouTubeLink:
+        """A short-lived download link for one quality (10 credits).
+
+        Video qualities are H.264 MP4 144p–1080p; ``mp3`` and ``m4a`` are audio.
+        """
+        return self._get("/v1/youtube/create", url=url, quality=quality)
+
+    def instagram_profile(self, username: Optional[str] = None, *, url: Optional[str] = None) -> dict:
+        """Public profile by username (``natgeo`` or ``@natgeo``) or profile link (3 credits)."""
+        if not username and not url:
+            raise ValueError("Pass a username or a profile url")
+        return self._get("/v1/instagram/profile", username=username, url=url)
+
+    # ── Free calls ─────────────────────────────────────────────────────────
+
+    def detect(self, url: str) -> Detection:
+        """Which platform a link belongs to. Free."""
+        return self._get("/v1/detect", url=url)
+
+    def platforms(self) -> dict:
+        """Supported platforms and their endpoints. Free."""
+        return self._get("/v1/platforms")
+
+    def me(self) -> dict:
+        """Key, plan and credit balance. Free."""
+        return self._get("/v1/me")
+
+    def usage(self, days: int = 30) -> dict:
+        """Daily usage for the last ``days`` (1–180). Free."""
+        return self._get("/v1/usage", days=days)
+
+
+class AsyncSaveAPI(_Base):
+    """``asyncio`` twin of :class:`SaveAPI` — same methods, awaitable.
+
+    >>> async with AsyncSaveAPI() as api:
+    ...     post = await api.download(url)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 1,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        super().__init__(api_key, base_url, max_retries)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSaveAPI":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _get(self, path: str, **params: Any) -> Any:
+        attempt = 0
+        while True:
+            response = await self._http.get(self._base_url + path, params=_clean(params), headers=self._headers)
+            if response.is_success:
+                return response.json()
+            error = _error(response)
+            wait = _delay(error, attempt) if attempt < self.max_retries else None
+            if wait is None:
+                raise error
+            await asyncio.sleep(wait)
+            attempt += 1
+
+    async def download(self, url: str, *, full_meta: bool = False,
+                       limit_mb: Optional[float] = None) -> DownloadResult:
+        return await self._get("/v1/download", url=url, full_meta=full_meta or None, limit_mb=limit_mb)
+
+    async def platform(self, platform: str, url: str, *, full_meta: bool = False,
+                       limit_mb: Optional[float] = None) -> DownloadResult:
+        return await self._get(f"/v1/{platform}", url=url, full_meta=full_meta or None, limit_mb=limit_mb)
+
+    async def youtube_info(self, url: str) -> YouTubeInfo:
+        return await self._get("/v1/youtube/info", url=url)
+
+    async def youtube_create(self, url: str, quality: YouTubeQuality = "720p") -> YouTubeLink:
+        return await self._get("/v1/youtube/create", url=url, quality=quality)
+
+    async def instagram_profile(self, username: Optional[str] = None, *, url: Optional[str] = None) -> dict:
+        if not username and not url:
+            raise ValueError("Pass a username or a profile url")
+        return await self._get("/v1/instagram/profile", username=username, url=url)
+
+    async def detect(self, url: str) -> Detection:
+        return await self._get("/v1/detect", url=url)
+
+    async def platforms(self) -> dict:
+        return await self._get("/v1/platforms")
+
+    async def me(self) -> dict:
+        return await self._get("/v1/me")
+
+    async def usage(self, days: int = 30) -> dict:
+        return await self._get("/v1/usage", days=days)

saveapi-0.1.0/src/saveapi/errors.py

@@ -0,0 +1,36 @@
+"""Errors raised by the client.
+
+Every failed call raises :class:`SaveAPIError`. Match on ``error.code`` —
+the codes are stable, the messages are not.
+"""
+
+from __future__ import annotations
+
+#: Codes a retry can fix. Everything else is a final answer: retrying a
+#: private or deleted post does not change it, and where the error is billed
+#: (0.1 credit for a link the source refuses) it costs another credit.
+RETRYABLE_CODES = frozenset({"UPSTREAM_TIMEOUT", "UPSTREAM_ERROR", "RATE_LIMITED"})
+
+
+class SaveAPIError(Exception):
+    """A non-2xx answer from api.saveapi.org.
+
+    Attributes:
+        code: Stable error code, e.g. ``PRIVATE_CONTENT`` or ``QUOTA_EXCEEDED``.
+            Full list: https://saveapi.org/en/docs/#errors
+        message: Human-readable explanation (may change between releases).
+        status: HTTP status code.
+        retry_after: Seconds to wait, set on ``RATE_LIMITED``.
+    """
+
+    def __init__(self, code: str, message: str, status: int, retry_after: float | None = None):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.status = status
+        self.retry_after = retry_after
+
+    @property
+    def retryable(self) -> bool:
+        """True when sending the same request again can succeed."""
+        return self.code in RETRYABLE_CODES

saveapi-0.1.0/src/saveapi/types.py

@@ -0,0 +1,133 @@
+"""Response shapes (``TypedDict``) — the client returns plain dicts.
+
+Field names match https://saveapi.org/en/docs/. Fields the source does not
+provide are ``None`` rather than missing.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional, TypedDict
+
+from typing_extensions import NotRequired
+
+
+class Credits(TypedDict):
+    spent: float
+    remaining: Optional[float]
+
+
+class Media(TypedDict):
+    type: Literal["video", "image", "audio"]
+    url: str
+    ext: Optional[str]
+    quality: Optional[str]
+    width: Optional[int]
+    height: Optional[int]
+    size_mb: Optional[float]
+    watermark: Optional[bool]
+
+
+class Format(TypedDict):
+    """A ready rendition the source itself offers (TikTok, VK, Likee)."""
+
+    format: str
+    label: str
+    type: Literal["video", "audio"]
+    size_mb: Optional[float]
+    exact: bool
+    url: str
+    watermark: NotRequired[Optional[bool]]
+
+
+class Meta(TypedDict, total=False):
+    title: Optional[str]
+    text: Optional[str]
+    author: Optional[str]
+    author_url: Optional[str]
+    thumbnail: Optional[str]
+    duration: Optional[float]
+    views: Optional[int]
+    published_at: Optional[int]
+    username: Optional[str]
+    author_avatar: Optional[str]
+    author_verified: Optional[bool]
+    likes: Optional[int]
+    comments: Optional[int]
+    shares: Optional[int]
+    saves: Optional[int]
+    location: Optional[str]
+    region: Optional[str]
+    music: Optional[dict]
+
+
+class DownloadResult(TypedDict):
+    """``/v1/download`` and ``/v1/{platform}``."""
+
+    success: Literal[True]
+    platform: str
+    type: str
+    source_url: str
+    video_id: Optional[str]
+    medias: list[Media]
+    music: Optional[Media]
+    meta: Meta
+    formats: NotRequired[list[Format]]
+    recommended_format: NotRequired[Optional[str]]
+    credits: Credits
+
+
+class YouTubeFormat(TypedDict):
+    quality: str
+    file_size: Optional[int]
+    file_size_str: Optional[str]
+    exact: bool
+
+
+class YouTubeInfo(TypedDict):
+    success: Literal[True]
+    platform: Literal["youtube"]
+    source_url: str
+    video_id: str
+    title: str
+    author: Optional[str]
+    duration_seconds: Optional[int]
+    duration_str: Optional[str]
+    thumbnail: Optional[str]
+    is_short: bool
+    formats: list[YouTubeFormat]
+    audio_formats: list[YouTubeFormat]
+    credits: Credits
+
+
+class YouTubeLink(TypedDict):
+    success: Literal[True]
+    platform: Literal["youtube"]
+    source_url: str
+    video_id: str
+    url: str
+    filename: str
+    quality: str
+    mode: Literal["video", "audio"]
+    ext: str
+    file_size: Optional[int]
+    file_size_str: Optional[str]
+    exact: bool
+    seekable: bool
+    expires: int
+    title: str
+    duration_seconds: Optional[int]
+    duration_str: Optional[str]
+    thumbnail: Optional[str]
+    credits: Credits
+
+
+class Detection(TypedDict):
+    success: Literal[True]
+    supported: bool
+    platform: Optional[str]
+    name: NotRequired[Optional[str]]
+    host: NotRequired[Optional[str]]
+    formats: NotRequired[bool]
+
+
+YouTubeQuality = Literal["144p", "240p", "360p", "480p", "720p", "1080p", "mp3", "m4a"]

saveapi-0.1.0/tests/test_client.py

@@ -0,0 +1,163 @@
+import httpx
+import pytest
+
+from saveapi import AsyncSaveAPI, SaveAPI, SaveAPIError
+from saveapi import _client
+
+OK = {
+    "success": True, "platform": "tiktok", "type": "video",
+    "source_url": "https://www.tiktok.com/@a/video/1", "video_id": "1",
+    "medias": [{"type": "video", "url": "https://cdn/x.mp4", "ext": "mp4", "quality": None,
+                "width": 0, "height": 0, "size_mb": 1.0, "watermark": False}],
+    "music": None, "meta": {}, "credits": {"spent": 1.5, "remaining": 998.5},
+}
+
+
+def _error(status, code, headers=None):
+    return httpx.Response(status, json={"success": False, "error": {"code": code, "message": code.lower()}},
+                          headers=headers or {})
+
+
+def _client_with(handler, **kwargs):
+    return SaveAPI("sk_test", http_client=httpx.Client(transport=httpx.MockTransport(handler)), **kwargs)
+
+
+@pytest.fixture(autouse=True)
+def no_sleep(monkeypatch):
+    slept = []
+    monkeypatch.setattr(_client.time, "sleep", slept.append)
+
+    async def fake_async_sleep(seconds):
+        slept.append(seconds)
+
+    monkeypatch.setattr(_client.asyncio, "sleep", fake_async_sleep)
+    return slept
+
+
+def test_download_sends_bearer_key_and_url():
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers["Authorization"]
+        seen["path"] = request.url.path
+        seen["params"] = dict(request.url.params)
+        seen["ua"] = request.headers["User-Agent"]
+        return httpx.Response(200, json=OK)
+
+    result = _client_with(handler).download("https://www.tiktok.com/@a/video/1", full_meta=True)
+
+    assert result["medias"][0]["url"] == "https://cdn/x.mp4"
+    assert seen["auth"] == "Bearer sk_test"
+    assert seen["path"] == "/v1/download"
+    assert seen["params"] == {"url": "https://www.tiktok.com/@a/video/1", "full_meta": "true"}
+    assert seen["ua"].startswith("saveapi-python/")
+
+
+def test_false_flags_and_none_are_not_sent():
+    seen = {}
+
+    def handler(request):
+        seen["params"] = dict(request.url.params)
+        return httpx.Response(200, json=OK)
+
+    _client_with(handler).platform("tiktok", "https://t/1")
+    assert seen["params"] == {"url": "https://t/1"}
+
+
+def test_final_error_is_raised_without_retry(no_sleep):
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return _error(403, "PRIVATE_CONTENT")
+
+    with pytest.raises(SaveAPIError) as exc:
+        _client_with(handler, max_retries=3).download("https://t/1")
+
+    assert exc.value.code == "PRIVATE_CONTENT"
+    assert exc.value.status == 403
+    assert exc.value.retryable is False
+    assert len(calls) == 1
+    assert no_sleep == []
+
+
+def test_upstream_timeout_is_retried_once_by_default(no_sleep):
+    answers = iter([_error(504, "UPSTREAM_TIMEOUT"), httpx.Response(200, json=OK)])
+    result = _client_with(lambda request: next(answers)).download("https://t/1")
+    assert result["success"] is True
+    assert no_sleep == [1.0]
+
+
+def test_retries_are_bounded():
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return _error(502, "UPSTREAM_ERROR")
+
+    with pytest.raises(SaveAPIError):
+        _client_with(handler, max_retries=2).download("https://t/1")
+    assert len(calls) == 3
+
+
+def test_rate_limit_waits_for_retry_after(no_sleep):
+    answers = iter([_error(429, "RATE_LIMITED", {"Retry-After": "7"}), httpx.Response(200, json=OK)])
+    _client_with(lambda request: next(answers)).download("https://t/1")
+    assert no_sleep == [7.0]
+
+
+def test_quota_exceeded_is_final():
+    with pytest.raises(SaveAPIError) as exc:
+        _client_with(lambda request: _error(429, "QUOTA_EXCEEDED")).download("https://t/1")
+    assert exc.value.code == "QUOTA_EXCEEDED"
+    assert exc.value.retryable is False
+
+
+def test_key_from_environment(monkeypatch):
+    monkeypatch.setenv("SAVEAPI_KEY", "sk_env")
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers["Authorization"]
+        return httpx.Response(200, json={"success": True, "supported": True, "platform": "tiktok"})
+
+    SaveAPI(http_client=httpx.Client(transport=httpx.MockTransport(handler))).detect("https://t/1")
+    assert seen["auth"] == "Bearer sk_env"
+
+
+def test_missing_key_explains_where_to_get_one(monkeypatch):
+    monkeypatch.delenv("SAVEAPI_KEY", raising=False)
+    with pytest.raises(ValueError, match="saveapi.org"):
+        SaveAPI()
+
+
+def test_youtube_create_passes_quality():
+    seen = {}
+
+    def handler(request):
+        seen["params"] = dict(request.url.params)
+        return httpx.Response(200, json={"success": True, "url": "https://api.saveapi.org/tunnel?id=1"})
+
+    _client_with(handler).youtube_create("https://youtu.be/x", "mp3")
+    assert seen["params"] == {"url": "https://youtu.be/x", "quality": "mp3"}
+
+
+def test_instagram_profile_needs_username_or_url():
+    with pytest.raises(ValueError):
+        _client_with(lambda request: httpx.Response(200, json={})).instagram_profile()
+
+
+def test_non_json_error_still_raises():
+    with pytest.raises(SaveAPIError) as exc:
+        _client_with(lambda request: httpx.Response(502, text="<html>bad gateway</html>")).me()
+    assert exc.value.status == 502
+    assert exc.value.code == "HTTP_ERROR"
+
+
+async def test_async_client_retries_and_returns(no_sleep):
+    answers = iter([_error(504, "UPSTREAM_TIMEOUT"), httpx.Response(200, json=OK)])
+    transport = httpx.MockTransport(lambda request: next(answers))
+    async with AsyncSaveAPI("sk_test", http_client=httpx.AsyncClient(transport=transport)) as api:
+        result = await api.download("https://t/1")
+    assert result["platform"] == "tiktok"
+    assert no_sleep == [1.0]