getyoutubetranscript 0.2.0__py3-none-any.whl

getyoutubetranscript/__init__.py

@@ -0,0 +1,25 @@
+"""Python SDK for the GetYouTubeTranscript REST API.
+
+    from getyoutubetranscript import Client
+
+    client = Client(api_key="sk_live_...")
+    transcript = client.get_transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw")
+
+See https://getyoutubetranscript.com/docs for the full API reference.
+"""
+
+from .client import Client, signup, verify_signup
+from .exceptions import GetYouTubeTranscriptError
+from .types import Segment, TranscriptData
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Client",
+    "GetYouTubeTranscriptError",
+    "Segment",
+    "TranscriptData",
+    "signup",
+    "verify_signup",
+    "__version__",
+]

getyoutubetranscript/client.py

@@ -0,0 +1,450 @@
+"""HTTP client for the GetYouTubeTranscript REST API.
+
+API reference: https://getyoutubetranscript.com/docs
+OpenAPI spec:  https://getyoutubetranscript.com/openapi.json
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from .exceptions import GetYouTubeTranscriptError
+from .types import TranscriptData
+
+DEFAULT_BASE_URL = "https://getyoutubetranscript.com/api/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _clean(params: dict[str, Any]) -> dict[str, Any]:
+    """Drop ``None`` values so optional query params are omitted entirely."""
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _send(
+    session: requests.Session,
+    method: str,
+    url: str,
+    *,
+    headers: Optional[dict[str, str]] = None,
+    params: Optional[dict[str, Any]] = None,
+    json_body: Optional[dict[str, Any]] = None,
+    timeout: float,
+) -> dict[str, Any]:
+    """Send one HTTP request and return the parsed JSON body.
+
+    Shared by :class:`Client` (authenticated endpoints) and the module-level
+    ``signup``/``verify_signup`` helpers (no API key needed), so request
+    sending and error parsing live in exactly one place.
+
+    Raises:
+        GetYouTubeTranscriptError: on any network failure, non-2xx status, or
+            a 2xx response whose body is ``{"success": false, ...}``.
+    """
+    try:
+        response = session.request(
+            method,
+            url,
+            headers=headers,
+            params=params,
+            json=json_body,
+            timeout=timeout,
+        )
+    except requests.RequestException as exc:
+        raise GetYouTubeTranscriptError(
+            code="NETWORK_ERROR",
+            message=str(exc),
+            status_code=0,
+        ) from exc
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    if not response.ok or not isinstance(payload, dict) or payload.get("success") is False:
+        code = "UNKNOWN_ERROR"
+        message = f"Request failed with HTTP status {response.status_code}"
+        if isinstance(payload, dict):
+            code = payload.get("code", code)
+            message = payload.get("message", message)
+        raise GetYouTubeTranscriptError(
+            code=code,
+            message=message,
+            status_code=response.status_code,
+            response_body=payload if isinstance(payload, dict) else None,
+        )
+
+    return payload
+
+
+class Client:
+    """Authenticated client for the GetYouTubeTranscript API.
+
+    Args:
+        api_key: Your API key (``sk_live_...``). Get one free (100 credits,
+            no card) at https://getyoutubetranscript.com, or via the
+            self-serve :func:`signup` / :func:`verify_signup` flow in this
+            module, which needs no key at all.
+        base_url: Override the API base URL. Defaults to the production
+            endpoint; mainly useful for testing against a local/staging copy.
+        timeout: Per-request timeout in seconds.
+        session: Bring your own ``requests.Session`` (e.g. for connection
+            pooling or custom retry/adapter configuration). One is created
+            for you otherwise.
+
+    Every method costs 1 credit unless its docstring says "free" - failed
+    and rate-limited requests are never charged. Every method raises
+    :class:`~getyoutubetranscript.GetYouTubeTranscriptError` on failure.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+        }
+
+    def _get(self, path: str, params: dict[str, Any]) -> dict[str, Any]:
+        return _send(
+            self._session,
+            "GET",
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=_clean(params),
+            timeout=self.timeout,
+        )
+
+    # -- transcript -----------------------------------------------------
+
+    def get_transcript(
+        self,
+        video: str,
+        *,
+        language: Optional[str] = None,
+        timestamps: bool = False,
+    ) -> TranscriptData:
+        """Get a YouTube video's transcript, plus title/author/thumbnail. 1 credit.
+
+        Args:
+            video: Full or short YouTube video URL, or an 11-character video ID.
+            language: Caption language code (e.g. ``"en"``, ``"es"``). Defaults
+                to the API's default of ``"en"`` when omitted.
+            timestamps: When ``True``, also return per-line timing in
+                ``segments``. Same 1 credit. The query param is only sent when
+                this is ``True``.
+
+        Returns:
+            dict with keys ``video_id``, ``language_code``, ``title``,
+            ``author_name``, ``author_url``, ``thumbnail_url``,
+            ``transcript`` (one block of text), and ``word_count``. With
+            ``timestamps=True`` it also has ``segments``, a list of
+            ``{"start": float, "duration": float, "text": str}`` (seconds),
+            one per caption line.
+
+        Raises:
+            GetYouTubeTranscriptError: e.g. ``code="NOT_FOUND"`` (HTTP 404) if
+                the video has no transcript/captions available.
+        """
+        payload = self._get(
+            "/transcript",
+            {"v": video, "language": language, "timestamps": "true" if timestamps else None},
+        )
+        return payload["data"]
+
+    # -- search -----------------------------------------------------------
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        *,
+        page_token: Optional[str] = None,
+        type: Optional[str] = None,
+        country: Optional[str] = None,
+        language: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """Search YouTube for videos or channels. 1 credit.
+
+        Args:
+            query: Search query. Required for a first page unless
+                ``page_token`` is given.
+            page_token: Continuation token from a previous response's
+                ``pagination.next_page_token``, to fetch the next page. Treat
+                as opaque - don't construct it yourself.
+            type: Restrict results to ``"video"`` (default) or ``"channel"``.
+                Never mixes both kinds in one response.
+            country: Two-letter region code, e.g. ``"us"``.
+            language: Result language hint, e.g. ``"en"``.
+            limit: Max results to return for this page.
+
+        Returns:
+            dict with ``query``, and either ``video_results`` or
+            ``channel_results`` depending on ``type``, plus
+            ``pagination.next_page_token`` when more results are available.
+
+        Raises:
+            ValueError: if neither ``query`` nor ``page_token`` is given.
+            GetYouTubeTranscriptError: on API failure.
+        """
+        if not query and not page_token:
+            raise ValueError("search() requires either 'query' or 'page_token'")
+        payload = self._get(
+            "/search",
+            {
+                "q": query,
+                "page_token": page_token,
+                "type": type,
+                "country": country,
+                "language": language,
+                "limit": limit,
+            },
+        )
+        return payload["data"]
+
+    # -- channels -----------------------------------------------------------
+
+    def resolve_channel(self, handle: str) -> dict[str, Any]:
+        """Resolve a channel @handle, URL, or ``UC...`` id to its channel ID. Free.
+
+        Args:
+            handle: Channel ``@handle``, a channel URL, or an existing
+                ``UC...`` channel id.
+
+        Returns:
+            dict with ``channel_id``, ``title``, ``handle``, ``resolved_via``.
+
+        Raises:
+            GetYouTubeTranscriptError: e.g. ``code="NOT_FOUND"`` (HTTP 404) if
+                no channel matches.
+        """
+        payload = self._get("/resolve", {"handle": handle})
+        return payload["data"]
+
+    def get_channel_latest(self, channel: str) -> dict[str, Any]:
+        """Get a channel's metadata plus its home-tab "Latest Videos" shelf. Free.
+
+        For the complete, paginated upload history use
+        :meth:`list_channel_videos` instead.
+
+        Args:
+            channel: Channel ``@handle``, URL, or ``UC...`` id.
+
+        Returns:
+            dict of channel metadata plus a home-tab video shelf. The exact
+            field set is passed through from upstream and may grow over
+            time - treat it as loosely typed.
+
+        Raises:
+            GetYouTubeTranscriptError: e.g. ``code="NOT_FOUND"`` (HTTP 404) if
+                the channel doesn't exist.
+        """
+        payload = self._get("/channel/latest", {"channel": channel})
+        return payload["data"]
+
+    def search_channel(
+        self,
+        channel: Optional[str] = None,
+        query: Optional[str] = None,
+        *,
+        continuation: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Search within one channel's videos. 1 credit.
+
+        Args:
+            channel: Channel ``@handle``, URL, or ``UC...`` id. Required for a
+                first page unless ``continuation`` is given.
+            query: Query to search within the channel. Required for a first
+                page unless ``continuation`` is given.
+            continuation: Continuation token from a previous response's
+                ``continuation_token``, to fetch the next page.
+
+        Returns:
+            dict with ``videos`` (list), ``has_more`` (bool), and
+            ``continuation_token`` (present when ``has_more`` is true).
+
+        Raises:
+            ValueError: if ``continuation`` is not given and either
+                ``channel`` or ``query`` is missing.
+            GetYouTubeTranscriptError: on API failure.
+        """
+        if not continuation and (not channel or not query):
+            raise ValueError(
+                "search_channel() requires either 'continuation', or both "
+                "'channel' and 'query'"
+            )
+        payload = self._get(
+            "/channel/search",
+            {"channel": channel, "q": query, "continuation": continuation},
+        )
+        return payload["data"]
+
+    def list_channel_videos(
+        self, channel: Optional[str] = None, *, continuation: Optional[str] = None
+    ) -> dict[str, Any]:
+        """List every video a channel has ever uploaded (paginated). 1 credit.
+
+        This is the channel's full ``/videos`` tab - not just the home-tab
+        shelf :meth:`get_channel_latest` returns.
+
+        Args:
+            channel: Channel ``@handle``, URL, or ``UC...`` id. Required for a
+                first page unless ``continuation`` is given.
+            continuation: Continuation token from a previous response's
+                ``continuation_token``, to fetch the next page.
+
+        Returns:
+            dict with ``videos`` (list), ``has_more`` (bool), and
+            ``continuation_token`` (present when ``has_more`` is true).
+
+        Raises:
+            ValueError: if neither ``channel`` nor ``continuation`` is given.
+            GetYouTubeTranscriptError: e.g. ``code="NOT_FOUND"`` (HTTP 404) if
+                the channel doesn't exist.
+        """
+        if not channel and not continuation:
+            raise ValueError(
+                "list_channel_videos() requires either 'channel' or 'continuation'"
+            )
+        payload = self._get(
+            "/channel/videos", {"channel": channel, "continuation": continuation}
+        )
+        return payload["data"]
+
+    # -- playlists -----------------------------------------------------------
+
+    def get_playlist(
+        self, list_id: Optional[str] = None, *, continuation: Optional[str] = None
+    ) -> dict[str, Any]:
+        """List every video in a playlist (paginated). 1 credit.
+
+        Args:
+            list_id: Playlist ID or URL. Required for a first page unless
+                ``continuation`` is given.
+            continuation: Continuation token from a previous response's
+                ``continuation_token``, to fetch the next page.
+
+        Returns:
+            dict with ``playlist_id``, ``title``, ``videos`` (list),
+            ``has_more`` (bool), and ``continuation_token`` (present when
+            ``has_more`` is true).
+
+        Raises:
+            ValueError: if neither ``list_id`` nor ``continuation`` is given.
+            GetYouTubeTranscriptError: e.g. ``code="NOT_FOUND"`` (HTTP 404) if
+                the playlist is missing, private, or deleted.
+        """
+        if not list_id and not continuation:
+            raise ValueError("get_playlist() requires either 'list_id' or 'continuation'")
+        payload = self._get("/playlist", {"list": list_id, "continuation": continuation})
+        return payload["data"]
+
+    # -- account -----------------------------------------------------------
+
+    def get_credits(self) -> dict[str, Any]:
+        """Check the remaining credit balance and plan for this API key. Free.
+
+        Returns:
+            dict with ``plan_credits_left``, ``topup_credits_left``, ``plan``
+            (one of ``"free"``, ``"monthly"``, ``"yearly"``), and
+            ``rate_limit_per_minute``.
+
+        Raises:
+            GetYouTubeTranscriptError: e.g. ``code="MISSING_API_KEY"``
+                (HTTP 401) if no API key is provided.
+        """
+        payload = self._get("/credits", {})
+        return payload["data"]
+
+
+# -- self-serve signup, no API key required --------------------------------
+
+
+def signup(
+    email: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = DEFAULT_TIMEOUT,
+    session: Optional[requests.Session] = None,
+) -> str:
+    """Request a 6-digit email OTP to create or access an API key. Free, no key needed.
+
+    Step 1 of the self-serve signup flow. Follow with :func:`verify_signup`
+    once the caller has the code from their inbox. The code is valid for 10
+    minutes.
+
+    Args:
+        email: Address to send the one-time code to.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+        session: Optional ``requests.Session`` to reuse.
+
+    Returns:
+        The confirmation message string from the API.
+
+    Raises:
+        GetYouTubeTranscriptError: e.g. ``code="BAD_REQUEST"`` (HTTP 400) if
+            the email is missing or malformed.
+    """
+    payload = _send(
+        session or requests.Session(),
+        "POST",
+        f"{base_url.rstrip('/')}/signup",
+        json_body={"email": email},
+        timeout=timeout,
+    )
+    return payload.get("message", "")
+
+
+def verify_signup(
+    email: str,
+    otp: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = DEFAULT_TIMEOUT,
+    session: Optional[requests.Session] = None,
+) -> str:
+    """Verify the OTP from :func:`signup` and mint a fresh API key. Free, no key needed.
+
+    Step 2 of the self-serve signup flow. Creates the account if it doesn't
+    exist yet, or signs in an existing one, either way returning a freshly
+    minted API key.
+
+    Args:
+        email: The same address passed to :func:`signup`.
+        otp: The 6-digit code the caller received by email.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+        session: Optional ``requests.Session`` to reuse.
+
+    Returns:
+        The raw API key string (``sk_live_...``). It is shown once here and
+        cannot be retrieved again - the caller is responsible for storing it.
+
+    Raises:
+        GetYouTubeTranscriptError: e.g. ``code="BAD_REQUEST"`` (HTTP 400) if
+            fields are missing or the code is invalid/expired.
+    """
+    payload = _send(
+        session or requests.Session(),
+        "POST",
+        f"{base_url.rstrip('/')}/signup/verify",
+        json_body={"email": email, "otp": otp},
+        timeout=timeout,
+    )
+    return payload["api_key"]

getyoutubetranscript/exceptions.py

@@ -0,0 +1,50 @@
+"""Exceptions raised by the GetYouTubeTranscript SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class GetYouTubeTranscriptError(Exception):
+    """Raised whenever the API returns a non-2xx status or ``{"success": false}``.
+
+    The API always responds to errors with a JSON body shaped like
+    ``{"success": false, "code": "...", "message": "..."}``. This exception
+    parses that shape so callers can branch on ``code`` instead of guessing
+    from an HTTP status or a generic exception message.
+
+    Common codes: ``MISSING_API_KEY``, ``INVALID_API_KEY``, ``RATE_LIMITED``,
+    ``PAYMENT_REQUIRED``, ``NOT_FOUND``. ``NETWORK_ERROR`` is used locally by
+    this SDK (status_code 0) when the request never reached the server at all
+    (DNS failure, timeout, connection refused, etc).
+
+    Attributes:
+        code: Machine-readable error code from the API's ``code`` field.
+        message: Human-readable message from the API's ``message`` field.
+        status_code: HTTP status code (400/401/402/404/429/503), or 0 if the
+            request never reached the server.
+        response_body: The full parsed JSON error body, if any, for callers
+            that need fields beyond ``code``/``message`` (e.g. ``RATE_LIMITED``
+            includes ``requestsThisMinute``; ``PAYMENT_REQUIRED`` includes
+            ``creditsLeft`` and ``topupCreditsLeft``).
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status_code: int,
+        *,
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body or {}
+        super().__init__(f"[{code}] {message} (HTTP {status_code})")
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"GetYouTubeTranscriptError(code={self.code!r}, "
+            f"message={self.message!r}, status_code={self.status_code!r})"
+        )

getyoutubetranscript/types.py

@@ -0,0 +1,33 @@
+"""Response types for the GetYouTubeTranscript API.
+
+These are ``TypedDict`` hints only: the client still returns plain dicts.
+"""
+
+from __future__ import annotations
+
+from typing import List, TypedDict
+
+
+class Segment(TypedDict):
+    """One caption line, returned in ``segments`` when ``timestamps=True``."""
+
+    start: float  # start time in seconds
+    duration: float  # duration in seconds
+    text: str
+
+
+class _TranscriptRequired(TypedDict):
+    video_id: str
+    language_code: str
+    title: str
+    author_name: str
+    author_url: str
+    thumbnail_url: str
+    transcript: str
+    word_count: int
+
+
+class TranscriptData(_TranscriptRequired, total=False):
+    """Result of :meth:`Client.get_transcript`."""
+
+    segments: List[Segment]  # present only when timestamps=True

getyoutubetranscript-0.2.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: getyoutubetranscript
+Version: 0.2.0
+Summary: Python SDK for the GetYouTubeTranscript REST API - transcripts, search, channels, and playlists
+Project-URL: Homepage, https://getyoutubetranscript.com
+Project-URL: Documentation, https://getyoutubetranscript.com/docs
+Project-URL: Repository, https://github.com/tubeagentkit/youtube-transcript-api-python
+Project-URL: Bug Tracker, https://github.com/tubeagentkit/youtube-transcript-api-python/issues
+Author: tubeagentkit
+License: MIT
+License-File: LICENSE
+Keywords: api-client,sdk,transcript,youtube,youtube-api
+Classifier: Development Status :: 4 - Beta
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# YouTube Transcript API: Python SDK
+
+[![License](https://img.shields.io/badge/License-MIT-4CAF50?style=for-the-badge)](./LICENSE)
+[![Website](https://img.shields.io/badge/Website-getyoutubetranscript.com-FF3B00?style=for-the-badge)](https://getyoutubetranscript.com)
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org)
+
+The official Python SDK (`getyoutubetranscript`) for the [GetYouTubeTranscript](https://getyoutubetranscript.com) YouTube Transcript API. Get YouTube video transcripts in Python without a Google API key, yt-dlp, or a headless browser. Get YouTube transcripts, search videos and channels, resolve channel handles, browse a channel's full upload history, search inside a channel, pull playlist contents, and check your credit balance, all with one typed client.
+
+Not published to PyPI yet - install straight from this repo.
+
+## Install
+
+```bash
+pip install git+https://github.com/tubeagentkit/youtube-transcript-api-python.git
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from getyoutubetranscript import Client
+
+client = Client(api_key="sk_live_...")
+
+transcript = client.get_transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw")
+print(transcript["title"], transcript["word_count"])
+print(transcript["transcript"])
+```
+
+## Getting an API key
+
+Every request needs an API key. There are two ways to get one:
+
+1. **Dashboard** - sign up at [getyoutubetranscript.com](https://getyoutubetranscript.com). Free tier: 100 credits, no card required.
+2. **Self-serve, in code** - use the `signup`/`verify_signup` helpers below. No key required for either call.
+
+```python
+from getyoutubetranscript import signup, verify_signup
+
+signup("you@example.com")          # sends a 6-digit code, valid 10 minutes
+# ... read the code from your inbox ...
+api_key = verify_signup("you@example.com", "123456")  # -> "sk_live_..."
+```
+
+The raw key is returned once by `verify_signup` and can't be retrieved again - store it yourself (env var, secret manager, etc).
+
+## Usage
+
+Every method costs 1 credit unless noted "free" below. Failed and rate-limited requests are never charged. All methods raise `GetYouTubeTranscriptError` on failure - see [Error handling](#error-handling).
+
+### Transcripts
+
+```python
+client.get_transcript("jNQXAC9IVRw", language="en")
+```
+
+Pass `timestamps=True` to also get one entry per caption line in `segments` (same 1 credit). Without it, the response has no `segments` key.
+
+```python
+result = client.get_transcript("5e37ZT3SQbk", timestamps=True)
+print(result["segments"][0])
+# {"start": 3.96, "duration": 4.56, "text": "So, Reed, education, which a lot of"}
+```
+
+Each segment is `{"start", "duration", "text"}` with `start` and `duration` in seconds. The `Segment` and `TranscriptData` typed dicts are importable from `getyoutubetranscript`.
+
+### Search
+
+```python
+client.search("lofi beats", type="video", limit=10)
+
+# Pagination
+page2 = client.search(page_token=first_page["pagination"]["next_page_token"])
+```
+
+### Channels
+
+```python
+client.resolve_channel("@mkbhd")            # free - handle/URL -> channel ID
+client.get_channel_latest("@mkbhd")         # free - metadata + latest uploads
+client.search_channel("@mkbhd", "iphone")   # search within a channel
+client.list_channel_videos("@mkbhd")        # full paginated upload history
+
+# Pagination (search_channel and list_channel_videos both work the same way)
+page = client.list_channel_videos("@mkbhd")
+while page["has_more"]:
+    page = client.list_channel_videos(continuation=page["continuation_token"])
+```
+
+### Playlists
+
+```python
+page = client.get_playlist("PLillGF-RfqbYE6Ik_EuXA2iZFcE082B3s")
+while page["has_more"]:
+    page = client.get_playlist(continuation=page["continuation_token"])
+```
+
+### Account
+
+```python
+client.get_credits()  # free - plan_credits_left, topup_credits_left, plan, rate_limit_per_minute
+```
+
+## Error handling
+
+Every non-2xx or `{"success": false}` response raises `GetYouTubeTranscriptError` with the API's parsed error shape:
+
+```python
+from getyoutubetranscript import Client, GetYouTubeTranscriptError
+
+client = Client(api_key="sk_live_...")
+
+try:
+    client.get_transcript("no-captions-here")
+except GetYouTubeTranscriptError as e:
+    print(e.code)          # e.g. "NOT_FOUND"
+    print(e.message)       # human-readable message from the API
+    print(e.status_code)   # 400 / 401 / 402 / 404 / 429 / 503, or 0 for a local network failure
+    print(e.response_body) # full parsed error body, e.g. {"creditsLeft": 0} on PAYMENT_REQUIRED
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+
+# Unit tests - mocked HTTP, no network or API key needed, always safe to run
+pytest tests -v --ignore=tests/live
+
+# Live integration tests - hits the real API, spends credits, needs a key
+GYT_API_KEY=sk_live_... pytest tests/live -v
+```
+
+## Links
+
+- [Full API docs](https://getyoutubetranscript.com/docs)
+- [OpenAPI spec](https://getyoutubetranscript.com/openapi.json)
+- [MCP server](https://getyoutubetranscript.com/youtube-mcp-server) - if you want an AI agent to call this API directly instead of via Python
+
+## Related projects
+
+Other ways to use the [GetYouTubeTranscript API](https://getyoutubetranscript.com):
+
+- [youtube-transcript-api](https://github.com/tubeagentkit/youtube-transcript-api): YouTube Transcript API docs, endpoint reference, OpenAPI spec and examples in curl, Python, JavaScript, Go and PHP
+- [youtube-transcript-api-node](https://github.com/tubeagentkit/youtube-transcript-api-node): YouTube Transcript API SDK for Node.js / TypeScript
+- [youtube-mcp](https://github.com/tubeagentkit/youtube-mcp): Remote YouTube MCP server for Claude, ChatGPT, Cursor and VS Code
+- [youtube-transcript-skills](https://github.com/tubeagentkit/youtube-transcript-skills): YouTube transcript Agent Skill for Claude Code, Cursor, Codex and OpenClaw
+- [youtube-transcript-cursor-plugin](https://github.com/tubeagentkit/youtube-transcript-cursor-plugin): YouTube Transcript Cursor plugin bundling the MCP server, skills, commands and a research agent
+- [n8n-nodes-getyoutubetranscript](https://github.com/tubeagentkit/n8n-nodes-getyoutubetranscript): YouTube transcript n8n community node, also usable as an AI Agent tool
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

getyoutubetranscript-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+getyoutubetranscript/__init__.py,sha256=d95jT5XHIg5NF9IPxZj1Qc115ywZ_n9INYuaX0dr39Q,623
+getyoutubetranscript/client.py,sha256=VKmIZthsqsbsclbgHYQLz2g8apeaOMgGjnZQHO0wV2c,16262
+getyoutubetranscript/exceptions.py,sha256=1EClkyv0btejIzlyxRbsZ61T3spP57Ev-gFndfkkK14,2023
+getyoutubetranscript/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getyoutubetranscript/types.py,sha256=hUEx8X5gIqmNTdFNlhbigoGBhNjGvPGpTDW7-t2PxJc,785
+getyoutubetranscript-0.2.0.dist-info/METADATA,sha256=DfVl-5LdEUZw6FYXwDcRRlDpF-pzs4Fn9pGgiK3kUj0,7709
+getyoutubetranscript-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+getyoutubetranscript-0.2.0.dist-info/licenses/LICENSE,sha256=9BV44fzXqxv9egaqFNr-TvzhlWpNBTVX8TqxF6bIWek,1069
+getyoutubetranscript-0.2.0.dist-info/RECORD,,

getyoutubetranscript-0.2.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

getyoutubetranscript-0.2.0.dist-info/licenses/LICENSE

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