ytapi-sdk 0.1.0__py3-none-any.whl

ytapi/__init__.py

@@ -0,0 +1,22 @@
+"""Python client for the YTAPI HTTP API. https://docs.ytapi.dev"""
+
+from .client import YTAPI
+from .errors import (
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitedError,
+    ServerError,
+    YTAPIError,
+)
+
+__all__ = [
+    "AuthError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitedError",
+    "ServerError",
+    "YTAPI",
+    "YTAPIError",
+]
+__version__ = "0.1.0"

ytapi/client.py

@@ -0,0 +1,421 @@
+"""Sync client for https://api.ytapi.dev."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from typing import Any
+
+from .errors import (
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitedError,
+    ServerError,
+    YTAPIError,
+)
+from .models import (
+    TEXT_FORMATS,
+    BatchJob,
+    BatchSubmit,
+    BatchTask,
+    Channel,
+    ChannelLatest,
+    ChannelPlaylistsPage,
+    ChannelPlaylist,
+    ChannelVideo,
+    ChannelVideosPage,
+    DurationFilter,
+    PlaylistPage,
+    PlaylistVideo,
+    SearchItem,
+    SearchPage,
+    SearchSort,
+    SearchType,
+    SortBy,
+    Suggestions,
+    TrackPolicy,
+    Transcript,
+    TranscriptFormat,
+    UploadDate,
+    VideoBasicInfo,
+    VideoInfo,
+)
+
+_USER_AGENT = "ytapi-python/0.1.0 (+https://docs.ytapi.dev)"
+_ENV_KEYS = ("YTAPI_API_KEY", "YTAPI_KEY")
+# A free account's daily limit answers 429 with Retry-After until 00:00 UTC.
+# Waiting that long inside a call would hang the caller, so it is raised.
+_DAILY_LIMIT_CODE = "daily_limit_exceeded"
+_ERROR_TYPES: dict[int, type[YTAPIError]] = {
+    401: AuthError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    429: RateLimitedError,
+}
+
+
+class YTAPI:
+    """Synchronous YTAPI client.
+
+    ``api_key`` falls back to the ``YTAPI_API_KEY`` environment variable,
+    then ``YTAPI_KEY``.
+
+    ``max_retries`` is the number of extra attempts after the first. They are
+    used for HTTP 429, 5xx and network errors (timeouts, dropped connections),
+    unless the body sets ``retryable`` to false. A 429 whose ``Retry-After`` is
+    longer than ``max_retry_wait`` seconds, such as a free account's daily
+    limit, is raised at once instead of waited out. ``max_retries=0`` disables
+    retries. Creating a batch is never retried after a 5xx or a network error,
+    since the job may already exist.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://api.ytapi.dev",
+        timeout: float = 30,
+        max_retries: int = 2,
+        backoff: float = 0.5,
+        backoff_cap: float = 8,
+        max_retry_wait: float = 60,
+        sleep: Callable[[float], None] = time.sleep,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        key = api_key
+        if key is None:
+            key = next((os.environ[name] for name in _ENV_KEYS if os.environ.get(name)), None)
+        if not key:
+            raise ValueError("Pass api_key or set the YTAPI_API_KEY environment variable.")
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0.")
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff = backoff
+        self.backoff_cap = backoff_cap
+        self.max_retry_wait = max_retry_wait
+        self._sleep = sleep
+        self._monotonic = monotonic
+
+    def get_transcript(
+        self,
+        video_id: str,
+        *,
+        format: TranscriptFormat | None = None,
+        word_level: bool | None = None,
+        languages: Sequence[str] | None = None,
+        track_policy: TrackPolicy | None = None,
+    ) -> Transcript | str:
+        """Captions for one video. Text formats return the document as a string."""
+        body: dict[str, Any] = {"video_id": video_id}
+        if format is not None:
+            body["format"] = format
+        if word_level is not None:
+            body["word_level"] = word_level
+        if languages is not None:
+            body["languages"] = list(languages)
+        if track_policy is not None:
+            body["track_policy"] = track_policy
+        as_text = format in TEXT_FORMATS
+        return self._request("POST", "/v1/transcripts", json_body=body, as_text=as_text)
+
+    def get_basic_info(self, video_id: str) -> VideoBasicInfo:
+        """Title, duration, channel and caption languages. Costs 0 credits."""
+        return self._request("GET", f"/v1/videos/{_seg(video_id)}/basic-info")
+
+    def get_video_info(self, video_id: str) -> VideoInfo:
+        """Full metadata, including description, counts and chapters. 1 credit."""
+        return self._request("GET", f"/v1/videos/{_seg(video_id)}/video-info")
+
+    def get_playlist(self, playlist_id: str, *, cursor: str | None = None) -> PlaylistPage:
+        """One page of a playlist. Later pages carry videos only. 1 credit per page."""
+        return self._request(
+            "GET", f"/v1/playlists/{_seg(playlist_id)}", query={"cursor": cursor}
+        )
+
+    def iter_playlist_videos(self, playlist_id: str) -> Iterator[PlaylistVideo]:
+        """Every video in a playlist, following ``next_cursor``."""
+        yield from _pages(
+            lambda cursor: self.get_playlist(playlist_id, cursor=cursor),
+            "videos",
+        )
+
+    def get_channel(self, channel_id: str) -> Channel:
+        """Channel profile. ``channel_id`` may be ``@handle`` or ``UC...``. 1 credit."""
+        return self._request("GET", f"/v1/channels/{_seg(channel_id)}")
+
+    def get_channel_latest(self, channel_id: str) -> ChannelLatest:
+        """The latest upload and a short list of recent videos. 1 credit."""
+        return self._request("GET", f"/v1/channels/{_seg(channel_id)}/latest")
+
+    def list_channel_videos(
+        self,
+        channel_id: str,
+        *,
+        cursor: str | None = None,
+        sort_by: SortBy | None = None,
+    ) -> ChannelVideosPage:
+        """One page of uploads. 1 credit per page."""
+        return self._request(
+            "GET",
+            f"/v1/channels/{_seg(channel_id)}/videos",
+            query={"cursor": cursor, "sort_by": sort_by},
+        )
+
+    def iter_channel_videos(
+        self, channel_id: str, *, sort_by: SortBy | None = None
+    ) -> Iterator[ChannelVideo]:
+        """Every upload, following ``next_cursor``. ``sort_by`` is sent on each page."""
+        yield from _pages(
+            lambda cursor: self.list_channel_videos(
+                channel_id, cursor=cursor, sort_by=sort_by
+            ),
+            "videos",
+        )
+
+    def list_channel_playlists(
+        self, channel_id: str, *, cursor: str | None = None
+    ) -> ChannelPlaylistsPage:
+        """One page of the channel's playlists. 1 credit per page."""
+        return self._request(
+            "GET",
+            f"/v1/channels/{_seg(channel_id)}/playlists",
+            query={"cursor": cursor},
+        )
+
+    def iter_channel_playlists(self, channel_id: str) -> Iterator[ChannelPlaylist]:
+        yield from _pages(
+            lambda cursor: self.list_channel_playlists(channel_id, cursor=cursor),
+            "playlists",
+        )
+
+    def search(
+        self,
+        query: str,
+        *,
+        type: SearchType | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+        upload_date: UploadDate | None = None,
+        duration: DurationFilter | None = None,
+        sort_by: SearchSort | None = None,
+    ) -> SearchPage:
+        """One page of search results. 1 credit per page."""
+        return self._request(
+            "GET",
+            "/v1/search",
+            query={
+                "q": query,
+                "type": type,
+                "limit": limit,
+                "cursor": cursor,
+                "upload_date": upload_date,
+                "duration": duration,
+                "sort_by": sort_by,
+            },
+        )
+
+    def iter_search(
+        self,
+        query: str,
+        *,
+        type: SearchType | None = None,
+        limit: int | None = None,
+        upload_date: UploadDate | None = None,
+        duration: DurationFilter | None = None,
+        sort_by: SearchSort | None = None,
+    ) -> Iterator[SearchItem]:
+        """Every search hit, following ``next_cursor``."""
+
+        def page(cursor: str | None) -> SearchPage:
+            return self.search(
+                query,
+                type=type,
+                limit=limit,
+                cursor=cursor,
+                upload_date=upload_date,
+                duration=duration,
+                sort_by=sort_by,
+            )
+
+        yield from _pages(page, "items")
+
+    def get_suggestions(self, query: str) -> Suggestions:
+        """Autocomplete strings. Costs 0 credits."""
+        return self._request("GET", "/v1/search/suggestions", query={"q": query})
+
+    def create_batch(
+        self, tasks: Sequence[BatchTask], *, concurrency: int | None = None
+    ) -> BatchSubmit:
+        """Start a batch of up to 100 tasks. Returns the job id; poll it with ``poll_batch``."""
+        body: dict[str, Any] = {"tasks": [dict(task) for task in tasks]}
+        if concurrency is not None:
+            body["concurrency"] = concurrency
+        # A 5xx or a dropped connection can come after the job was created, so
+        # a retry could start a second batch. Only 429 (nothing was created)
+        # is retried here.
+        return self._request("POST", "/v1/batch", json_body=body, retry_server_errors=False)
+
+    def get_batch(self, job_id: str) -> BatchJob:
+        """Status of a batch job. Free."""
+        return self._request("GET", f"/v1/batch/{_seg(job_id)}")
+
+    def poll_batch(
+        self, job_id: str, *, interval: float = 1, timeout: float = 120
+    ) -> BatchJob:
+        """Poll until status is ``completed`` or ``failed``, or ``timeout`` seconds pass."""
+        deadline = self._monotonic() + timeout
+        while True:
+            job = self.get_batch(job_id)
+            if job.get("status") in ("completed", "failed"):
+                return job
+            if self._monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Batch {job_id} still {job.get('status')!r} after {timeout} seconds."
+                )
+            self._sleep(interval)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        json_body: Mapping[str, Any] | None = None,
+        as_text: bool = False,
+        retry_server_errors: bool = True,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            pairs = [(key, value) for key, value in query.items() if value is not None]
+            if pairs:
+                url = url + "?" + urllib.parse.urlencode(pairs)
+        data = None if json_body is None else json.dumps(json_body).encode()
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json, text/plain, text/vtt, text/markdown",
+            "User-Agent": _USER_AGENT,
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    status = response.status
+                    raw = response.read()
+                    header_map = {key.lower(): value for key, value in response.headers.items()}
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                raw = exc.read()
+                header_map = {key.lower(): value for key, value in exc.headers.items()}
+            except (urllib.error.URLError, TimeoutError, ConnectionError, http.client.HTTPException) as exc:
+                reason = exc.reason if isinstance(exc, urllib.error.URLError) else exc
+                error = YTAPIError(f"Request failed: {reason}", status=0, retryable=True)
+                if attempt >= self.max_retries or not retry_server_errors:
+                    raise error from exc
+                self._sleep(self._backoff_delay(attempt))
+                attempt += 1
+                continue
+
+            if status in (200, 202):
+                if as_text:
+                    return raw.decode("utf-8")
+                if not raw:
+                    return {}
+                try:
+                    return json.loads(raw)
+                except json.JSONDecodeError as exc:
+                    raise YTAPIError(
+                        f"Expected JSON from {method} {path}, got: {raw[:200]!r}",
+                        status=status,
+                        retryable=False,
+                    ) from exc
+
+            error = _error_from(status, header_map, raw)
+            if attempt >= self.max_retries or not _should_retry(
+                error, retry_server_errors, self.max_retry_wait
+            ):
+                raise error
+            delay = self._backoff_delay(attempt)
+            if error.retry_after is not None:
+                delay = max(delay, error.retry_after)
+            self._sleep(delay)
+            attempt += 1
+
+    def _backoff_delay(self, attempt: int) -> float:
+        return min(self.backoff_cap, self.backoff * (2**attempt))
+
+
+def _seg(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _should_retry(
+    error: YTAPIError, retry_server_errors: bool = True, max_retry_wait: float = 60
+) -> bool:
+    if error.retryable is False:
+        return False
+    if error.status == 429:
+        if error.code == _DAILY_LIMIT_CODE:
+            return False
+        return error.retry_after is None or error.retry_after <= max_retry_wait
+    return retry_server_errors and error.status >= 500
+
+
+def _error_from(status: int, headers: Mapping[str, str], raw: bytes) -> YTAPIError:
+    retry_after = _retry_after(headers.get("retry-after"))
+    message = raw.decode("utf-8", "replace")
+    code: str | None = None
+    retryable: bool | None = None
+    try:
+        payload = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        payload = None
+    if isinstance(payload, dict):
+        err = payload.get("error")
+        if isinstance(err, dict):
+            code = err.get("code") if isinstance(err.get("code"), str) else None
+            if isinstance(err.get("message"), str):
+                message = err["message"]
+            if isinstance(err.get("retryable"), bool):
+                retryable = err["retryable"]
+    kind = _ERROR_TYPES.get(status, ServerError if status >= 500 else YTAPIError)
+    return kind(
+        message, status=status, code=code, retryable=retryable, retry_after=retry_after
+    )
+
+
+def _retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _pages(fetch_page: Callable[[str | None], Mapping[str, Any]], key: str) -> Iterator[Any]:
+    cursor: str | None = None
+    seen: set[str] = set()
+    while True:
+        page = fetch_page(cursor)
+        items = page.get(key) or []
+        yield from items
+        next_cursor = page.get("next_cursor")
+        # Stop on a repeated cursor rather than loop forever.
+        if not page.get("has_more") or not next_cursor or next_cursor in seen:
+            return
+        seen.add(next_cursor)
+        cursor = next_cursor

ytapi/errors.py

@@ -0,0 +1,50 @@
+"""Errors raised by the YTAPI client.
+
+The API returns ``{"error": {"code", "message", "retryable"}}``.
+"""
+
+from __future__ import annotations
+
+
+class YTAPIError(Exception):
+    """Base error. ``status`` is the HTTP status, or 0 for a network error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None = None,
+        retryable: bool | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retryable = retryable
+        self.retry_after = retry_after
+
+
+class AuthError(YTAPIError):
+    """401. The API key is missing or rejected."""
+
+
+class InsufficientCreditsError(YTAPIError):
+    """402. The credit balance cannot cover the call."""
+
+
+class NotFoundError(YTAPIError):
+    """404. ``code`` is captions_disabled, language_not_found, video_unavailable, or another not-found code."""
+
+
+class RateLimitedError(YTAPIError):
+    """429. ``retry_after`` is the wait the server asked for, in seconds.
+
+    ``code`` is ``rate_limited`` for a burst over the key's rate (retried
+    automatically) or ``daily_limit_exceeded`` when a free account used its
+    requests for the day (raised at once; it resets at 00:00 UTC).
+    """
+
+
+class ServerError(YTAPIError):
+    """5xx. Retried when ``retryable`` is not explicitly false."""

ytapi/models.py

@@ -0,0 +1,263 @@
+"""Response shapes documented at https://docs.ytapi.dev.
+
+Fields are optional in the type because pages after the first omit some of
+them (a playlist page after the first carries videos only). The client
+returns the JSON object as decoded; it does not drop unknown keys.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+TranscriptFormat = Literal[
+    "segments",
+    "word_timestamps",
+    "sentences",
+    "markdown",
+    "text",
+    "srt",
+    "vtt",
+    "json3",
+]
+TrackPolicy = Literal["manual_first", "asr_first", "exact_only"]
+SearchType = Literal["video", "channel", "playlist", "shorts", "movie"]
+SortBy = Literal["newest", "popular", "oldest"]
+UploadDate = Literal["hour", "today", "week", "month", "year"]
+DurationFilter = Literal["short", "medium", "long"]
+SearchSort = Literal["relevance", "rating", "upload_date", "view_count"]
+BatchTaskType = Literal["transcript", "basic_info"]
+BatchStatus = Literal["pending", "processing", "completed", "failed"]
+
+JSON_FORMATS = frozenset({"segments", "word_timestamps", "sentences", "json3"})
+TEXT_FORMATS = frozenset({"markdown", "text", "srt", "vtt"})
+
+
+class Thumbnail(TypedDict, total=False):
+    url: str
+    width: int
+    height: int
+
+
+class Word(TypedDict, total=False):
+    word: str
+    start: float
+    end: float
+
+
+class Segment(TypedDict, total=False):
+    text: str
+    start: float
+    end: float
+    duration: float
+    words: list[Word]
+
+
+class Transcript(TypedDict, total=False):
+    video_id: str
+    language: str
+    track_kind: Literal["manual", "asr"]
+    duration_seconds: float
+    has_word_level: bool
+    segments: list[Segment]
+
+
+class CaptionLanguage(TypedDict, total=False):
+    code: str
+    name: str
+    kind: str
+
+
+class BasicChannel(TypedDict, total=False):
+    id: str
+    title: str
+    url: str
+
+
+class VideoBasicInfo(TypedDict, total=False):
+    video_id: str
+    title: str
+    length_seconds: float
+    channel: BasicChannel
+    available_languages: list[CaptionLanguage]
+
+
+class VideoChannel(TypedDict, total=False):
+    id: str
+    title: str
+    url: str
+    subscribers: str
+    avatar_url: str
+
+
+class Chapter(TypedDict, total=False):
+    title: str
+    start_time_seconds: float
+    time_description: str
+
+
+class VideoInfo(TypedDict, total=False):
+    video_id: str
+    title: str
+    description: str
+    length_seconds: float
+    view_count: int
+    like_count: int
+    published: int
+    keywords: list[str]
+    channel: VideoChannel
+    thumbnails: list[Thumbnail]
+    available_languages: list[CaptionLanguage]
+    chapters: list[Chapter]
+
+
+class PlaylistVideo(TypedDict, total=False):
+    video_id: str
+    title: str
+    index: int
+    length_seconds: float
+    length_text: str
+    author: str
+
+
+class PlaylistPage(TypedDict, total=False):
+    playlist_id: str
+    title: str
+    video_count: int
+    view_count_text: str
+    author: str
+    thumbnails: list[Thumbnail]
+    videos: list[PlaylistVideo]
+    has_more: bool
+    next_cursor: str | None
+
+
+class Channel(TypedDict, total=False):
+    channel_id: str
+    title: str
+    handle: str
+    description: str
+    subscriber_count: int
+    subscriber_count_text: str
+    custom_url: str
+    country: str
+    video_count: int
+    verified: bool
+    thumbnails: list[Thumbnail]
+    banners: list[Thumbnail]
+    links: list[str]
+    available_tabs: list[str]
+
+
+class ChannelVideo(TypedDict, total=False):
+    video_id: str
+    title: str
+    length_text: str
+    view_count_text: str
+    published_text: str
+    thumbnails: list[Thumbnail]
+
+
+class ChannelLatest(TypedDict, total=False):
+    channel_id: str
+    channel_title: str
+    latest_video: ChannelVideo
+    recent_videos: list[ChannelVideo]
+
+
+class ChannelVideosPage(TypedDict, total=False):
+    channel_id: str
+    channel_title: str
+    has_more: bool
+    next_cursor: str | None
+    continuation: str | None
+    videos: list[ChannelVideo]
+
+
+class ChannelPlaylist(TypedDict, total=False):
+    playlist_id: str
+    title: str
+    video_count: int
+    video_count_text: str
+    thumbnails: list[Thumbnail]
+
+
+class ChannelPlaylistsPage(TypedDict, total=False):
+    playlists: list[ChannelPlaylist]
+    has_more: bool
+    next_cursor: str | None
+
+
+class SearchItem(TypedDict, total=False):
+    id: str
+    type: str
+    title: str
+    description: str
+    author: str
+    channel_id: str
+    length_seconds: float
+    length_text: str
+    view_count_text: str
+    published_text: str
+    thumbnails: list[Thumbnail]
+    handle: str
+    subscriber_count_text: str
+    video_count_text: str
+    badges: list[str]
+
+
+class SearchPage(TypedDict, total=False):
+    query: str
+    type: str
+    has_more: bool
+    next_cursor: str | None
+    items: list[SearchItem]
+
+
+class Suggestions(TypedDict, total=False):
+    query: str
+    suggestions: list[str]
+
+
+class BatchTask(TypedDict, total=False):
+    id: str
+    type: BatchTaskType
+    video_id: str
+    format: TranscriptFormat
+    languages: list[str]
+    track_policy: TrackPolicy
+    word_level: bool
+
+
+class BatchSubmit(TypedDict, total=False):
+    id: str
+    status: str
+    total: int
+    estimated_credits: int
+    created_at: str
+
+
+class BatchTaskError(TypedDict, total=False):
+    code: str
+    message: str
+
+
+class BatchTaskResult(TypedDict, total=False):
+    id: str
+    type: str
+    video_id: str
+    status: int
+    data: Any
+    error: BatchTaskError
+
+
+class BatchJob(TypedDict, total=False):
+    id: str
+    status: str
+    total: int
+    successful: int
+    failed: int
+    credits_deducted: int
+    duration_ms: int
+    results: list[BatchTaskResult]
+    created_at: str
+    completed_at: str | None

