# TranscriptLab API (transcriptlab.dev)

You are helping a user fetch YouTube transcripts or transcribe media through this HTTP API. Ask what they are building (a script, an n8n or Make workflow, an agent tool) and write that for them. If they have not given you an API key, ask for it. Never invent one.

## Request

    POST https://api.transcriptlab.dev/v1/transcripts
    GET https://api.transcriptlab.dev/v1/transcripts/{VIDEO_ID}

- Submit a YouTube URL or 11-character video ID with POST /v1/transcripts (JSON body, for example {"video_id":"dQw4w9WgXcQ","format":"text"}). A 200 response contains the document; a 202 response carries a Location header, the same GET URL to poll until the transcript is ready.
- GET /v1/transcripts/{VIDEO_ID} reads a variant the account already has. Re-reading a delivered variant is free.
- Authentication on every /v1 route: Authorization: Bearer <ytgw_... key> or X-API-Key: <ytgw_... key>. Keys are created in the dashboard at https://transcriptlab.dev.
- Formats: json, text, srt, vtt. Language, caption type and translation can be selected where supported.
- Caption discovery: GET https://api.transcriptlab.dev/v1/transcripts/{VIDEO_ID}/discover lists the available caption languages and track types.

## Media, batch and channels

    POST https://api.transcriptlab.dev/v1/media

- POST /v1/media accepts a direct https audio or video file url and produces a cached transcript. Page URLs (TikTok, Vimeo, podcast pages) are rejected; host the file at a public https URL instead.
- Speech-to-text is an explicit opt-in (engine=stt for YouTube reads without captions); it is never an automatic fallback. It is metered per audio minute.
- POST /v1/transcripts/batch and POST /v1/channels/transcribe queue jobs of up to 250 videos. Jobs can be inspected, cancelled and followed with webhooks.

## Errors and limits

- 401: the key is missing or not recognised. Ask the user to check it or create a new one.
- A video without captions returns an explicit error result; nothing is transcribed unless the caller opts into speech-to-text.
- Credits are charged when a transcript is delivered, not before. First delivery of a variant costs 1 credit; later deliveries of that variant are free.
- Plans: free account 10 one-time credits; Starter $3.99/month for 1,000 credits (60 requests/min); $4.99 one-time pack for 1,000 credits.
- x402 agent payments: the two transcript read routes accept $0.01 USDC on Base per delivered transcript, no API key. An agent gets a 402 payment challenge, pays, and retries.
- No fixed latency or per-video success guarantee; store transcripts you already fetched instead of requesting them again.

## Examples

cURL:

    curl -X POST -H "Authorization: Bearer $TRANSCRIPTLAB_KEY" \
      -H "Content-Type: application/json" \
      -d '{"video_id":"dQw4w9WgXcQ","format":"text"}' \
      "https://api.transcriptlab.dev/v1/transcripts"

Python:

    import os, requests

    def get_transcript(video_id, fmt="text"):
        r = requests.post(
            "https://api.transcriptlab.dev/v1/transcripts",
            headers={"Authorization": f"Bearer {os.environ['TRANSCRIPTLAB_KEY']}"},
            json={"video_id": video_id, "format": fmt},
            timeout=60,
        )
        if r.status_code == 202:
            poll = r.headers["Location"]
            import time
            for _ in range(30):
                time.sleep(2)
                r = requests.get(poll, headers={"Authorization": f"Bearer {os.environ['TRANSCRIPTLAB_KEY']}"}, timeout=60)
                if r.status_code == 200:
                    break
        r.raise_for_status()
        return r.json()

JavaScript:

    async function getTranscript(videoId, format = "text") {
      const res = await fetch("https://api.transcriptlab.dev/v1/transcripts", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.TRANSCRIPTLAB_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ video_id: videoId, format }),
      })
      if (res.status === 202) {
        const poll = res.headers.get("Location")
        for (let i = 0; i < 30; i++) {
          await new Promise((r) => setTimeout(r, 2000))
          const next = await fetch(poll, { headers: { Authorization: `Bearer ${process.env.TRANSCRIPTLAB_KEY}` } })
          if (next.status === 200) return next.json()
        }
      }
      if (!res.ok) throw new Error(`Transcript request failed: ${res.status}`)
      return res.json()
    }

## Other ways to use it

- In Claude, ChatGPT or any MCP client without code: connect the MCP server at https://api.transcriptlab.dev/mcp. Setup notes for agents: https://transcriptlab.dev/mcp.md
- Full reference, jobs, webhooks and the OpenAPI 3.1 document: https://transcriptlab.dev/docs and https://transcriptlab.dev/docs/swagger
