YouTube transcript API reference.

Authorization: Bearer tl_live_...

curl https://api.transcriptlayer.com/v1/transcripts \
  -H "Authorization: Bearer $TRANSCRIPTLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-row-1842" \
  -d '{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language_preferences": [
    "en"
  ],
  "caption_kinds": [
    "manual"
  ],
  "include": [
    "available_tracks"
  ]
}'

HTTP/1.1 202 Accepted
Location: https://api.transcriptlayer.com/v1/transcripts/tr_7QxK2mYb
Retry-After: 2
X-Credits-Charged: 0

{
  "id": "tr_7QxK2mYb",
  "request_id": "req_5nD8vTca",
  "object": "transcript",
  "status": "processing",
  "source": {
    "platform": "youtube",
    "id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "requested": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language_preferences": [
      "en"
    ],
    "caption_kinds": [
      "manual"
    ],
    "language_fallback": "none",
    "content_format": "segments",
    "allow_stale_on_error": false,
    "include": [
      "available_tracks"
    ]
  },
  "usage": {
    "credits_charged": 0
  },
  "poll_url": "https://api.transcriptlayer.com/v1/transcripts/tr_7QxK2mYb",
  "created_at": "2026-08-22T09:41:05Z",
  "updated_at": "2026-08-22T09:41:05Z"
}

HTTP/1.1 200 OK
X-Credits-Charged: 1

{
  "id": "tr_7QxK2mYb",
  "request_id": "req_5nD8vTca",
  "object": "transcript",
  "status": "completed",
  "source": {
    "platform": "youtube",
    "id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "requested": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language_preferences": [
      "en"
    ],
    "caption_kinds": [
      "manual"
    ],
    "language_fallback": "none",
    "content_format": "segments",
    "allow_stale_on_error": false,
    "include": [
      "available_tracks"
    ]
  },
  "track": {
    "id": "yt.cc.en",
    "language": "en",
    "name": "English",
    "kind": "manual",
    "fallback_applied": false
  },
  "available_tracks": [
    {
      "id": "yt.cc.en",
      "language": "en",
      "name": "English",
      "kind": "manual"
    },
    {
      "id": "yt.asr.en",
      "language": "en",
      "name": "English (auto-generated)",
      "kind": "automatic"
    }
  ],
  "content": {
    "url": "https://api.transcriptlayer.com/v1/transcripts/tr_7QxK2mYb/content",
    "available_formats": [
      "text",
      "json",
      "srt",
      "vtt"
    ],
    "included": "segments",
    "segments": [
      {
        "start_ms": 0,
        "duration_ms": 4300,
        "text": "A committee had twelve weeks to decide"
      },
      {
        "start_ms": 4300,
        "duration_ms": 3900,
        "text": "what a passing civilization should hear."
      }
    ]
  },
  "retrieval": {
    "cache_status": "miss",
    "observed_at": "2026-08-22T09:41:07Z",
    "access_validated_at": "2026-08-22T09:41:07Z",
    "access_validation_age_seconds": 0,
    "cache_age_seconds": 0,
    "stale": false,
    "source_market": "US",
    "content_sha256": "3b1f8c0d94a7e2661bd5a08f7c4e19d2a6f30b5ce8471d92aa0c63e5f7182b4d"
  },
  "usage": {
    "credits_charged": 1
  },
  "created_at": "2026-08-22T09:41:05Z",
  "updated_at": "2026-08-22T09:41:08Z",
  "completed_at": "2026-08-22T09:41:08Z"
}

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "track_id": "yt.cc.es"
}

curl "https://api.transcriptlayer.com/v1/transcripts/tr_7QxK2mYb/content?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPTLAYER_API_KEY" \
  -o episode.srt

HTTP/1.1 200 OK
X-Credits-Charged: 0

{
  "id": "tr_9LmP4nZq",
  "request_id": "req_2hV6bXsw",
  "object": "transcript",
  "status": "failed",
  "source": {
    "platform": "youtube",
    "id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "requested": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language_preferences": [
      "es"
    ],
    "caption_kinds": [
      "manual"
    ],
    "language_fallback": "none",
    "content_format": "segments",
    "allow_stale_on_error": false,
    "include": []
  },
  "usage": {
    "credits_charged": 0
  },
  "error": {
    "code": "track_not_available",
    "detail": "No manual Spanish track is published for this video.",
    "request_id": "req_2hV6bXsw",
    "retryable": false,
    "observed_at": "2026-08-22T09:41:08Z",
    "cache_status": "miss"
  },
  "created_at": "2026-08-22T09:41:05Z",
  "updated_at": "2026-08-22T09:41:08Z",
  "completed_at": "2026-08-22T09:41:08Z"
}

