Sources and options | transcript1 docs

Transcribe a YouTube URL or an uploaded file. Use source, diarize and language to select the transcript source, speaker labels and language. All three are optional fields in the request body of POST /v1/transcriptions.

Supported YouTube URL formats

Set "platform": "youtube" and pass a video URL in url. These forms are accepted, with or without www.:

Form	Example
Watch page	`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
Short link	`https://youtu.be/dQw4w9WgXcQ`
Shorts	`https://www.youtube.com/shorts/dQw4w9WgXcQ`
Embed	`https://www.youtube.com/embed/dQw4w9WgXcQ`
Live	`https://www.youtube.com/live/dQw4w9WgXcQ`
Mobile and music hosts	`https://m.youtube.com/watch?v=dQw4w9WgXcQ`, `https://music.youtube.com/watch?v=dQw4w9WgXcQ`

Extra query parameters such as t, list and si are ignored, and every form of one video is treated as the same video. The URL must be a full URL: a bare 11-character video id is rejected. Channel pages, playlist-only links and non-YouTube URLs return 422 invalid_url. Any other platform value returns 422 unsupported_platform with the list of supported_platforms.

Only public and unlisted videos can be fetched. Private, age-restricted and live videos fail with media_private, age_restricted and live_stream. For a file you own, use an upload.

source

source decides where the transcript comes from.

Value	Behavior
`auto` (default)	Use YouTube captions when a usable caption track exists, otherwise transcribe the audio with AI speech-to-text.
`captions`	Use YouTube captions only. If the video has no usable track the transcription fails with `no_captions` and nothing is charged.
`stt`	Always transcribe the audio with AI speech-to-text.

Uploaded files are always transcribed with speech-to-text. For an upload, source may be auto or stt; captions returns 422 invalid_request.

A usable caption track must match the requested language (or the video's original language when language is auto). It must be creator-uploaded or generated by YouTube in that language. Auto-translated tracks are never used. Creator captions take priority over auto-generated captions.

diarize

diarize adds speaker labels. It defaults to false.

Speaker labels need speech-to-text. With source set to auto, diarize: true skips captions and goes straight to speech-to-text.
source: "captions" together with diarize: true is rejected with 422 invalid_request.
Labels look like Speaker 1 and Speaker 2. They appear in transcript.speakers, in each segment's speaker field and as a Speaker 1: prefix in the text and srt formats (a <v Speaker 1> voice tag in vtt).

{ "platform": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ", "source": "stt", "diarize": true }

language

language is auto (the default) or a two-letter ISO 639-1 code such as en, de or es.

For captions it selects the caption track language. With auto, transcript1 picks the video's original language.
For speech-to-text it is passed to the speech-to-text provider as a language hint. With auto, the language is identified for you, and each segment carries its own language.

The transcription object reports the dominant language in language.

Transcript source and output

transcript_source identifies how the transcript was produced. For YouTube captions, caption_kind identifies the track type.

	`youtube_captions`, `caption_kind` `manual`	`youtube_captions`, `caption_kind` `auto_generated`	`speech_to_text`
Segments	One per caption cue	One per caption cue	Grouped on speaker change, language change, sentence-final punctuation or a 15-second cap
Word timings with `include=words`	None (`words` is `null`)	Word start times; each word ends where the next begins	Word start and end times with `confidence`
Speaker labels	No	No	Yes, when `diarize` is `true`
Language	The track language	The track language	Per segment

Caption text is kept as YouTube published it, including tags such as [Music]. Speech-to-text accepts media up to 5 hours; longer media fails with media_too_long.

Price

Captions and speech-to-text cost the same: one credit per media minute, rounded up. The choice only changes where the transcript comes from, not what you pay. See Billing and limits.