saveapi 0.1.0__py3-none-any.whl

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/_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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+saveapi/__init__.py,sha256=-kD6hnrZA_RbpHGOA11CgLMwzYiX2_W6_8gsztDUYb4,416
+saveapi/_client.py,sha256=yGmN6Zhyf1Vw3u5dvUYCzRs97zSvkhqUUK0XaVpFG8c,9789
+saveapi/errors.py,sha256=rSz5w5cZ_rVATd3OEWRYubTWWA9BVbpJhMQcrV4gplY,1342
+saveapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+saveapi/types.py,sha256=2_e2BTsPmlAB_7TxsFYm1KXvLu8GCY3D7AbpGNqFEso,3105
+saveapi-0.1.0.dist-info/METADATA,sha256=-xt1pfPpMU9MeXccHJSXrlEQgq4FA2iTFx2eGC5Qe3g,4729
+saveapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+saveapi-0.1.0.dist-info/licenses/LICENSE,sha256=0zEE0_GdMg3sMgU9CMCgbg02qEutYVEGCxeJOBvrNgA,1068
+saveapi-0.1.0.dist-info/RECORD,,

saveapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

saveapi-0.1.0.dist-info/licenses/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.