Release 1.0.0: full endpoint coverage, accurate platform docs

The public docs promise the SDKs follow semver, but 0.x reserves the right to
break anything. Freeze the surface at 1.0.0 and make it match the API first.

- Add me() and transcripts.job() to both the sync and async clients, which
  completes coverage of all 8 v1 endpoints.
- A 202 (no captions, so the API transcribes the audio) used to raise a Pydantic
  validation error, because Transcript.kind was pinned to the literal
  "transcript" while the 202 carries "transcript_job". kind is now a str and the
  envelope's status/job_id/poll_url are lifted onto the model, so the documented
  poll-until-done flow actually works.
- Document what the video/batch inputs really are: YouTube, TikTok, Instagram
  and direct media file URLs. Behavior is unchanged, the clients always passed
  the input straight through. channel/playlist/search stay described as
  YouTube-only, because that is what they are.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ksoEUHvR7DHdNujkGv8UT

Author: Chandler Casey

CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## [1.0.0] - 2026-08-05
+
+First stable release. The published docs promise the SDKs follow semver, and a
+0.x version explicitly reserves the right to break anything, so the surface is
+declared stable at 1.0.0 rather than contradicting that.
+
+- Full API coverage: added `me()` (validate the key + read the balance, free)
+  and `transcripts.job()` (poll an audio-transcription job), on both clients.
+- `transcripts.video` / `batch` are now documented as accepting any supported
+  source: YouTube, TikTok, Instagram, and direct media file URLs. `channel`,
+  `playlist` and `search` remain YouTube-only concepts. No behavior change; the
+  clients always passed the input through untouched.
+- Fixed: a 202 (no captions, so audio transcription started) raised a validation
+  error because `Transcript.kind` was pinned to `"transcript"`. It now returns a
+  `Transcript` with `status="processing"` and a `job_id` to poll.
+- New `Account` model; `Transcript` gains `status`, `job_id` and `poll_url`.
+
 ## [0.1.0] - Unreleased
 
 Initial release.

README.md

@@ -1,6 +1,8 @@
 # TranscriptFetch Python SDK
 
