Index YouTube | Captain Docs

Index YouTube videos into a collection.

Three modes control how each video is processed and billed:

mode	Behavior	Billing
`transcript` (default)	Fetches the caption track (auto-generated or manual), formats it with inline timestamps, and indexes it as text. No frames or audio are processed.	Basic text pages (roughly 3 credits for an hour of captions)
`audio`	Pulls the audio track through the multimodal audio pipeline (transcription plus audio understanding).	5 credits per audio minute
`video`	Pulls the video through the multimodal video pipeline (frame descriptions plus transcription).	20 credits per video minute

The default is transcript and will stay transcript: media modes cost orders of magnitude more for the same video and are strictly opt-in.

A video with no captions fails in transcript mode by default. Set on_missing_transcript to audio or video to fall back to a media mode for that video instead. Because the fallback changes what you are billed, it is recorded per video: GET /v2/jobs/{job_id} returns a youtube array with mode_used, fell_back_from, transcript_available, and languages for every video in the job.

Accepts either a single url string or a urls array (max 20; duplicate videos are removed). Supported URL shapes: youtube.com/watch?v=, youtu.be/, youtube.com/shorts/, youtube.com/embed/, youtube.com/v/, and youtube.com/live/. Redirects and shortener URLs are not followed. Live streams are not indexable, and media longer than 4 hours is rejected.

Headers:

Authorization: Bearer {api_key} - Captain API key for authentication
X-Organization-ID: Organization UUID
Idempotency-Key: UUID for request deduplication (optional)

Returns: { job_id, status: “pending” }

Index YouTube videos into a collection. Three modes control how each video is processed and billed: | mode | Behavior | Billing | | --- | --- | --- | | `transcript` (default) | Fetches the caption track (auto-generated or manual), formats it with inline timestamps, and indexes it as text. No frames or audio are processed. | Basic text pages (roughly 3 credits for an hour of captions) | | `audio` | Pulls the audio track through the multimodal audio pipeline (transcription plus audio understanding). | 5 credits per audio minute | | `video` | Pulls the video through the multimodal video pipeline (frame descriptions plus transcription). | 20 credits per video minute | The default is `transcript` and will stay `transcript`: media modes cost orders of magnitude more for the same video and are strictly opt-in. A video with no captions fails in transcript mode by default. Set `on_missing_transcript` to `audio` or `video` to fall back to a media mode for that video instead. Because the fallback changes what you are billed, it is recorded per video: `GET /v2/jobs/{job_id}` returns a `youtube` array with `mode_used`, `fell_back_from`, `transcript_available`, and `languages` for every video in the job. Accepts either a single `url` string or a `urls` array (max 20; duplicate videos are removed). Supported URL shapes: `youtube.com/watch?v=`, `youtu.be/`, `youtube.com/shorts/`, `youtube.com/embed/`, `youtube.com/v/`, and `youtube.com/live/`. Redirects and shortener URLs are not followed. Live streams are not indexable, and media longer than 4 hours is rejected. Headers: - Authorization: Bearer {api_key} - Captain API key for authentication - X-Organization-ID: Organization UUID - Idempotency-Key: UUID for request deduplication (optional) Returns: { job_id, status: "pending" }

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

custom_metadatamap from strings to strings or integers or doubles or booleans or lists of strings or nullOptional

Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].

languageslist of strings or nullOptional

Preferred transcript languages in priority order (ISO 639-1 codes). Defaults to English. Only specify if you need a non-English transcript (e.g., [‘fr’, ‘de’]). Falls back to auto-generated captions if manual transcript unavailable.

urlstring or nullOptional

A single YouTube video URL (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). Provide either ‘url’ or ‘urls’, not both.

urlslist of strings or nullOptional

A list of YouTube video URLs to index. Provide either 'url' or 'urls', not both.

mask_piibooleanOptionalDefaults to false