ytapi/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. This package ships inline type hints.

ytapi_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: ytapi-sdk
+Version: 0.1.0
+Summary: Python client for YTAPI: YouTube transcripts, video details, search, channels and playlists.
+Author: YTAPI
+License-Expression: MIT
+Project-URL: Documentation, https://docs.ytapi.dev
+Project-URL: Homepage, https://ytapi.dev
+Project-URL: Repository, https://github.com/ytapi/ytapi-python
+Project-URL: Issues, https://github.com/ytapi/ytapi-python/issues
+Keywords: youtube,transcript,captions,subtitles,youtube-transcript,ytapi
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# YTAPI Python client
+
+Python client for [YTAPI](https://ytapi.dev?utm_source=github): YouTube transcripts, video details, search, channels and playlists over one HTTP API. It works from servers and cloud functions, where fetching YouTube directly tends to get blocked.
+
+- No dependencies beyond the standard library. Python 3.10+.
+- Typed responses (`TypedDict`), typed errors, automatic retries and pagination.
+- Reference: [docs.ytapi.dev](https://docs.ytapi.dev).
+
+## Install
+
+```bash
+pip install ytapi-sdk
+```
+
+The package is `ytapi-sdk` on PyPI, and you import it as `ytapi`.
+
+## Quickstart
+
+Get a key at [ytapi.dev](https://ytapi.dev/app/api-keys?utm_source=github). New accounts get 200 free credits, and no card is needed.
+
+```python
+from ytapi import YTAPI
+
+api = YTAPI()  # reads YTAPI_API_KEY (or YTAPI_KEY) from the environment
+transcript = api.get_transcript("dQw4w9WgXcQ")
+for segment in transcript["segments"][:3]:
+    print(segment["start"], segment["text"])
+```
+
+By default you get the captions in the video's own language, as timed segments. A successful request uses 1 credit, and errors are free.
+
+## Examples
+
+```python
+# Other formats. markdown, text, srt and vtt come back as a string.
+srt = api.get_transcript("dQw4w9WgXcQ", format="srt")
+spanish = api.get_transcript("dQw4w9WgXcQ", format="text", languages=["es", "*"])
+words = api.get_transcript("dQw4w9WgXcQ", format="word_timestamps", word_level=True)
+
+# Free: title, length, channel and the caption languages a video has.
+basic = api.get_basic_info("dQw4w9WgXcQ")
+# 1 credit: description, counts, chapters and more.
+info = api.get_video_info("dQw4w9WgXcQ")
+
+# Channels take an @handle, a channel ID (UC...) or a URL.
+channel = api.get_channel("@3blue1brown")
+for video in api.iter_channel_videos("@3blue1brown", sort_by="popular"):
+    print(video["video_id"], video["title"])
+
+# Playlists, page by page or as an iterator.
+for video in api.iter_playlist_videos("PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi"):
+    print(video["video_id"], video["length_text"])
+
+# Search: type is video, channel, playlist, shorts or movie.
+page = api.search("rust async", type="video", upload_date="month", limit=10)
+for hit in page["items"]:
+    print(hit["title"])
+
+# Search suggestions are free.
+print(api.get_suggestions("nextjs")["suggestions"])
+
+# Batch: up to 100 transcript or basic_info tasks per job.
+job = api.create_batch(
+    [
+        {"id": "a", "type": "transcript", "video_id": "dQw4w9WgXcQ", "format": "text"},
+        {"id": "b", "type": "basic_info", "video_id": "jNQXAC9IVRw"},
+    ]
+)
+done = api.poll_batch(job["id"], timeout=120)
+print(done["successful"], done["credits_deducted"])
+```
+
+The iterators (`iter_playlist_videos`, `iter_channel_videos`, `iter_channel_playlists`, `iter_search`) follow `next_cursor` for you. Each page is a request and uses a credit. In a batch, each successful task uses 1 credit and failed tasks are free.
+
+## Errors
+
+```python
+from ytapi import InsufficientCreditsError, NotFoundError, RateLimitedError, YTAPIError
+
+try:
+    api.get_transcript("xxxxxxxxxxx")
+except NotFoundError as exc:
+    print(exc.code)  # captions_disabled, language_not_found, video_unavailable, ...
+except RateLimitedError as exc:
+    print(exc.code, exc.retry_after)  # rate_limited or daily_limit_exceeded
+except InsufficientCreditsError:
+    print("Out of credits: https://ytapi.dev/#pricing")
+except YTAPIError as exc:
+    print(exc.status, exc.code, exc)  # status 0 means a network error
+```
+
+| Status | Exception |
+| --- | --- |
+| 401 | `AuthError` |
+| 402 | `InsufficientCreditsError` |
+| 404 | `NotFoundError` |
+| 429 | `RateLimitedError` |
+| 5xx | `ServerError` |
+| network error | `YTAPIError` with `status` 0 |
+| other | `YTAPIError` |
+
+## Retries
+
+The client retries a 429, a 5xx or a network error up to `max_retries` times (default 2). It backs off from 0.5 seconds, doubling up to 8, and waits longer when the server sends `Retry-After`. A few cases are not retried:
+
+- **A 429 that asks for a long wait.** The cutoff is `max_retry_wait`, default 60 seconds. This includes a free account's daily limit (`daily_limit_exceeded`), which lasts until 00:00 UTC. The client raises these right away instead of hanging your program.
+- **Creating a batch after a 5xx or a network error.** The job may already exist, so a retry could start a second one.
+
+Use `YTAPI(max_retries=0)` to turn retries off.
+
+## Releases
+
+Each GitHub release publishes the matching version to [PyPI](https://pypi.org/project/ytapi-sdk/) through trusted publishing. The release tag must match the version in `pyproject.toml`, such as `v0.1.0`.
+
+## Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+The tests mock HTTP and need no network or API key.
+
+## License
+
+MIT

ytapi_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ytapi/__init__.py,sha256=6QS4chpaOTJxqIWBezXjM-f6VexoxBOakF9qJ_N16xw,418
+ytapi/client.py,sha256=28DejOFQmHGSaoCeU01PUTHENISkmUyu2sOlbM2ldno,15118
+ytapi/errors.py,sha256=afuYpEqwC64ZnwdwmRLTOonIcIKP_Almx3zBxwqyoaU,1402
+ytapi/models.py,sha256=vVy6DP3IgF_wD04pNit63Z0WUCfBLv3mQq57fYwIdrs,5611
+ytapi/py.typed,sha256=lgCyp9gZfAMplkwv75pxHXKdO1FqRCF61SzGRi14E-M,65
+ytapi_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=mz8MPcnKcM-hIdd8qsDd8DZKwF7X_WOvTGJlz7nOHjI,1062
+ytapi_sdk-0.1.0.dist-info/METADATA,sha256=cVh0N6m5kvqRYw-oTXtOF1cY38zfodv6ekoqGP3Q1sU,5514
+ytapi_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ytapi_sdk-0.1.0.dist-info/top_level.txt,sha256=ZnFvZDGQEUJ-jRMFP36VnigUI7CYDGl-L_6WqBC0kkI,6
+ytapi_sdk-0.1.0.dist-info/RECORD,,

ytapi_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ytapi_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YTAPI
+
+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.

ytapi_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ytapi