TranscriptResponse
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"ready"
]
},
"video": {
"$ref": "#/components/schemas/TranscriptVideo"
},
"quality": {
"type": "string",
"enum": [
"captions",
"premium"
],
"description": "The requested quality. Premium is served only with an owned unlock; it never falls back to captions."
},
"source": {
"type": "string",
"enum": [
"creator_captions",
"third_party_quick",
"arcmira_premium"
],
"description": "Public source class. creator_captions were written or approved by the channel, third_party_quick are YouTube automatic captions, arcmira_premium is our own diarized transcript."
},
"language": {
"type": "string",
"description": "The language of the lines: the resolved track code (asr-en style when the track is automatic) or, when the transcript was translated, the code it was translated into."
},
"base_language": {
"type": "string",
"description": "The transcript's own language, as a code (en, es): the original caption track's, or the language a Premium transcript was spoken and transcribed in. language= returns the transcript in it; a language other than base_language means the lines were translated."
},
"languages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CaptionTrack"
},
"description": "Every caption track the video offers. Empty when we did not list them on this call."
},
"translation_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "The codes language can name on this read. On captions, only the languages YouTube makes available for the video (its own tracks, and its auto-translate languages); on Premium, every language Arcmira translates into, at the Premium rate."
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number",
"description": "Line start in seconds from the beginning of the video."
},
"end": {
"type": "number",
"description": "Line end in seconds."
},
"text": {
"type": "string"
},
"speaker": {
"type": "integer",
"description": "The person saying this line, present on every Premium line. Join it against speakers[].id."
},
"index": {
"type": "integer",
"description": "Line index, present on every Premium line. Stable within one revision."
}
},
"required": [
"start",
"end",
"text"
]
},
"description": "Present when timestamps is true. Cite start with watch_url."
},
"paragraphs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number",
"description": "Paragraph start in seconds."
},
"text": {
"type": "string"
},
"speaker": {
"type": "integer"
}
},
"required": [
"start",
"text"
]
},
"description": "Present when timestamps is false. Lines joined on speaker changes for Premium and on sentence boundaries for captions."
},
"speakers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"x-arcmira-ordinal": true,
"description": "Speaker id, numbered in the order people first speak. Only meaningful with this read and its revision."
},
"name": {
"type": "string",
"description": "The identified person, or Speaker 1, Speaker 2 and so on for a voice nobody has identified yet."
},
"entity_id": {
"type": [
"string",
"null"
],
"description": "Public entity id (\"ent_{n}\") of the identified person. Null when the speaker is unidentified."
},
"confidence": {
"type": [
"string",
"null"
],
"description": "high when the name was reviewed, low when it is your own identification still awaiting review, null when nobody is identified."
}
},
"required": [
"id",
"name",
"entity_id",
"confidence"
]
},
"description": "Premium only. Speaker identification is right most of the time and wrong sometimes; say it came from Arcmira when a name matters."
},
"revision": {
"type": "string",
"description": "Premium reads only. Opaque id of the transcript you were served, the approved corrections on it, and who speaks each line. It changes when any of those change."
},
"range": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
},
"required": [
"start",
"end"
],
"description": "Echoed when you sent start and end. Lines overlapping the window are returned. On captions only the window is billed. An explicit Premium read is charged for the whole video, from the account's plan credits and then its on-demand budget; the window only trims the returned content."
},
"rows_billed": {
"type": "integer",
"description": "Credits this captions read used, in rows (a row is 4 credits): 4 credits per started 15 minutes. 0 on a repeat of the same video, quality, language, translation, and range inside the 7 day dedupe window. Premium reads report 0, because the Premium transcript job carries their charge, except the read that pays for a Premium transcript in another language, which reports its rows."
},
"as_of": {
"type": [
"string",
"null"
],
"description": "When the transcript was produced."
},
"premium_job": {
"allOf": [
{
"$ref": "#/components/schemas/TranscriptionJob"
},
{
"description": "Your open Premium transcript job for this video, when captions were served while it transcribes."
}
]
},
"access": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"permission_error",
"quota_exceeded",
"rate_limit_error",
"not_found",
"conflict_error",
"server_error"
],
"description": "The error class. It fixes the HTTP status: invalid_request_error 400, authentication_error 401, quota_exceeded 402, permission_error 403, not_found 404, conflict_error 409, rate_limit_error 429, server_error 500. Switch on it for retry and gate handling."
},
"code": {
"type": "string",
"description": "The specific condition, stable and snake_case; doc_url anchors on it. x-arcmira-codes on this schema lists every code with its type, gate and meaning. The list is open: new codes may appear inside an existing type, so switch on type and gate first."
},
"reason": {
"type": "string",
"enum": [
"no_credential",
"invalid",
"revoked"
],
"description": "Only on invalid_api_key. no_credential: nothing was sent. invalid: a credential was sent and is unknown or malformed. revoked: the key exists and is no longer usable."
},
"message": {
"type": "string",
"description": "One plain line. Names the fix or the unlock."
},
"param": {
"type": "string",
"description": "The query or body parameter the gate refused, when one did."
},
"gate": {
"type": "string",
"enum": [
"rows",
"key",
"plan",
"freshness",
"exposure_law",
"rate",
"pagination"
],
"description": "Which boundary refused. Present on every gate error; switch on it without parsing the message."
},
"resource": {
"$ref": "#/components/schemas/ErrorResource"
},
"unlock": {
"type": "object",
"properties": {
"tier": {
"type": "string",
"description": "The plan that lifts the gate."
},
"url": {
"type": "string",
"description": "Absolute upgrade or sign-up URL carrying its ?src= attribution. Use it verbatim."
},
"offer": {
"type": "null",
"description": "Reserved for the agent-discount offer. Always null today."
},
"action": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "What the call does. send_signup_code sends a verification code to an address for an account key."
},
"method": {
"type": "string",
"description": "HTTP method to use."
},
"url": {
"type": "string",
"description": "Absolute endpoint carrying its ?src= attribution. Call it verbatim."
}
},
"required": [
"kind",
"method",
"url"
],
"description": "The request that lifts the gate with no human, present when the caller can fix this itself. A key gate carries the signup send here; a plan or quota gate has no action and its url is a page a person opens."
}
},
"required": [
"tier",
"url",
"offer"
],
"description": "How to lift the gate. Present when the gate has an unlock."
},
"retry_after_seconds": {
"type": "integer",
"description": "Present on rate gates. Mirrors the Retry-After header."
},
"details": {
"type": "object",
"properties": {
"quote": {
"$ref": "#/components/schemas/RefusedQuote"
},
"limit": {
"$ref": "#/components/schemas/Limit"
},
"url": {
"type": "string",
"description": "On terms_acceptance_required: the page where the person accepts the updated Terms of Service. On terms_updated: the Terms of Service page."
}
},
"description": "Machine data the refusal carries for you to act on. Present only on the codes that name a field here."
},
"doc_url": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"required": [
"type",
"code",
"message",
"doc_url",
"request_id"
],
"description": "The gate that reduced this response. Present only when something was withheld; carries the same code, gate, and unlock an outright refusal would."
},
"note": {
"type": "string",
"description": "One steering sentence for the agent reading this. On Premium it is the diarization disclosure verbatim."
}
},
"required": [
"state",
"video",
"quality",
"source",
"language",
"base_language",
"languages",
"translation_languages",
"rows_billed",
"as_of",
"note"
],
"examples": [
{
"video": {
"id": "dQw4w9WgXcQ",
"title": "TBPN | Tuesday, August 4",
"channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
"channel_name": "TBPN",
"published_at": "2026-08-04T17:00:00.000Z",
"duration_seconds": 10800,
"watch_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
},
"quality": "captions",
"source": "creator_captions",
"language": "en",
"base_language": "en",
"languages": [
{
"code": "en",
"name": "English",
"generated": false
}
],
"translation_languages": [
"ar",
"de",
"es",
"fr",
"hi",
"ja",
"ko",
"pt",
"zh-Hans"
],
"lines": [
{
"start": 4787,
"end": 4791.5,
"text": "Ramp has been on the show for a while now."
},
{
"start": 4791.5,
"end": 4796,
"text": "The pitch is still the same, spend less time on expenses."
}
],
"rows_billed": 12,
"as_of": "2026-08-04T18:12:00.000Z",
"note": "This transcript is the video's own caption track. `creator_captions` were written or approved by the channel; `third_party_quick` are YouTube's automatic captions and can misspell names and drop punctuation. `language` says which track you got."
},
{
"video": {
"id": "aB3dE5fG7hI",
"title": "Moment of Truth | The permitting fight nobody watched",
"channel_id": "UClWkDGXEzsh77GAhs90wpXw",
"channel_name": "Moment of Truth",
"published_at": "2026-08-19T14:00:00.000Z",
"duration_seconds": 4500,
"watch_url": "https://www.youtube.com/watch?v=aB3dE5fG7hI"
},
"quality": "premium",
"source": "arcmira_premium",
"language": "en",
"base_language": "en",
"languages": [
{
"code": "en",
"name": "English",
"generated": false
}
],
"translation_languages": [
"ar",
"de",
"es",
"fr",
"hi",
"ja",
"ko",
"pt",
"zh-Hans"
],
"lines": [
{
"start": 612,
"end": 617.5,
"text": "The permit sat in review for nineteen months.",
"speaker": 0,
"index": 0
},
{
"start": 617.5,
"end": 623,
"text": "And the second review started before the first one closed.",
"speaker": 1,
"index": 1
}
],
"speakers": [
{
"id": 0,
"name": "Dana Whitfield",
"entity_id": 4821,
"confidence": "high"
},
{
"id": 1,
"name": "Speaker 1",
"entity_id": null,
"confidence": null
}
],
"revision": "rev_7f2c1a.0k3m9x",
"rows_billed": 375,
"as_of": "2026-08-19T16:40:00.000Z",
"note": "Premium transcripts are Arcmira's own. Every Premium transcript is diarized: each line carries a speaker. We identify each speaker from the audio, the video, and internal and community review. We are right most of the time and wrong sometimes, so when a name matters, say it came from Arcmira's speaker identification and cite the line."
}
]
}