POST /v1/batches
Idempotency-Key: nightly-2026-08-22

{
  "webhook_endpoint_id": "whe_7QxK2mYb",
  "items": [
    {
      "reference": "row-1",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "language_preferences": [
        "en"
      ]
    },
    {
      "reference": "row-2",
      "video_id": "9bZkp7q19f0",
      "platform": "youtube",
      "language_preferences": [
        "ko"
      ],
      "caption_kinds": [
        "manual"
      ]
    }
  ]
}

import { createHmac, timingSafeEqual } from "node:crypto";

const API_VERSION = "2026-08-21";
const MAX_AGE_SECONDS = 300;
const secrets = new Map([
  [process.env.TL_WEBHOOK_KEY_ID, process.env.TL_WEBHOOK_SECRET],
  [process.env.TL_WEBHOOK_PREVIOUS_KEY_ID, process.env.TL_WEBHOOK_PREVIOUS_SECRET],
].filter(([keyId, secret]) => keyId && secret));

async function readBody(request) {
  const declared = Number.parseInt(request.headers.get("content-length") ?? "0", 10);
  if (Number.isFinite(declared) && declared > 16 * 1024) return null;
  const reader = request.body?.getReader();
  if (!reader) return null;
  const chunks = [];
  let total = 0;
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    total += value.byteLength;
    if (total > 16 * 1024) {
      await reader.cancel("webhook body too large");
      return null;
    }
    chunks.push(value);
  }
  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
}

function validSignature(rawBody, headers) {
  const eventId = headers.get("transcriptlayer-event-id") ?? "";
  const timestamp = headers.get("transcriptlayer-timestamp") ?? "";
  const candidates = [
    [headers.get("transcriptlayer-key-id"), headers.get("transcriptlayer-signature")],
    [headers.get("transcriptlayer-previous-key-id"), headers.get("transcriptlayer-previous-signature")],
  ];

  if (!/^evt_[A-Za-z0-9]+$/.test(eventId) || !/^\d{10,12}$/.test(timestamp)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > MAX_AGE_SECONDS) return false;

  return candidates.some(([keyId, supplied]) => {
    const secret = secrets.get(keyId);
    if (!secret || !/^v1=[a-f0-9]{64}$/.test(supplied ?? "")) return false;
    const prefix = Buffer.from(`v1:${timestamp}:${eventId}:${API_VERSION}:${keyId}:`);
    const expected = createHmac("sha256", secret).update(Buffer.concat([prefix, rawBody])).digest();
    const received = Buffer.from(supplied.slice(3), "hex");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

function validTerminalEvent(event) {
  const terminalTypes = [
    "transcript.completed", "transcript.failed", "transcript.cancelled",
    "batch.completed", "batch.cancelled",
  ];
  if (!event || event.object !== "event" || event.api_version !== API_VERSION
    || !terminalTypes.includes(event.type)) return false;
  const [object, status] = event.type.split(".");
  return event.resource?.object === object
    && event.resource.status === status
    && typeof event.resource.id === "string"
    && Number.isInteger(event.resource.version)
    && event.resource.version >= 1
    && typeof event.resource.url === "string";
}

export async function receive(request, enqueueOnce) {
  const rawBody = await readBody(request);
  if (!rawBody) return new Response(null, { status: 413 });
  if (!validSignature(rawBody, request.headers)) return new Response(null, { status: 401 });

  let event;
  try { event = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody)); }
  catch { return new Response(null, { status: 400 }); }
  if (event.id !== request.headers.get("transcriptlayer-event-id")
    || event.object !== "event" || event.api_version !== API_VERSION) {
    return new Response(null, { status: 400 });
  }
  if (event.type === "endpoint.verification") {
    if (!/^whch_[A-Za-z0-9_-]+$/.test(event.challenge ?? "") || !event.endpoint?.id) {
      return new Response(null, { status: 400 });
    }
    return Response.json({ challenge: event.challenge });
  }
  if (!validTerminalEvent(event)) return new Response(null, { status: 400 });

  await enqueueOnce(event.id, event.resource);
  return new Response(null, { status: 204 });
}

{
  "id": "evt_7QxK2mYb",
  "object": "event",
  "api_version": "2026-08-21",
  "type": "transcript.completed",
  "created_at": "2026-08-22T09:41:08Z",
  "resource": {
    "id": "tr_7QxK2mYb",
    "object": "transcript",
    "status": "completed",
    "request_id": "req_5nD8vTca",
    "version": 1,
    "url": "https://api.transcriptlayer.com/v1/transcripts/tr_7QxK2mYb"
  }
}