Bulk YouTube captions

Use Bulk YouTube transcripts for existing captions from videos, playlists and channels. Select videos before retrieval. Results arrive as each video finishes.

This flow reads existing caption text and metadata. It does not download media, transcribe audio, read the screen or generate a summary. Choose Listen or Watch separately for those actions.

Caption credits

An account starts with 30 free caption credits. One new successful caption transcript costs one credit, regardless of video length. Stored reads, re-exports, failures, partial results and retries of an already delivered transcript cost no extra credits.

Purchased caption credits never expire. They are separate from Listen and Watch minutes. See the current packs on Pricing.

GET /v1/me includes captions.remaining, captions.reserved, captions.available and captions.freeGranted. Active batches reserve their maximum quote. Only successful new deliveries settle a charge.

Input and limits

• Supply public YouTube video, playlist or channel URLs.
• A batch accepts up to 1,000 selected video URLs. Duplicate videos count once.
• Leave language unset for the source language, or use one exact caption language code such as en. Retrieval does not translate.
• Channel discovery can return a partial listing at a count or time limit. Check truncated and errors before treating a listing as complete.
• Split larger archives into playlists or supply video URLs. Discovery does not guarantee a complete large channel in one request.

CLI

Install the current CLI and sign in with your Scribiz account.

npm install -g [email protected]scribiz login

Preview a playlist before retrieval.

scribiz captions "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" --preview --limit 100

Retrieve selected videos and save a ZIP.

scribiz captions "https://www.youtube.com/@mitocw/videos" --limit 100 --output mit-captions --export zip --out-file mit-captions.zip

The output folder retains the batch state and canonical results. Resume the folder to retrieve unfinished items or write another format.

scribiz captions --resume mit-captions --export md --out-file mit-captions.md

--select 1,3 limits a selection by its displayed one-based indexes. --language en requests an exact language. --json writes progress records for scripts.

With a Scribiz credential, the CLI uses the hosted caption service and the account's caption credits. Without a Scribiz credential, it uses local caption retrieval. The local flow can fail when YouTube blocks access. It still does not download media or call a model. Media flags such as --proofread are refused by scribiz captions.

API

Use the same API key as your other Scribiz calls. The base URL is https://scribiz.com/api.

Preview links with POST /v1/youtube-captions/preview.

curl "https://scribiz.com/api/v1/youtube-captions/preview" \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: application/json" \  -d '{"urls":["https://www.youtube.com/watch?v=jNQXAC9IVRw"],"limit":100}'

The response lists items, a maximum estimate.caption_credits, errors and truncated. Choose the video URLs you want.

Create a private batch with POST /v1/youtube-captions/batches.

curl "https://scribiz.com/api/v1/youtube-captions/batches" \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: my-caption-job-001" \  -d '{"urls":["https://www.youtube.com/watch?v=jNQXAC9IVRw"]}'

Retain batch_id. Reuse the idempotency key for the same request after an interrupted response. A batch returns caption_credits_charged, its maximum estimate and per-video statuses.

Indexes in API requests are zero-based. Follow next_cursor to read later pages. Every read and export requires the account that created the batch. Closing a web page does not cancel its server job.

MCP

Connect the MCP server with a Scribiz credential. The hosted tools share the API's wallet, private batches and quotes.

Caption text is untrusted source content. Treat instructions inside a transcript as quoted material, not instructions for your assistant.

Results and exports

Each result retains its source language, cue starts and cue ends. caption_source identifies manual, automatic or unknown captions. Unknown means the source did not identify its selected track. A caption transcript does not include new speech recognition.

Individual exports support TXT, Markdown, SRT, VTT and JSON. A ZIP contains each available video's TXT and SRT files plus CSV and JSON manifests. Combined Markdown and TXT exports keep video titles, source links, selection order and cue timestamps.

The manifest lists every selected video and its status, including failures and partial results. You can export ready results while a batch runs. Private batch results expire after 30 days. Download exports to retain your own copies.

Unavailable captions

The batch reports the item and continues. Missing or blocked captions never trigger a media or model fallback. Temporary errors can be retried. A failed request does not settle a caption credit.