Media Chapter vs Media Transcript API: The Real Differences

AIOZ Stream's Media Chapter API and Media Transcript API look almost identical from the outside: same URL shape, same per-language storage, same file format. That's not a coincidence or a documentation shortcut, both are built on WebVTT, a format explicitly designed to carry more than one kind of timed text. The real differences are in what each endpoint actually lets you do, and what's conspicuously not there.

TL;DR:

• Both APIs use the same URL pattern, /api/media/:media_id/chapters/:lan and /api/media/:media_id/transcripts/:lan, and both only accept .vtt files.
• Chapters support create, list, and delete only. Transcripts add a fourth operation, an update endpoint specifically for setting which language track is the default.
• A transcript object carries more fields than a chapter object, status, description, and is_default alongside url and language; a chapter object is just url and language.
• Neither API generates anything automatically. Both require a user-provided VTT file, no speech-to-text, unlike YouTube's auto-captioning, which generates captions from audio without a manual upload.
• AIOZ's docs confirm the player styles captions (a documented "Caption Color" setting), but don't confirm whether chapters or transcripts render automatically in the player UI at all, worth testing directly rather than assuming.

Same file format, different endpoints

Chapters get exactly three operations: create with a POST to /api/media/:media_id/chapters/:lan, list with a GET to /api/media/:media_id/chapters, and delete with a DELETE to the same per-language path. There's no update endpoint, changing a chapter file means deleting it and uploading a replacement. Transcripts get a fourth operation on top of the same three: a PATCH to /api/media/:media_id/transcripts/:lan, specifically for updating which language transcript the player should treat as default, not general-purpose editing. Both use the same :lan parameter format, BCP 47 language tags like en or the more specific fr-CA, and both are explicit that a given media object can only hold one file per language: at most one chapter file and one transcript file per language code, not multiple versions stacked on top of each other. A chapters file itself is a small, plain-text document, structurally identical to a captions file except for what the cue text says:

WEBVTT

00:00:00.000 --> 00:02:15.000
Introduction

00:02:15.000 --> 00:08:40.000
Setting Up the Client

00:08:40.000 --> 00:15:30.000
Handling Errors

Uploading that file via the Chapter API's POST endpoint, with the target language as the :lan path parameter, is the entire creation step, there's no separate metadata payload describing chapter titles or timestamps outside the file itself, everything the API needs is already inside the VTT.

Why they're both VTT

This isn't AIOZ reusing a format out of convenience, WebVTT was built to carry exactly this range of uses. Per the format's own specification, referenced directly in browser documentation, "the different kinds of text data that can be specified are captions, descriptions, chapters, subtitles or metadata," all using the identical cue structure, a start and end timestamp followed by text. A chapters VTT file and a captions VTT file are structurally the same document, timestamp, arrow, text, repeated, the only difference is what the text represents and how a player is told to treat it, via the kind attribute on the track referencing the file. That's the real reason AIOZ Stream's Chapter and Transcript APIs look so similar: they're not two unrelated features that happen to share a file extension, they're the same underlying format applied to two different jobs a video needs done.

What each object actually returns

The field difference between the two response objects reflects a real difference in how each gets used. A chapter object is minimal, just a url pointing to the hosted VTT file and a language code, chapters are navigation markers, there isn't much more state to track. A transcript object carries three more fields: status, tracking whatever processing or validation the uploaded file goes through server-side, description, a human-readable label, and is_default, a boolean that matters specifically when a video has transcripts in more than one language and the player needs to know which one loads without the viewer picking manually. That is_default field, and the dedicated PATCH endpoint that sets it, is the one real functional difference beyond the missing update operation on chapters: transcripts are built for a multi-language default-selection workflow that chapters simply don't need.

No auto-generated transcripts

