2.5.0: markdown and chunks on video() and batch()

Author: Transcript-Fetch-Admin

CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## [2.5.0] - 2026-10-28
+
+### Added
+
+- `markdown=` and `chunks=` on `transcripts.video()` and `transcripts.batch()`
+  (sync and async). `chunks=True`, or `{"max_tokens": 800, "overlap_tokens":
+  80}`, returns the transcript in pieces sized for an embedding model, each
+  with `start`, `end`, a `url` that opens the video at that moment, and its
+  token count (`Transcript.chunks`, typed as the new `Chunk`). `markdown=True`
+  returns a timestamped Markdown rendering (`Transcript.markdown`). Both are
+  free, and an audio-transcription job delivers them too. These are what the
+  LangChain and LlamaIndex integrations build on.
+
 ## [2.4.1] - 2026-10-02
 
 ### Fixed

src/transcriptfetch/__init__.py

@@ -33,6 +33,7 @@
     ApiErrorBlock,
     BatchResponse,
     BatchResult,
+    Chunk,
     Monitor,
     MonitorCheck,
     MonitorDeleted,
@@ -56,6 +57,7 @@
     VideoList,
     VideoStats,
 )
+from .resources.transcripts import ChunkOptions
 
 __all__ = [
     "__version__",
@@ -80,6 +82,8 @@
     # models
     "Usage",
     "Account",
+    "Chunk",
+    "ChunkOptions",
     "Segment",
     "Transcript",
     "Video",

src/transcriptfetch/_version.py

@@ -1 +1 @@
-__version__ = "2.4.1"
+__version__ = "2.5.0"

src/transcriptfetch/models.py

@@ -38,6 +38,24 @@ class Segment(_Model):
     speaker: Optional[int] = None
 
 
+class Chunk(_Model):
+    """One embedding-sized piece of a transcript (``chunks=`` on a request).
+
+    Pieces break between caption lines, never mid-word, and overlap the
+    previous piece slightly. ``start``/``end`` are seconds (``None`` when the
+    transcript has no timings); ``url`` opens the video at ``start`` on
+    YouTube and is the item's own link elsewhere; ``tokens`` is the piece's
+    size in OpenAI's o200k_base encoding.
+    """
+
+    index: int = 0
+    text: str = ""
+    start: Optional[float] = None
+    end: Optional[float] = None
+    url: Optional[str] = None
+    tokens: Optional[int] = None
+
+
 class Transcript(_Model):
     """A single video's transcript, from any supported source.
 
@@ -74,6 +92,12 @@ class Transcript(_Model):
     source: Optional[str] = None  # "captions" | "audio" (AI transcription); None on a 202
     text: Optional[str] = None
     segments: List[Segment] = Field(default_factory=list)
+    markdown: Optional[str] = None
+    """Set when the request asked for ``markdown=True``: title, channel, length
+    and link, then paragraphs that each open with a timestamp link."""
+    chunks: List[Chunk] = Field(default_factory=list)
+    """Set when the request asked for ``chunks``: the transcript in
+    embedding-sized pieces (see :class:`Chunk`). Empty otherwise."""
     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).
@@ -83,7 +107,7 @@ class Transcript(_Model):
     error: Optional["ApiErrorBlock"] = None
     """Why a job failed. Set only when ``status == "failed"``."""
 
-    @field_validator("segments", mode="before")
+    @field_validator("segments", "chunks", mode="before")
     @classmethod
     def _null_segments_to_list(cls, v: Any) -> Any:
         return v or []
@@ -188,6 +212,10 @@ class BatchResult(_Model):
     source: Optional[str] = None  # "captions" | "audio" on outcome "ok"
     text: Optional[str] = None
     segments: Optional[List[Segment]] = None
+    markdown: Optional[str] = None
+    """Set on ``outcome == "ok"`` when the batch asked for ``markdown=True``."""
+    chunks: Optional[List[Chunk]] = None
+    """Set on ``outcome == "ok"`` when the batch asked for ``chunks``."""
     job_id: Optional[str] = None
     """Set when ``outcome == "processing"``: the audio-transcription job that
     will deliver this entry."""

src/transcriptfetch/resources/transcripts.py

@@ -11,7 +11,17 @@
 
 from __future__ import annotations
 
-from typing import Any, AsyncIterator, Iterable, Iterator, Literal, Optional, Protocol
+from typing import (
+    Any,
+    AsyncIterator,
+    Iterable,
+    Iterator,
+    Literal,
+    Optional,
+    Protocol,
+    TypedDict,
+    Union,
+)
 
 from .._transport import parse_usage as _usage
 from ..models import ApiErrorBlock, BatchResponse, Transcript, VideoList
@@ -25,6 +35,27 @@
 _JOB = "/api/v2/transcripts/jobs/{job_id}"
 
 
+class ChunkOptions(TypedDict, total=False):
+    """Sizes for ``chunks=``: ``max_tokens`` 100 to 2000 (default 500) and
+    ``overlap_tokens`` 0 to 200, smaller than ``max_tokens`` (default 50)."""
+
+    max_tokens: int
+    overlap_tokens: int
+
+
+Chunks = Union[bool, ChunkOptions]
+
+
+def _formats(markdown: Optional[bool], chunks: Optional[Chunks]) -> dict[str, Any]:
+    """The LLM-ready output options, only the ones set. Both are free."""
+    out: dict[str, Any] = {}
+    if markdown is not None:
+        out["markdown"] = markdown
+    if chunks is not None and chunks is not False:
+        out["chunks"] = dict(chunks) if isinstance(chunks, dict) else True
+    return out
+
+
 # ── Requester protocols (avoid importing the client → no circular import) ─────
 class _SyncRequester(Protocol):
     def _request(
@@ -109,6 +140,8 @@ def video(
         *,
         mode: Optional[Literal["auto", "captions", "audio"]] = None,
         timestamps: Optional[bool] = None,
+        markdown: Optional[bool] = None,
+        chunks: Optional[Chunks] = None,
         callback_url: Optional[str] = None,
         idempotency_key: Optional[str] = None,
     ) -> Transcript:
@@ -117,6 +150,12 @@ def video(
         ``video`` is a YouTube, TikTok or Instagram URL, a direct media file
         URL, or a bare YouTube ID.
 
+        ``markdown=True`` adds :attr:`~transcriptfetch.Transcript.markdown`;
+        ``chunks=True`` (or ``{"max_tokens": 800, "overlap_tokens": 80}``)
+        adds :attr:`~transcriptfetch.Transcript.chunks`, pieces sized for an
+        embedding model with a link to the moment each one starts. Both are
+        free, and an audio-transcription job delivers them too.
+
         When the source has no captions the API transcribes its audio and
         answers with a job instead: the returned
         :class:`~transcriptfetch.Transcript` then has ``status ==
@@ -134,7 +173,8 @@ def video(
                     "callback_url": callback_url,
                 }.items()
                 if v is not None
-            },
+            }
+            | _formats(markdown, chunks),
             idempotent=True,
             idempotency_key=idempotency_key,
         )
@@ -204,6 +244,8 @@ def batch(
         video_ids: Iterable[str],
         *,
         mode: Optional[str] = None,
+        markdown: Optional[bool] = None,
+        chunks: Optional[Chunks] = None,
         idempotency_key: Optional[str] = None,
     ) -> BatchResponse:
         """Fetch up to 50 transcripts in one call (same inputs as :meth:`video`).
@@ -225,6 +267,7 @@ def batch(
         body: dict[str, Any] = {"videoIds": list(video_ids)}
         if mode is not None:
             body["mode"] = mode
+        body.update(_formats(markdown, chunks))
         env = self._c._request(
             "POST",
             _BATCH,
@@ -278,6 +321,8 @@ async def video(
         *,
         mode: Optional[Literal["auto", "captions", "audio"]] = None,
         timestamps: Optional[bool] = None,
+        markdown: Optional[bool] = None,
+        chunks: Optional[Chunks] = None,
         callback_url: Optional[str] = None,
         idempotency_key: Optional[str] = None,
     ) -> Transcript:
@@ -294,7 +339,8 @@ async def video(
                     "callback_url": callback_url,
                 }.items()
                 if v is not None
-            },
+            }
+            | _formats(markdown, chunks),
             idempotent=True,
             idempotency_key=idempotency_key,
         )