-Official, typed Python client for the [TranscriptFetch](https://transcriptfetch.com) API: fetch YouTube transcripts, channels, playlists, and search results as clean, structured data. Sync + async, fully type-hinted.
+Official, typed Python client for the [TranscriptFetch](https://transcriptfetch.com) API: fetch transcripts as clean, structured data, plus YouTube channel, playlist and search listings. Sync + async, fully type-hinted.
+
+Transcripts come from **YouTube, TikTok, Instagram, or a direct media file URL** (mp3/mp4/wav and friends). Channel, playlist and search are YouTube-only, since no other supported platform has those concepts.
 
 ```bash
 pip install transcriptfetch-sdk
@@ -14,7 +16,7 @@ from transcriptfetch import TranscriptFetch
 # api_key falls back to the TRANSCRIPTFETCH_API_KEY env var
 tf = TranscriptFetch(api_key="tf_live_...")
 
-t = tf.transcripts.video("https://youtu.be/aircAruvnKk")
+t = tf.transcripts.video("https://youtu.be/aircAruvnKk")   # or a TikTok / Instagram / file URL
 print(t.title)
 print(t.text)
 for seg in t.segments:
@@ -28,15 +30,31 @@ Get an API key (100 free credits) at <https://transcriptfetch.com/app>. One cred
 ## Endpoints
 
 ```python
-tf.transcripts.video(video)                    # single transcript (text + segments)
-tf.transcripts.channel(channel, limit=, cursor=)   # a channel's videos (metadata)
-tf.transcripts.playlist(playlist, limit=, cursor=) # a playlist's videos
+tf.transcripts.video(video)                        # single transcript (text + segments)
+tf.transcripts.batch(video_ids)                    # up to 50 transcripts in one call
+tf.transcripts.channel(channel, limit=, cursor=)   # a YouTube channel's videos (metadata)
+tf.transcripts.playlist(playlist, limit=, cursor=) # a YouTube playlist's videos
 tf.transcripts.search(query, limit=, cursor=)      # search YouTube
-tf.transcripts.batch(video_ids)                # up to 50 transcripts in one call
-tf.health()                                    # unauthenticated liveness probe
+tf.transcripts.job(job_id)                         # poll an audio-transcription job (free)
+tf.me()                                            # validate the key + read the balance (free)
+tf.health()                                        # unauthenticated liveness probe
 ```
 
-`video`/`channel`/`playlist` accept URLs or raw IDs (normalized automatically).
+`video` and `batch` take a YouTube, TikTok or Instagram URL, a direct media file URL, or a bare YouTube ID. `channel`/`playlist` take a URL, an `@handle`/`PL…` ID, or a raw ID. IDs and URLs are normalized automatically.
+
+## Videos without captions
+
+When a source has no captions, the API transcribes its audio and answers with a job instead of a transcript. That comes back as a `Transcript` with `status == "processing"` and a `job_id`; poll it for free until it completes:
+
+```python
+import time
+
+t = tf.transcripts.video("https://www.tiktok.com/@user/video/7137723462233555205")
+while t.status == "processing":
+    time.sleep(3)
+    t = tf.transcripts.job(t.job_id)
+print(t.text)
+```
 
 ## Pagination
 

examples/transcribe_job.py

@@ -0,0 +1,24 @@
+"""Fetch a source that may have no captions, then poll until it is transcribed.
+
+Any supported input works here: a YouTube, TikTok or Instagram URL, or a direct
+media file URL. When captions exist the first call already returns the text;
+when they do not, the API transcribes the audio and hands back a job to poll.
+Polling is free, so the loop below costs at most the one credit on delivery.
+"""
+
+import time
+
+from transcriptfetch import TranscriptFetch
+
+URL = "https://www.tiktok.com/@nasa/video/7137723462233555205"
+
+with TranscriptFetch() as tf:  # reads TRANSCRIPTFETCH_API_KEY
+    t = tf.transcripts.video(URL)
+
+    while t.status == "processing" and t.job_id:
+        print("transcribing…", t.job_id)
+        time.sleep(3)
+        t = tf.transcripts.job(t.job_id)
+
+    print("title:", t.title)
+    print("text:", (t.text or "(no transcript)")[:500])

pyproject.toml

@@ -5,14 +5,14 @@ build-backend = "hatchling.build"
 [project]
 name = "transcriptfetch-sdk"
 dynamic = ["version"]
-description = "Official Python SDK for the TranscriptFetch API: fetch YouTube transcripts, channels, playlists, and search as clean, typed data."
+description = "Official Python SDK for the TranscriptFetch API: fetch transcripts from YouTube, TikTok, Instagram and direct media URLs as clean, typed data."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.9"
 authors = [{ name = "TranscriptFetch", email = "support@transcriptfetch.com" }]
-keywords = ["youtube", "transcript", "captions", "subtitles", "api", "sdk", "rag", "llm"]
+keywords = ["youtube", "tiktok", "instagram", "transcript", "captions", "subtitles", "api", "sdk", "rag", "llm"]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",

src/transcriptfetch/__init__.py

@@ -26,6 +26,7 @@
     UpstreamUnavailableError,
 )
 from .models import (
+    Account,
     BatchResponse,
     BatchResult,
     Segment,
@@ -41,6 +42,7 @@
     "AsyncTranscriptFetch",
     # models
     "Usage",
+    "Account",
     "Segment",
     "Transcript",
     "Video",

src/transcriptfetch/_transport.py

@@ -16,6 +16,7 @@
 from ._config import ClientConfig
 from ._version import __version__
 from .errors import raise_api_error
+from .models import Usage
 
 USER_AGENT = f"transcriptfetch-python/{__version__}"
 
@@ -34,6 +35,12 @@ def build_headers(
     return headers
 
 
+def parse_usage(env: dict[str, Any]) -> Optional[Usage]:
+    """Lift the envelope-level ``usage`` block off a response, if present."""
+    raw = env.get("usage")
+    return Usage.model_validate(raw) if isinstance(raw, dict) else None
+
+
 def new_idempotency_key() -> str:
     return uuid.uuid4().hex
 

src/transcriptfetch/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "1.0.0"

src/transcriptfetch/async_client.py

@@ -15,8 +15,10 @@
     is_retryable,
     new_idempotency_key,
     parse_envelope,
+    parse_usage,
 )
 from .errors import APIConnectionError, APITimeoutError
+from .models import Account
 from .resources.transcripts import AsyncTranscripts
 
 
@@ -78,6 +80,13 @@ async def _request(
                 continue
             return parse_envelope(resp)
 
+    async def me(self) -> Account:
+        """Validate the API key and read the account's credit balance. Free."""
+        env = await self._request("GET", "/api/v1/me")
+        account = Account.model_validate(env.get("data") or {})
+        account.usage = parse_usage(env)
+        return account
+
     async def health(self) -> dict[str, Any]:
         """Unauthenticated liveness probe."""
         return await self._request("GET", "/api/v1/health", auth=False)

src/transcriptfetch/client.py

@@ -15,8 +15,10 @@
     is_retryable,
     new_idempotency_key,
     parse_envelope,
+    parse_usage,
 )
 from .errors import APIConnectionError, APITimeoutError
+from .models import Account
 from .resources.transcripts import Transcripts
 
 
@@ -75,6 +77,13 @@ def _request(
                 continue
             return parse_envelope(resp)
 
+    def me(self) -> Account:
+        """Validate the API key and read the account's credit balance. Free."""
+        env = self._request("GET", "/api/v1/me")
+        account = Account.model_validate(env.get("data") or {})
+        account.usage = parse_usage(env)
+        return account
+
     def health(self) -> dict[str, Any]:
         """Unauthenticated liveness probe."""
         return self._request("GET", "/api/v1/health", auth=False)

src/transcriptfetch/models.py

@@ -33,21 +33,43 @@ class Segment(_Model):
 
 
 class Transcript(_Model):
-    """A single video's transcript (``kind == "transcript"``)."""
+    """A single video's transcript, from any supported source.
 
-    kind: Literal["transcript"] = "transcript"
+    Also covers the "not ready yet" case. When a video has no captions the API
+    transcribes the audio and answers 202 with ``kind == "transcript_job"``,
+    which is why ``kind`` is a plain ``str``: pinning it to a literal would turn
+    a 202 into a validation error instead of a pollable job. In that case
+    ``text``/``segments`` are empty and ``status``/``job_id`` are set, so pass
+    ``job_id`` to ``transcripts.job()`` until ``status == "completed"``.
+    """
+
+    kind: str = "transcript"
     video_id: str = ""
     title: Optional[str] = None
     text: Optional[str] = None
     segments: List[Segment] = Field(default_factory=list)
     usage: Optional[Usage] = None
+    # Envelope-level fields, lifted onto the model so an async job round-trips
+    # as one object (the API returns them beside ``data``, not inside it).
+    status: Optional[str] = None  # "processing" | "completed", async jobs only
+    job_id: Optional[str] = None
+    poll_url: Optional[str] = None
 
     @field_validator("segments", mode="before")
     @classmethod
     def _null_segments_to_list(cls, v: Any) -> Any:
         return v or []
 
 
+class Account(_Model):
+    """The calling key's account (``kind == "me"``): identity + credit balance."""
+
+    kind: Literal["me"] = "me"
+    user_id: str = ""
+    credits: Optional[int] = None  # null for unlimited (admin) accounts
+    usage: Optional[Usage] = None
+
+
 class Video(_Model):
     """A video reference from a channel/playlist/search list (metadata only)."""