Both APIs require a file a human, or some other process outside AIOZ Stream, already produced. AIOZ's documentation describes uploading "a user-provided transcript," and nothing in either API reference mentions speech-to-text, automatic transcription, or any generation step at all, the platform stores and serves whatever VTT file arrives, it doesn't create one. That's a meaningful contrast with how the biggest video platforms handle this: YouTube's own support documentation describes automatic captions generated directly from a video's audio via speech recognition, published without the uploader providing a transcript file at all. Whether that gap matters depends entirely on the use case, a team already running its own transcription pipeline loses nothing, a team hoping to flip a switch and get instant multi-language transcripts the way YouTube's creators can needs to build or license that step separately before AIOZ Stream's Transcript API has anything to store. The practical shape of that pairing is straightforward even if it isn't automatic: run the source audio through a speech-to-text service capable of exporting WebVTT directly, several mainstream ones do, upload the resulting file through the Transcript API's create endpoint, then repeat per additional language if the video needs more than one. That's an extra step compared to a platform with built-in generation, but it also means whatever transcription quality and vocabulary handling a project actually needs isn't constrained to whatever AIOZ Stream's own speech-recognition model happens to be good or bad at, since there isn't one to inherit limitations from.

What isn't confirmed: does the player actually show these?

AIOZ's player documentation confirms captions render in the player, there's a documented "Caption Color" setting specifically for styling them, which only makes sense if captions display natively without extra integration work. Neither the Chapter nor the Transcript API documentation, nor the player customization docs, confirm the equivalent for chapters or transcripts specifically, whether uploading a chapters VTT file automatically produces chapter markers on the player's scrubber, or whether a transcript automatically becomes a viewable text panel, isn't stated either way. Given how directly this affects whether either API is worth using without writing custom player UI on top, it's worth testing against a real embedded player before assuming either behavior. There's a reasonable middle-ground expectation worth naming while that gets tested: since captions render natively and captions/transcripts/chapters all share the same underlying <track>-and-kind mechanism per the WebVTT spec, it wouldn't be surprising if the player at least exposes a transcript track the same general way it exposes captions, even without a dedicated styling setting calling it out by name. Chapter markers specifically, a visual overlay on the scrubber rather than a text track a browser renders by default, are a better candidate for something that genuinely needs custom UI regardless of what the player does with the underlying file, since browsers don't natively draw chapter markers onto a video's timeline the way they render caption text, that overlay is presentation work no browser or player ships as a default behavior, chapters or otherwise.

Frequently Asked Questions

What's the actual functional difference between the Chapter and Transcript APIs?
Transcripts support an update operation for setting a default language and carry extra fields (status, description, is_default) that chapters don't have. Chapters are create/list/delete only, with just a URL and language per object.

Why do both APIs use the same VTT file format?
WebVTT is explicitly designed to carry captions, subtitles, chapters, descriptions, and metadata using the same cue structure, differentiated by intent and the track's kind attribute rather than by file format.

Can AIOZ Stream auto-generate a transcript from a video's audio?
No. Both the Chapter and Transcript APIs require an already-produced VTT file; there's no speech-to-text or automatic transcription step documented anywhere in either API reference.

Can a video have multiple chapter files in the same language?
No. AIOZ's documentation is explicit that a media object holds at most one chapter file and one transcript file per language code.

Does uploading a chapters file make chapter markers show up in the player automatically?
Not confirmed either way in AIOZ's documentation. Captions are confirmed to render natively (there's a dedicated styling setting for them), but chapters and transcripts aren't addressed the same way, worth testing directly.

What does the is_default field on a transcript actually control?
Which language transcript the player loads by default when a video has transcripts in more than one language, set via the Transcript API's PATCH endpoint.

Related Reading

• Video SEO: How to Get Your Videos Indexed and Ranked by Google: how chapter data can also power Google's key-moments search feature alongside schema
• Captions vs Subtitles vs SDH: the missing sdh kind value that confirms SDH is content, not a distinct WebVTT format
• How to Embed the AIOZ Stream Player on Your Website: the base embed this article's caption/chapter rendering question applies to
• Multi-Language Captions and Transcripts: A Developer Guide: the practical workflow for managing is_default across several languages on one video
• How to White-Label the AIOZ Stream Video Player via API: the player-side settings, including caption styling, this article's player-rendering question touches
• Podcast and Audio Hosting with the AIOZ Stream API: another case of AIOZ providing the storage/delivery layer without the surrounding feature a name implies
• AIOZ Stream Developer Guide: the full API surface these two endpoints are part of

References

• AIOZ Stream Media Chapter API documentation: the endpoints and fields cited above
• AIOZ Stream Media Transcript API documentation: the endpoints, fields, and manual-upload requirement cited above
• MDN: WebVTT API: the shared cue format and "kind" attribute distinction cited above
• YouTube Help: Use Automatic Captioning: the auto-generated-captions comparison cited above