How to get a YouTube transcript in Python

Send the request from your server

Keep the API key in an environment variable. The public endpoint accepts a YouTube URL or the normalized 11-character video ID.

Python

import os
import requests

BASE_URL = "https://capslane.com"
API_KEY = os.environ["CAPSLANE_API_KEY"]

response = requests.get(
    f"{BASE_URL}/v1/transcript",
    headers={"x-api-key": API_KEY},
    params={"url": "dQw4w9WgXcQ", "mode": "auto"},
    timeout=20,
)
response.raise_for_status()
result = response.json()

A native or cached transcript returns HTTP 200. A video that requires generation can return HTTP 202 with a durable job ID.

Poll generated jobs

Use the same key for the job endpoint. Polling does not reserve another monthly request unit. Stop on a terminal status and apply an application-level deadline.

Python

import time

while response.status_code == 202:
    job_id = result["jobId"]
    time.sleep(2)
    response = requests.get(
        f"{BASE_URL}/v1/transcript/{job_id}",
        headers={"x-api-key": API_KEY},
        timeout=20,
    )
    response.raise_for_status()
    result = response.json()
    if result["status"] in {"completed", "failed", "cancelled"}:
        break

Read text or timestamped segments

By default, content is an array of segments with text, offset, duration and lang. Add text=true when one normalized string is enough.

Handle errors by code

Do not retry every non-200 response. Retry bounded network and upstream failures with backoff. Stop on invalid input, an invalid key, a disabled tenant or a monthly limit. Preserve requestId for workspace logs and support.