{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"TranscriptLab API","version":"1.0.0","summary":"YouTube captions, speech transcription, and transcript jobs.","description":"TranscriptLab provides a REST API for YouTube captions, explicit speech-to-text on public media URLs, batch and channel jobs, and cached transcript queries.\n\nAuthenticate with `Authorization: Bearer <API_KEY>` or `X-API-Key: <API_KEY>`. API keys are created in the TranscriptLab dashboard. Keep them on a trusted server.\n\nTranscript reads return JSON, text, SRT, or VTT. A YouTube request returns 200 with the transcript, or 202 with a `Location` to request again until it answers 200 — there is no job to poll for a single video. Batch and channel submissions are asynchronous. A 202 does not mean a transcript was delivered; channel listing rows are metered as the asynchronous listing proceeds.\n\n`lang` selects a preferred YouTube caption language; with `engine=stt`, the spoken language is detected from audio. `type` selects any, manual, or generated caption track. For `engine=captions`, `language.is_generated` identifies auto-generated captions. Speech transcripts include `metadata.engine=stt`. When `translate` is requested, inspect `translation.target` and `translation.translated` in the result. Translation is not supported with STT, and the API never silently falls back from captions to speech transcription.\n\nOperational bounds: synchronous requests default to 20 seconds and accept up to 60 seconds; batch size and per-channel listing limits come from the plan; a channel transcription job is capped at 250 videos and each job may include up to 10 channels. A maximum of 25 jobs may be open per account. Speech-to-text input is capped at 12 hours.\n\nIdempotency: `POST /v1/transcripts/batch` and `POST /v1/channels/transcribe` accept an `Idempotency-Key` header (1–255 printable ASCII characters). A retry with the same key and body replays the original 202 and sets `Idempotent-Replayed: true`; the same key with a different body is a 409 `conflict`. Transcript requests need no key: a transcript variant is charged once per account however often it is requested, and media submissions coalesce on the media document.\n\nPagination: list endpoints return `has_more` and an opaque `next_cursor`; pass it back as `cursor`.\n\nErrors: every error has `error.code`, `error.message`, and `error.request_id`. Branch on `code`, not on the HTTP status — for example `rate_limited` and `quota_exceeded` are both 429, and `upstream_rate_limited` is 503. Each operation lists the codes it can return in `x-error-codes`.\n\nCredits: one per transcript variant — the first delivered transcript of a (video, language, caption-type) combination is charged and all later deliveries of it are free — plus one per started audio minute, and one per 100 channel video rows listed (transcribe mode applies the same first-delivery rule per variant). Caption discovery and cached queries cost no credits; discovery is subject to a plan-based monthly quota. Rate limiting is plan-based; 429 responses include `Retry-After`.","contact":{"name":"TranscriptLab Support","url":"https://transcriptlab.dev"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.transcriptlab.dev","description":"TranscriptLab production API"}],"tags":[{"name":"Transcripts","description":"Request, read, search and discover YouTube transcripts."},{"name":"Jobs","description":"Poll, list and cancel asynchronous work."},{"name":"Channels","description":"List or transcribe whole channels."},{"name":"Media","description":"Speech-to-text for audio and video files at public URLs."}],"externalDocs":{"description":"Human-readable API guide","url":"https://transcriptlab.dev/docs"},"components":{"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A retry with the same key and request body replays the original response (`Idempotent-Replayed: true`) instead of creating a second job; the same key with a different body is a 409 `conflict`. Keys are scoped to the account.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[!-~]+$"}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque `next_cursor` from the previous page.","schema":{"type":"string","maxLength":512}}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"TranscriptLab API key","description":"Send the API key as `Authorization: Bearer ytgw_…`. `X-API-Key: ytgw_…` is also accepted."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to HTTP Bearer authentication."}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","insufficient_credits","forbidden","not_found","video_not_found","job_not_found","method_not_allowed","conflict","payload_too_large","unsupported_media_type","transcript_unavailable","rate_limited","quota_exceeded","upstream_error","upstream_schema_error","upstream_rejected","upstream_unavailable","upstream_rate_limited","upstream_timeout","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}},"TranscriptRequest":{"type":"object","additionalProperties":false,"description":"Provide exactly one of `url` or `video_id`. Rules the server enforces: `translate` is not supported with `engine=stt`; `diarize` and `speakers` require `engine=stt`; `also` adds renderings to a `json` response; `deadline_ms` bounds the wait before a 202 is returned. A violated rule is a 400 `invalid_request`.","oneOf":[{"required":["url"]},{"required":["video_id"]}],"properties":{"url":{"type":"string","maxLength":2048,"description":"YouTube video URL."},"video_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","description":"11-character YouTube video ID."},"lang":{"type":"string","default":"en","description":"Preferred YouTube caption language (ISO 639-1). Speech-to-text detects the source language from audio."},"translate":{"type":"string","description":"Translate captions to an ISO 639-1 language."},"type":{"type":"string","enum":["any","manual","generated"],"default":"any","description":"Selects a YouTube caption track; not used to select speech-to-text output."},"format":{"type":"string","enum":["json","text","srt","vtt"],"default":"json"},"metadata":{"type":"boolean","default":true},"also":{"type":"array","uniqueItems":true,"maxItems":3,"items":{"type":"string","enum":["srt","vtt","text"]},"description":"Additional renderings to embed when format is json."},"deadline_ms":{"type":"integer","minimum":1000,"maximum":60000,"default":20000},"engine":{"type":"string","enum":["captions","stt"],"default":"captions","description":"STT is explicit; the API never switches to it automatically."},"cleanup":{"type":"boolean","default":false},"diarize":{"type":"boolean","default":false,"description":"Requires engine=stt; implies tier=premium."},"tier":{"type":"string","enum":["normal","premium","auto"],"default":"auto","description":"Speech model tier. engine=stt only."},"speakers":{"type":"string","maxLength":2048,"example":"Speaker 1=Host"}},"anyOf":[{"required":["url"]},{"required":["video_id"]}],"not":{"required":["url","video_id"]}},"Transcript":{"type":"object","required":["video_id","url","language","translation","duration_seconds","snippet_count","transcript","source"],"properties":{"video_id":{"type":"string"},"url":{"type":"string","format":"uri"},"language":{"type":"object","properties":{"code":{"type":"string","description":"Caption language or speech-detected language."},"name":{"type":"string"},"is_generated":{"type":"boolean","description":"For engine=captions, true marks an auto-generated YouTube caption track; false marks a manual track. Use metadata.engine to identify speech-to-text transcripts."}}},"translation":{"oneOf":[{"type":"null"},{"type":"object","properties":{"target":{"type":"string"},"translated":{"type":"boolean","description":"Whether the returned transcript is translated."}}}],"description":"Null when translation was not requested; otherwise reports the target language and translation status."},"duration_seconds":{"type":["number","null"]},"snippet_count":{"type":"integer"},"transcript":{"type":"object","properties":{"text":{"type":"string"},"timestamped":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSegment"}}}},"formats":{"type":"object","additionalProperties":{"type":"string"},"description":"Present when `also` requested additional renderings."},"metadata":{"type":["object","null"],"additionalProperties":true},"source":{"type":"object","properties":{"cache":{"type":"string","enum":["L1","R2","UPSTREAM","COALESCED"]},"fetched_at":{"type":"string","format":"date-time"}}}}},"Discover":{"type":"object","required":["video_id","url","available_transcripts","result_types","source"],"properties":{"video_id":{"type":"string"},"url":{"type":"string","format":"uri"},"available_transcripts":{"type":"array","items":{"type":"object","properties":{"language_code":{"type":"string"},"language":{"type":"string"},"is_generated":{"type":"boolean"},"is_translatable":{"type":"boolean"},"translation_languages":{"type":["array","null"],"items":{"type":"string"}}}}},"result_types":{"type":"array","items":{"type":"string"}},"source":{"type":"object","properties":{"cache":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"}}}}},"StoredTranscript":{"type":"object","required":["v","video_id","url","language","translation","snippets","text","fetched_at"],"properties":{"v":{"const":1},"video_id":{"type":"string"},"url":{"type":"string"},"language":{"type":"object","additionalProperties":true},"translation":{"type":["object","null"],"additionalProperties":true},"is_translatable":{"type":"boolean"},"translation_languages":{"type":["array","null"],"items":{"type":"string"}},"duration_seconds":{"type":["number","null"]},"snippet_count":{"type":"integer"},"snippets":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSegment"}},"text":{"type":"string"},"metadata":{"type":["object","null"],"additionalProperties":true},"fetched_at":{"type":"string","format":"date-time"},"upstream":{"type":"object","additionalProperties":true}}},"TranscriptSegment":{"type":"object","required":["text","start","duration"],"properties":{"text":{"type":"string"},"start":{"type":"number","description":"Start time in seconds."},"duration":{"type":"number","description":"Segment duration in seconds."},"speaker":{"type":"string"}}},"Processing":{"type":"object","required":["video_id","state"],"properties":{"video_id":{"type":"string"},"state":{"const":"processing","description":"The result is not ready. Request the `Location` URL again after `Retry-After` seconds; there is no job to poll."}}},"Job":{"type":"object","required":["id","type","status","state","terminal","progress","total_items","completed_items","failed_items","credits_charged","error","created_at","poll_url","items_url"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["single","batch","channel","discover","stt","stt_upload","stt_url"],"description":"Job list returns batch, channel and file (stt_upload/stt_url) jobs; single, discover and stt jobs stay readable by id only."},"status":{"type":"string","enum":["queued","launching","upstream_running","collecting","succeeded","partial","failed","canceled"]},"state":{"type":"string","enum":["waiting","preparing","processing","done","failed"],"description":"Stop polling when state is done or failed."},"terminal":{"type":"boolean"},"progress":{"type":"number","minimum":0,"maximum":1},"total_items":{"type":"integer"},"completed_items":{"type":"integer"},"failed_items":{"type":"integer"},"credits_charged":{"type":"integer"},"error_code":{"type":["string","null"]},"error":{"type":["string","null"]},"result_url":{"type":["string","null"]},"webhook_configured":{"type":"boolean"},"webhook_secret":{"type":"string","description":"Returned only in the submission response when webhook_url was configured. Save it to verify callbacks."},"created_at":{"type":"integer"},"started_at":{"type":["integer","null"]},"finished_at":{"type":["integer","null"]},"updated_at":{"type":"integer"},"poll_url":{"type":"string"},"items_url":{"type":"string"}}},"WebhookEvent":{"type":"object","required":["id","type","created","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["job.succeeded","job.partial","job.failed","job.canceled"]},"created":{"type":"integer","description":"Unix timestamp in seconds."},"data":{"type":"object","required":["job_id","status","total","completed","failed","credits_charged"],"properties":{"job_id":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"},"credits_charged":{"type":"integer"}}}}},"JobItem":{"type":"object","properties":{"video_id":{"type":"string"},"title":{"type":["string","null"]},"duration_seconds":{"type":["number","null"]},"view_count":{"type":["integer","null"]},"position":{"type":["integer","null"]},"status":{"type":"string","enum":["pending","processing","done","failed"]},"language_code":{"type":["string","null"]},"translation_target":{"type":["string","null"]},"error_code":{"type":["string","null"]},"credits":{"type":"integer"},"attempts":{"type":"integer"},"updated_at":{"type":"integer"}}},"RegexResult":{"type":"object","required":["mode","matches","truncated","count"],"properties":{"mode":{"const":"regex"},"matches":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"start":{"type":"number"},"duration":{"type":"number"},"index":{"type":"integer"},"groups":{"type":"array","items":{"type":"string"}},"context":{"type":["string","null"]}}}},"truncated":{"type":"boolean"},"count":{"type":"integer"}}},"KeywordResult":{"type":"object","required":["mode","matches","summary","truncated","count"],"properties":{"mode":{"const":"keyword"},"matches":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"snippet_text":{"type":"string"},"start":{"type":"number"},"duration":{"type":"number"},"offset_in_text":{"type":"integer"}}}},"summary":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"count":{"type":"integer"},"first_start":{"type":["number","null"]}}}},"truncated":{"type":"boolean"},"count":{"type":"integer"}}},"ChunkResult":{"type":"object","required":["mode","chunks","count","token_estimate_method"],"properties":{"mode":{"const":"chunk"},"chunks":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"},"token_estimate":{"type":"integer"},"snippet_start":{"type":"integer"},"snippet_end":{"type":"integer"},"oversize":{"type":"boolean"},"overlap":{"type":"boolean"}}}},"count":{"type":"integer"},"token_estimate_method":{"const":"chars_div_4"}}},"TranscriptQueryResult":{"oneOf":[{"$ref":"#/components/schemas/RegexResult"},{"$ref":"#/components/schemas/KeywordResult"},{"$ref":"#/components/schemas/ChunkResult"}]},"TranscriptQuery":{"type":"object","required":["mode"],"properties":{"url":{"type":"string"},"video_id":{"type":"string"},"lang":{"type":"string","default":"en"},"translate":{"type":"string"},"type":{"type":"string","enum":["any","manual","generated"],"default":"any"},"mode":{"type":"string","enum":["regex","keyword","chunk"]},"pattern":{"type":"string","maxLength":200,"description":"Required for regex mode; applied independently to transcript snippets."},"flags":{"type":"string","maxLength":8,"description":"Regex flags supported: i, m, s, u, y."},"terms":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":200},"description":"Required for keyword mode; combined term length is capped at 4096 characters."},"case_sensitive":{"type":"boolean","default":false},"context_chars":{"type":"integer","minimum":0,"maximum":1000},"target_tokens":{"type":"integer","minimum":1,"maximum":2048,"default":256,"description":"Required effective constraint: target_tokens must not exceed max_tokens."},"max_tokens":{"type":"integer","minimum":1,"maximum":2048,"default":2048},"overlap_snippets":{"type":"integer","minimum":0,"maximum":20,"default":0}},"anyOf":[{"required":["url"]},{"required":["video_id"]}],"allOf":[{"if":{"properties":{"mode":{"const":"regex"}},"required":["mode"]},"then":{"required":["pattern"]}},{"if":{"properties":{"mode":{"const":"keyword"}},"required":["mode"]},"then":{"required":["terms"]}}]},"BatchRequest":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}},"lang":{"type":"string","default":"en"},"translate":{"type":"string"},"type":{"type":"string","enum":["any","manual","generated"],"default":"any"},"formats":{"type":"array","items":{"type":"string","enum":["srt","vtt","text"]},"maxItems":3},"metadata":{"type":"boolean","default":true},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS callback. Save webhook_secret from the submission response; callbacks use X-YTGW-Signature."}}},"ChannelRequest":{"type":"object","required":["channel"],"properties":{"channel":{"oneOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}}]},"mode":{"type":"string","enum":["list","transcribe"],"default":"list"},"max_videos":{"type":"integer","minimum":1,"maximum":100000,"default":100,"description":"Plan limit applies; mode=transcribe is capped at 250 videos per job."},"lang":{"type":"string","default":"en"},"translate":{"type":"string"},"type":{"type":"string","enum":["any","manual","generated"],"default":"any"},"formats":{"type":"array","items":{"type":"string","enum":["srt","vtt","text"]},"maxItems":3},"metadata":{"type":"boolean","default":true},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS callback; save webhook_secret from the submission response to verify X-YTGW-Signature."}}},"MediaRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS URL for a supported media filename (mp3, m4a, mp4, m4v, mov, webm, mkv, wav, flac, ogg, oga, opus, aac, wma, aiff, aif, mka, or ts). Page URLs and YouTube URLs are rejected."},"format":{"type":"string","enum":["json","text","srt","vtt"],"default":"json"},"cleanup":{"type":"boolean","default":false},"diarize":{"type":"boolean","default":false,"description":"Implies tier=premium."},"tier":{"type":"string","enum":["normal","premium","auto"],"default":"auto","description":"Speech model tier."},"speakers":{"type":"string"},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS callback; save webhook_secret from the submission response to verify X-YTGW-Signature."}},"required":["url"]}}},"paths":{"/healthz":{"get":{"summary":"Health check","description":"Unauthenticated health endpoint. Reports binding presence only.","security":[],"responses":{"200":{"description":"Worker health status and binding availability.","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"service":"ytgw","now":"2026-01-15T12:00:00.000Z","bindings":{"db":true,"r2":true,"kv":true,"queue":true,"single_flight":true,"breaker":true,"ratelimits":true,"apify_token":true,"public_origin":true,"cache_l1_enabled":true}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"summary":"Download the OpenAPI specification","description":"Unauthenticated machine-readable OpenAPI 3.1 document for this API.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 specification.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}}}},"/v1/transcripts":{"get":{"summary":"List your transcript library","description":"Returns videos this account has paid to retrieve, newest first. Continue a page with `cursor` set to the previous `next_cursor`; the cursor carries the snapshot watermark, so new deliveries do not move the boundary of a walk.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Transcript library page.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"video_id":{"type":"string"},"last_fetched_at":{"type":"integer"},"fetches":{"type":"integer"},"title":{"type":["string","null"]}}}},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."}}},"example":{"items":[{"video_id":"dQw4w9WgXcQ","last_fetched_at":1768478400000,"fetches":3,"title":"Sample video"}],"limit":25,"has_more":false,"next_cursor":null}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"search","in":"query","schema":{"type":"string","maxLength":64}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"$ref":"#/components/parameters/Cursor"}],"x-error-codes":["invalid_request","unauthorized","rate_limited","internal_error"]},"post":{"summary":"Request a YouTube transcript","description":"Returns the transcript when it is ready within `deadline_ms` (200). Otherwise returns 202 with `Location` set to `GET /v1/transcripts/{videoId}` for the same options; request that URL until it answers 200. A 202 is not charged as a transcript delivery. `engine=stt` explicitly transcribes audio when captions are not requested; it does not support translation.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Transcript in the requested format.","headers":{"X-Cache":{"description":"Transcript source tier (for example HIT-L1, HIT-R2, MISS, or HIT-COALESCED).","schema":{"type":"string"}},"X-Credits-Charged":{"description":"Credits charged for this delivery.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Remaining account credits when available.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"},"example":{"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":{"code":"en","name":"English","is_generated":true},"translation":null,"duration_seconds":3.6,"snippet_count":2,"transcript":{"text":"Welcome to the sample video.","timestamped":[{"text":"Welcome to the sample","start":0,"duration":2.4},{"text":"video.","start":2.4,"duration":1.2}]},"metadata":{"engine":"captions"},"source":{"cache":"UPSTREAM","fetched_at":"2026-01-15T12:00:00.000Z"}}},"text/plain":{"schema":{"type":"string","description":"Plain transcript text."},"example":"Welcome to the sample video."},"application/x-subrip":{"schema":{"type":"string","description":"SubRip subtitle file."},"example":"1\n00:00:00,000 --> 00:00:02,400\nWelcome to the sample\n\n2\n00:00:02,400 --> 00:00:03,600\nvideo."},"text/vtt":{"schema":{"type":"string","description":"WebVTT subtitle file."},"example":"WEBVTT\n\n00:00:00.000 --> 00:00:02.400\nWelcome to the sample\n\n00:00:02.400 --> 00:00:03.600\nvideo."}}},"202":{"description":"The transcript is still being produced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processing"},"example":{"video_id":"dQw4w9WgXcQ","state":"processing"}}},"headers":{"Location":{"description":"The URL to request again — the same one a finished result is read from.","schema":{"type":"string"}},"Retry-After":{"description":"Suggested delay in seconds before the next request.","schema":{"type":"integer","example":2}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptRequest"},"example":{"video_id":"dQw4w9WgXcQ","format":"json","lang":"en"}}}},"x-error-codes":["invalid_request","unauthorized","insufficient_credits","video_not_found","transcript_unavailable","rate_limited","quota_exceeded","upstream_error","upstream_unavailable","upstream_timeout","internal_error"]}},"/v1/transcripts/{videoId}":{"get":{"summary":"Read a published YouTube transcript","description":"Cache-only read: this route never starts upstream work. 200 is the transcript; 202 means a run you started with `POST /v1/transcripts` is still going (request it again after `Retry-After`); 404 means nothing is published and none of yours is running; 422 means your run failed. The first delivery of each transcript variant is billed; once the account owns that variant, reads are free. The charge is made once per account and variant, so retrying a read never bills twice. Send an Idempotency-Key on a retry of a paid first read to skip the balance pre-check, so the retry can still be served after the first attempt spent the last credit; reuse the key only for retries of that same read.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Transcript in the requested format.","headers":{"X-Cache":{"description":"Transcript source tier (for example HIT-L1, HIT-R2, MISS, or HIT-COALESCED).","schema":{"type":"string"}},"X-Credits-Charged":{"description":"Credits charged for this delivery.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Remaining account credits when available.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"},"example":{"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":{"code":"en","name":"English","is_generated":true},"translation":null,"duration_seconds":3.6,"snippet_count":2,"transcript":{"text":"Welcome to the sample video.","timestamped":[{"text":"Welcome to the sample","start":0,"duration":2.4},{"text":"video.","start":2.4,"duration":1.2}]},"metadata":{"engine":"captions"},"source":{"cache":"UPSTREAM","fetched_at":"2026-01-15T12:00:00.000Z"}}},"text/plain":{"schema":{"type":"string","description":"Plain transcript text."},"example":"Welcome to the sample video."},"application/x-subrip":{"schema":{"type":"string","description":"SubRip subtitle file."},"example":"1\n00:00:00,000 --> 00:00:02,400\nWelcome to the sample\n\n2\n00:00:02,400 --> 00:00:03,600\nvideo."},"text/vtt":{"schema":{"type":"string","description":"WebVTT subtitle file."},"example":"WEBVTT\n\n00:00:00.000 --> 00:00:02.400\nWelcome to the sample\n\n00:00:02.400 --> 00:00:03.600\nvideo."}}},"202":{"description":"A transcript you requested is still being produced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processing"},"example":{"video_id":"dQw4w9WgXcQ","state":"processing"}}},"headers":{"Location":{"description":"The URL to request again — the same one a finished result is read from.","schema":{"type":"string"}},"Retry-After":{"description":"Suggested delay in seconds before the next request.","schema":{"type":"integer","example":2}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. Reuse this value only for retries of the same account, transcript, and render options.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[!-~]+$"}},{"name":"format","in":"query","description":"Output format.","schema":{"type":"string","enum":["json","text","srt","vtt"],"default":"json"}},{"name":"lang","in":"query","description":"Preferred YouTube caption language (ISO 639-1). Defaults to en.","schema":{"type":"string","default":"en","example":"en"}},{"name":"translate","in":"query","description":"Translate a YouTube caption track to this ISO 639-1 language. Not supported with engine=stt.","schema":{"type":"string","example":"es"}},{"name":"type","in":"query","description":"Caption track type.","schema":{"type":"string","enum":["any","manual","generated"],"default":"any"}},{"name":"metadata","in":"query","description":"Include source metadata in JSON responses.","schema":{"type":"boolean","default":true}},{"name":"also","in":"query","description":"Comma-separated extra renderings included in a JSON response.","schema":{"type":"string","example":"srt,vtt"}},{"name":"engine","in":"query","description":"Use YouTube caption tracks (default) or explicitly transcribe audio with STT.","schema":{"type":"string","enum":["captions","stt"],"default":"captions"}},{"name":"deadline_ms","in":"query","description":"Maximum synchronous wait before returning a job. Defaults to 20000; capped at 60000.","schema":{"type":"integer","minimum":1000,"maximum":60000,"default":20000}},{"name":"cleanup","in":"query","description":"Remove conversational filler from the rendered result.","schema":{"type":"boolean","default":false}},{"name":"diarize","in":"query","description":"Label speakers. Requires engine=stt; implies tier=premium.","schema":{"type":"boolean","default":false}},{"name":"speakers","in":"query","description":"Rename diarization labels, for example Speaker%201=Host.","schema":{"type":"string","example":"Speaker 1=Host,Speaker 2=Guest"}},{"name":"tier","in":"query","description":"Speech model tier — normal bills 1 credit per audio minute; premium bills 10 and supports speaker labels. engine=stt only.","schema":{"type":"string","enum":["normal","premium","auto"],"default":"auto"}}],"x-error-codes":["invalid_request","unauthorized","insufficient_credits","not_found","transcript_unavailable","rate_limited","internal_error"]}},"/v1/transcripts/{videoId}/discover":{"get":{"summary":"Discover caption tracks","description":"Lists available caption tracks for a YouTube video. Discovery is free and subject to a plan-based monthly upstream quota. If discovery continues past the deadline, the 202 response asks you to request this same endpoint again.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Available caption tracks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discover"},"example":{"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","available_transcripts":[{"language_code":"en","language":"English","is_generated":true,"is_translatable":true,"translation_languages":["es"]}],"result_types":["json","text","srt","vtt"],"source":{"cache":"UPSTREAM","fetched_at":"2026-01-15T12:00:00.000Z"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"202":{"description":"Discovery is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processing"},"example":{"video_id":"dQw4w9WgXcQ","state":"processing"}}},"headers":{"Location":{"description":"The URL to request again — the same one a finished result is read from.","schema":{"type":"string"}},"Retry-After":{"description":"Suggested delay in seconds before the next request.","schema":{"type":"integer","example":2}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$"}},{"name":"deadline_ms","in":"query","schema":{"type":"integer","minimum":1000,"maximum":60000,"default":20000}}],"x-error-codes":["invalid_request","unauthorized","video_not_found","rate_limited","quota_exceeded","upstream_error","upstream_unavailable","upstream_timeout","internal_error"]}},"/v1/transcripts/batch":{"post":{"summary":"Submit a batch transcript job","description":"Queues unique YouTube URLs for processing. The plan controls the maximum URLs per job. Poll the returned job and use its items endpoint to inspect per-video outcomes.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"example":{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"batch","status":"launching","state":"preparing","terminal":false,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":null,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}}},"headers":{"Location":{"description":"URL to poll for job status.","schema":{"type":"string"}},"Retry-After":{"description":"Suggested delay in seconds before the next poll.","schema":{"type":"integer","example":2}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"`true` when this response replays the job created by an earlier request with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"urls":["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],"lang":"en","formats":["srt"]}}}},"x-error-codes":["invalid_request","unauthorized","insufficient_credits","conflict","rate_limited","internal_error"]}},"/v1/transcripts/query":{"post":{"summary":"Search or chunk a cached transcript","description":"Runs regex, keyword, or chunk operations against an already-cached transcript. This endpoint never fetches a transcript; call POST /v1/transcripts first on a cache miss.","tags":["Transcripts"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Result for the selected query mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptQueryResult"},"examples":{"regex":{"summary":"Regex match","value":{"mode":"regex","matches":[{"text":"sample video","start":1.2,"duration":1.4,"index":0,"groups":[],"context":"Welcome to the sample video."}],"truncated":false,"count":1}},"keyword":{"summary":"Keyword match","value":{"mode":"keyword","matches":[{"term":"video","snippet_text":"Welcome to the sample video.","start":2.4,"duration":1.2,"offset_in_text":24}],"summary":[{"term":"video","count":1,"first_start":2.4}],"truncated":false,"count":1}},"chunk":{"summary":"Transcript chunk","value":{"mode":"chunk","chunks":[{"index":0,"text":"Welcome to the sample video.","start":0,"end":3.6,"token_estimate":8,"snippet_start":0,"snippet_end":1,"oversize":false,"overlap":false}],"count":1,"token_estimate_method":"chars_div_4"}}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptQuery"},"examples":{"regex":{"value":{"video_id":"dQw4w9WgXcQ","mode":"regex","pattern":"transcript","flags":"i","context_chars":50}},"keyword":{"value":{"video_id":"dQw4w9WgXcQ","mode":"keyword","terms":["music","video"],"context_chars":80}},"chunk":{"value":{"video_id":"dQw4w9WgXcQ","mode":"chunk","target_tokens":800,"overlap_snippets":2}}}}}},"x-error-codes":["invalid_request","unauthorized","not_found","rate_limited","internal_error"]}},"/v1/channels/transcribe":{"post":{"summary":"List or transcribe a channel","description":"Creates an asynchronous channel job. `mode=list` collects video metadata; `mode=transcribe` also transcribes listed videos. Listing costs one credit per 100 video rows collected; transcribe mode charges one credit per delivered transcript variant the account does not own yet. A job may include up to 10 channel references; plan limits apply to videos per channel, and transcription is capped at 250 videos per job.","tags":["Channels"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"example":{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"batch","status":"launching","state":"preparing","terminal":false,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":null,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}}},"headers":{"Location":{"description":"URL to poll for job status.","schema":{"type":"string"}},"Retry-After":{"description":"Suggested delay in seconds before the next poll.","schema":{"type":"integer","example":2}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"`true` when this response replays the job created by an earlier request with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelRequest"},"example":{"channel":"https://www.youtube.com/@NASA","mode":"list","max_videos":100}}}},"x-error-codes":["invalid_request","unauthorized","insufficient_credits","conflict","rate_limited","internal_error"]}},"/v1/jobs":{"get":{"summary":"List jobs","description":"Returns this account’s jobs newest first. Filter by `state`. Continue a page with `cursor` set to the previous `next_cursor`.","tags":["Jobs"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Jobs page.","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."}}},"example":{"jobs":[{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"batch","status":"launching","state":"preparing","terminal":false,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":null,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}],"limit":25,"has_more":false,"next_cursor":null}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"state","in":"query","schema":{"type":"string","enum":["waiting","preparing","processing","done","failed"]}},{"$ref":"#/components/parameters/Cursor"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"x-error-codes":["invalid_request","unauthorized","rate_limited","internal_error"]}},"/v1/jobs/{jobId}":{"get":{"summary":"Get a job","description":"Poll this account’s job. Treat `state` as the stable polling contract and stop when it is `done` or `failed`. On completion, follow `result_url` for single-result jobs; batch and channel results are listed at `items_url`.","tags":["Jobs"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Current job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"example":{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"batch","status":"launching","state":"preparing","terminal":false,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":null,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"x-error-codes":["unauthorized","job_not_found","rate_limited","internal_error"]},"delete":{"summary":"Cancel a job","description":"Cancels a non-terminal job. Cancellation returns 202 while cleanup may continue, and cancelling a job that is already cancelled returns 202 again. A job that has already finished returns 409.","tags":["Jobs"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"202":{"description":"Cancellation accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"example":{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"batch","status":"canceled","state":"failed","terminal":true,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":1768478400000,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"x-error-codes":["unauthorized","job_not_found","conflict","rate_limited","internal_error"]}},"/v1/jobs/{jobId}/items":{"get":{"summary":"List job items","description":"Lists item-level results for a batch, channel, or other multi-item job.","tags":["Jobs"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Job items page.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/JobItem"}}}},"example":{"job_id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","status":"succeeded","limit":50,"has_more":false,"next_cursor":null,"items":[{"video_id":"dQw4w9WgXcQ","title":"Sample video","duration_seconds":3.6,"view_count":42,"position":1,"status":"done","language_code":"en","translation_target":null,"error_code":null,"credits":1,"attempts":1,"updated_at":1768478400000}]}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","done","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"$ref":"#/components/parameters/Cursor"}],"x-error-codes":["invalid_request","unauthorized","job_not_found","rate_limited","internal_error"]}},"/v1/media":{"post":{"summary":"Transcribe a media URL","description":"Submit a public HTTPS audio/video file URL. A cached transcript returns 200 inline; a new transcription returns 202 with `media_id`, `poll_url`, and `transcript_url`. YouTube URLs belong on /v1/transcripts. Audio is billed at one credit per started minute.","tags":["Media"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Cached media transcript.","content":{"application/json":{"schema":{"type":"object","properties":{"media_id":{"type":"string"},"format":{"type":"string"},"document":{"oneOf":[{"$ref":"#/components/schemas/StoredTranscript"},{"type":"string","description":"Rendered text, SRT, or VTT when format is not json."}]},"cache":{"type":"string"},"charged_credits":{"type":"integer"}}},"example":{"media_id":"med_01JQ8S7X4M6V2A1B9C3D5E7F0G","format":"json","document":{"v":1,"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":{"code":"en","name":"English"},"translation":null,"is_translatable":false,"translation_languages":[],"duration_seconds":3.6,"snippet_count":2,"snippets":[{"text":"Welcome to the sample","start":0,"duration":2.4},{"text":"video.","start":2.4,"duration":1.2}],"text":"Welcome to the sample video.","metadata":{"engine":"stt"},"fetched_at":"2026-01-15T12:00:00.000Z","upstream":{}},"cache":"hit","charged_credits":1}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"202":{"description":"Transcription accepted or already in progress.","content":{"application/json":{"schema":{"type":"object","properties":{"media_id":{"type":"string"},"job_id":{"type":"string"},"status":{"const":"accepted"},"coalesced":{"type":"boolean"},"poll_url":{"type":"string"},"transcript_url":{"type":"string"},"job":{"$ref":"#/components/schemas/Job"}}},"example":{"media_id":"med_01JQ8S7X4M6V2A1B9C3D5E7F0G","url":"https://cdn.example.com/episode.mp3","job_id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","status":"accepted","coalesced":false,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","transcript_url":"/v1/media/med_01JQ8S7X4M6V2A1B9C3D5E7F0G/transcript","job":{"id":"job_01JQ8S7X4M6V2A1B9C3D5E7F0G","type":"stt_url","status":"launching","state":"preparing","terminal":false,"progress":0,"total_items":2,"completed_items":0,"failed_items":0,"credits_charged":0,"error_code":null,"error":null,"result_url":null,"webhook_configured":false,"created_at":1768478400000,"started_at":1768478400000,"finished_at":null,"updated_at":1768478400000,"poll_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G","items_url":"/v1/jobs/job_01JQ8S7X4M6V2A1B9C3D5E7F0G/items"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaRequest"},"example":{"url":"https://cdn.example.com/episode.mp3","format":"vtt","diarize":true}}}},"x-error-codes":["invalid_request","unauthorized","insufficient_credits","transcript_unavailable","rate_limited","upstream_error","upstream_unavailable","internal_error"]}},"/v1/media/{mediaId}/transcript":{"get":{"summary":"Read a media transcript","description":"Reads the result after the media job finishes. Returns 422 while a transcript is not ready or unavailable.","tags":["Media"],"security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Transcript in the requested format.","headers":{"X-Cache":{"description":"Transcript source tier (for example HIT-L1, HIT-R2, MISS, or HIT-COALESCED).","schema":{"type":"string"}},"X-Credits-Charged":{"description":"Credits charged for this delivery.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Remaining account credits when available.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredTranscript"},"example":{"v":1,"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":{"code":"en","name":"English"},"translation":null,"is_translatable":false,"translation_languages":[],"duration_seconds":3.6,"snippet_count":2,"snippets":[{"text":"Welcome to the sample","start":0,"duration":2.4},{"text":"video.","start":2.4,"duration":1.2}],"text":"Welcome to the sample video.","metadata":{"engine":"stt"},"fetched_at":"2026-01-15T12:00:00.000Z","upstream":{}}},"text/plain":{"schema":{"type":"string","description":"Plain transcript text."},"example":"Welcome to the sample video."},"application/x-subrip":{"schema":{"type":"string","description":"SubRip subtitle file."},"example":"1\n00:00:00,000 --> 00:00:02,400\nWelcome to the sample\n\n2\n00:00:02,400 --> 00:00:03,600\nvideo."},"text/vtt":{"schema":{"type":"string","description":"WebVTT subtitle file."},"example":"WEBVTT\n\n00:00:00.000 --> 00:00:02.400\nWelcome to the sample\n\n00:00:02.400 --> 00:00:03.600\nvideo."}}},"400":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"url or video_id is required","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Valid API credentials are required.","request_id":"req_01JQ8S7X"}}}},"headers":{"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","example":"Bearer"}},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_credits","message":"Insufficient credits for this request.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"403":{"description":"The account or requested operation is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"This operation is not allowed for the account.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"404":{"description":"The requested resource does not exist or is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"409":{"description":"The resource is in a state that prevents this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"The resource is in a state that prevents this operation.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"413":{"description":"The request or uploaded file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"The request or uploaded file is too large.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"The request content type is not supported.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"422":{"description":"A transcript cannot be produced for this source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"transcript_unavailable","message":"A transcript cannot be produced for this source.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"429":{"description":"The account reached a rate, concurrency, or plan quota. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"The account reached a rate, concurrency, or plan quota.","request_id":"req_01JQ8S7X"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"500":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An internal error occurred.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"502":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_error","message":"The upstream provider returned an error.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"503":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The upstream provider is unavailable.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}},"504":{"description":"An API error. `request_id` matches the X-Request-Id response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_timeout","message":"The upstream provider timed out.","request_id":"req_01JQ8S7X"}}}},"headers":{"X-Request-Id":{"description":"Unique request identifier for support and log correlation.","schema":{"type":"string"}}}}},"parameters":[{"name":"mediaId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","text","srt","vtt"],"default":"json"}},{"name":"cleanup","in":"query","schema":{"type":"string"}},{"name":"diarize","in":"query","schema":{"type":"string"}},{"name":"speakers","in":"query","schema":{"type":"string"}}],"x-error-codes":["invalid_request","unauthorized","transcript_unavailable","rate_limited","internal_error"]}}},"webhooks":{"terminalJobEvent":{"post":{"summary":"Terminal job event","description":"TranscriptLab POSTs one event when a webhook-enabled job becomes succeeded, partial, failed, or canceled. A 2xx response acknowledges delivery; failed or non-2xx deliveries are retried. The `webhook_secret` is returned once in the job submission response and is not included in later job reads.","parameters":[{"name":"X-YTGW-Event","in":"header","required":true,"schema":{"type":"string","enum":["job.succeeded","job.partial","job.failed","job.canceled"]}},{"name":"X-YTGW-Signature","in":"header","required":true,"description":"Format `t=<unix-seconds>,v1=<hex-hmac>`. Verify HMAC-SHA256 using the saved webhook_secret over the exact string `<timestamp>.<raw request body>`; compare signatures in constant time and reject stale timestamps.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Event acknowledged."}}}}}}