When true, detected PII (emails, phone numbers, SSNs, credit cards, names, and locations) is masked in the parsed content before it is embedded and stored — replaced with entity tags like <PERSON> and <EMAIL_ADDRESS>. For images (including images embedded in PDFs), PII text visible in the image is also pixel-redacted. Opt-in; defaults to false, which leaves content unchanged.

pii_engineenumOptionalDefaults to kev

Masking engine for this job. kev (default): the Kev classifier model on Captain’s infrastructure; supports pii_fields and pii_instructions; no fallback, so a file kev cannot mask fails to index and the rest of the job continues. jev: TypeSafe’s hosted Jev model, slightly more accurate, best-effort availability; supports custom fields and instructions and may list fallbacks in pii_fallback. presidio: the legacy pattern engine, built-in categories only (rejects pii_fields or pii_instructions with 422), never a fallback. Requires mask_pii: true. The earlier names captain-jev and captain-presidio keep working as before; new requests should use kev, jev or presidio.

Allowed values:

pii_fallbackobject or booleanOptional

Ordered fallback engines for jev, as {"engines": [...], "retry_budget_seconds": n}. Omitted or an empty engines list means no fallback. Only valid with pii_engine: "jev"; with kev or presidio a non-empty list answers 422. On the multipart file upload endpoint, send it as a JSON string form field. With the earlier engine name captain-jev it is true (default, fall back to captain-presidio) or false.

pii_fieldslist of objects or nullOptional

Additional PII categories to mask for this job, on top of the built-in set. Requires mask_pii to be true. Up to 20 fields. Each masked value is replaced with the field’s tag in angle brackets and appears in the masking report under the field’s name.

pii_instructionsstring or nullOptional<=1000 characters

Plain-language guidance that steers what counts as personal data for this job, for the built-in categories and any pii_fields. For example: ‘Names of hospital staff may stay; patient names, record numbers and bed assignments must be masked.’ Requires mask_pii to be true. Up to 1,000 characters.

modeenumOptionalDefaults to transcript

How to index each video. ‘transcript’ (default): fetch the caption track and index it as text, billed as basic text pages. ‘audio’: pull the audio track through the multimodal audio pipeline, billed at 5 credits per audio minute. ‘video’: pull the video (frame descriptions plus transcription) through the multimodal video pipeline, billed at 20 credits per video minute. Media modes cost orders of magnitude more than transcript mode for the same video; the default is transcript and will not change.

Allowed values:

on_missing_transcriptenumOptionalDefaults to fail

Only applies when mode=‘transcript’. What to do for a video whose captions are disabled or absent. ‘fail’ (default): that video fails. ‘audio’ / ‘video’: fall back to indexing that video through the corresponding media pipeline instead, billed at media rates. Any fallback is recorded per video in the job’s youtube record (mode_used, fell_back_from) so the billing change is visible. Setting this together with a media mode is rejected with a validation error.

Allowed values:

Response

Successful Response

job_idstring

statusstringOptionalDefaults to pending

custom_metadatamap from strings to any or nullOptional

The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.

Index YouTube videos into a collection.

Three modes control how each video is processed and billed:

mode	Behavior	Billing
`transcript` (default)	Fetches the caption track (auto-generated or manual), formats it with inline timestamps, and indexes it as text. No frames or audio are processed.	Basic text pages (roughly 3 credits for an hour of captions)
`audio`	Pulls the audio track through the multimodal audio pipeline (transcription plus audio understanding).	5 credits per audio minute
`video`	Pulls the video through the multimodal video pipeline (frame descriptions plus transcription).	20 credits per video minute

The default is transcript and will stay transcript: media modes cost orders of magnitude more for the same video and are strictly opt-in.

Headers:

Authorization: Bearer {api_key} - Captain API key for authentication
X-Organization-ID: Organization UUID
Idempotency-Key: UUID for request deduplication (optional)

Returns: { job_id, status: “pending” }