API Reference

Authentication

Every request must include your API key in the Authorization header using the Bearer scheme:

Create an API key from the dashboard. Keys are shown once; store them securely.

POST /v1/transcript

Enqueues a transcript request for a YouTube video. The API is asynchronous: this call always returns a queued request (HTTP 202), and you poll GET /v1/transcript/:id until its status is completed (or failed). Requests already in our cache are resolved by the worker almost immediately, so polling typically completes on the first or second try.

Request body (JSON)

Example

Example response (a completed request)

While the worker runs, status is queued or processing and result is null. Once completed, result holds the transcript — including original_language and translated_to (non-null only when a translation was applied). When a translation is applied, JSON responses also include original_transcript and original_segments (the pre-translation text), and result.summary is present when include_summary was set.

Response headers

• X-RateLimit-Limit / -Remaining / -Reset: current rate-limit budget.

AI summary

Add "include_summary": true to any POST /v1/transcript request to get an AI-generated summary alongside the transcript. The summary is written in the transcript's display language (so it respects translate_to) and lands on result.summary:

• tldr — a 2–3 sentence overview of the whole video.
• key_points — 5–8 one-sentence bullet points.
• model — the model that produced the summary.
• generated_at — ISO timestamp.

Summaries are free — only the transcript's normal credit applies (1 native / per-minute Whisper). They are cached, so re-summarizing the same video and language is instant and costs nothing. If summary generation fails, the transcript is still returned with summary: null — a summary failure never fails the transcript.

POST /v1/summarize

A convenience wrapper that always sets include_summary and format: json. Same async contract as /v1/transcript: it returns a queued request you poll at GET /v1/transcript/:id.

Browse endpoints

The same bearer key unlocks lightweight YouTube discovery endpoints and the bulk-transcript queue. Discovery (list-only) endpoints charge a flat one credit per call — zero if the call returns no results. /v1/channel/latest returns the single most-recent upload and is free. The bulk endpoint charges one credit per transcript delivered (cache hits charge the same as a fresh fetch). Single-video /v1/video/metadata is free.

GET /v1/search accepts a type of video (the default), channel, playlist, or all. limit defaults to 10. The cap varies by endpoint: /v1/search allows up to 50; the channel and playlist listing endpoints allow up to 200; the bulk endpoint caps at 100. Values above the cap are rejected with a VALIDATION_ERROR.

On /v1/search and /v1/channel/search, q is the canonical search-query parameter, and query is accepted as an alias. Send one or the other — if both are present, q takes precedence.

Output formats

Pass format in the request body to control how the transcript is rendered. Every response is the JSON envelope shown above (Content-Type: application/json) — format changes the string inside result.transcript, not the response type. Write that string to a file yourself if you need a standalone subtitle file.

• json — result.transcript is plain text; a structured segments array is included alongside it.
• text — plain text only, no timestamps.
• text-timestamps — plain text prefixed with [mm:ss] per line.
• srt — result.transcript holds SubRip-formatted subtitles.
• vtt — result.transcript holds WebVTT-formatted subtitles.

Credits

One credit per native YouTube transcript regardless of length. Whisper fallback costs one credit per minute of audio (rounded up). Cached requests are free.

Your remaining balance is in credits_remaining on every JSON response.

Error codes

A code with no HTTP status (—) is not an HTTP error: the request returns 200, then its status becomes failed and error_code holds the code.

All errors share the envelope { error, code, message, request_id, ...details }. Quote the request_id when reporting a failure so it can be traced in the logs.