@@ -357,6 +403,8 @@ async def batch(
         video_ids: Iterable[str],
         *,
         mode: Optional[str] = None,
+        markdown: Optional[bool] = None,
+        chunks: Optional[Chunks] = None,
         idempotency_key: Optional[str] = None,
     ) -> BatchResponse:
         """Fetch up to 50 transcripts in one call. See :meth:`Transcripts.batch`
@@ -366,6 +414,7 @@ async def batch(
         body: dict[str, Any] = {"videoIds": list(video_ids)}
         if mode is not None:
             body["mode"] = mode
+        body.update(_formats(markdown, chunks))
         env = await self._c._request(
             "POST",
             _BATCH,

tests/test_client.py

@@ -194,3 +194,61 @@ def test_missing_api_key_raises(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("TRANSCRIPTFETCH_API_KEY", raising=False)
     with pytest.raises(ValueError):
         TranscriptFetch()
+
+
+CHUNKED_ENV = {
+    "ok": True,
+    "request_id": "req_chunks",
+    "data": {
+        "kind": "transcript",
+        "video_id": "abc",
+        "url": "https://www.youtube.com/watch?v=abc",
+        "platform": "youtube",
+        "title": "Example",
+        "text": "hello world",
+        "segments": [],
+        "markdown": "# Example\n\n[0:00](https://www.youtube.com/watch?v=abc&t=0s) hello world",
+        "chunks": [
+            {"index": 0, "text": "hello world", "start": 0.0, "end": 2.5,
+             "url": "https://www.youtube.com/watch?v=abc&t=0s", "tokens": 2},
+        ],
+    },
+}
+
+
+@respx.mock
+def test_video_sends_and_parses_llm_formats() -> None:
+    route = respx.post(f"{BASE}/api/v2/transcripts/video").mock(
+        return_value=httpx.Response(200, json=CHUNKED_ENV)
+    )
+    with _client() as tf:
+        t = tf.transcripts.video("abc", markdown=True, chunks={"max_tokens": 800})
+
+    body = json.loads(route.calls.last.request.content)
+    assert body == {"video": "abc", "markdown": True, "chunks": {"max_tokens": 800}}
+    assert t.markdown and t.markdown.startswith("# Example")
+    assert len(t.chunks) == 1
+    c = t.chunks[0]
+    assert (c.index, c.start, c.end, c.tokens) == (0, 0.0, 2.5, 2)
+    assert c.url == "https://www.youtube.com/watch?v=abc&t=0s"
+
+
+@respx.mock
+def test_video_omits_unset_formats_and_false_chunks() -> None:
+    route = respx.post(f"{BASE}/api/v2/transcripts/video").mock(
+        return_value=httpx.Response(200, json=VIDEO_ENV)
+    )
+    with _client() as tf:
+        t = tf.transcripts.video("abc", chunks=False)
+    assert json.loads(route.calls.last.request.content) == {"video": "abc"}
+    assert t.chunks == [] and t.markdown is None
+
+
+@respx.mock
+def test_batch_sends_chunks_true() -> None:
+    route = respx.post(f"{BASE}/api/v2/transcripts/batch").mock(
+        return_value=httpx.Response(200, json=BATCH_ENV)
+    )
+    with _client() as tf:
+        tf.transcripts.batch(["a", "b"], chunks=True)
+    assert json.loads(route.calls.last.request.content) == {"videoIds": ["a", "b"], "chunks": True}