YouTube Transcript API Skill

intent

extract transcripts from youtube videos using the youtubetranscript.dev v2 api. handles native captions, asr transcription for videos without captions, translation to 100+ languages, and batch processing of up to 100 videos in a single request. use this skill when you need to convert video content to text, build llm pipelines with youtube data, or repurpose videos into written formats.

inputs

• api_key (required): bearer token for youtubetranscript.dev. get a free key at youtubetranscript.dev. store as env var YOUTUBE_TRANSCRIPT_API_KEY or pass directly.
• video_id or url (required): either an 11-character youtube video id (e.g., dQw4w9WgXcQ) or full youtube url (e.g., https://www.youtube.com/watch?v=dQw4w9WgXcQ).
• language (optional): iso 639-1 code for translation (e.g., es, fr, de). omit to skip translation and save credits.
• source (optional): one of auto (default), manual (native captions only), or asr (audio transcription). asr requires webhook_url.
• format (optional): output structure. one of timestamp (default, includes timecodes), paragraphs (grouped sentences), or words (individual word tokens).
• webhook_url (optional but required for asr): url where the api will post results when asr transcription completes. polling /api/v2/jobs/{job_id} works as fallback.
• video_ids array (for batch): up to 100 youtube ids or urls in a single array for batch processing.

external connection: https://youtubetranscript.dev/api/v2

procedure

1. validate and store api key

   • input: api_key (string)
   • check that api_key is not empty and matches expected bearer token format
   • output: api_key confirmed or error thrown

2. normalize video input

   • input: video_id or url (string)
   • if url, extract 11-character id using regex pattern (?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]{11})
   • if already 11 chars alphanumeric + underscore + hyphen, accept as-is
   • output: normalized video_id (string)

3. choose endpoint based on input count

   • input: video_id or video_ids array
   • if single video_id, proceed to step 4
   • if video_ids array with 1-100 items, proceed to step 5
   • if video_ids array with more than 100 items, throw error and suggest splitting into multiple requests
   • output: endpoint selection (single or batch)

4. single video transcription request

   • input: api_key, video_id, language (optional), source (optional), format (optional)
   • construct post request to https://youtubetranscript.dev/api/v2/transcribe
   • set headers: Authorization: Bearer {api_key}, Content-Type: application/json
   • set body: {video: video_id, language: language, source: source, format: format} (omit optional fields if not provided)
   • if source is asr, require webhook_url in body or set polling mode
   • send request and capture response
   • output: http response object with status code and json body

5. batch video transcription request

   • input: api_key, video_ids array (1-100), language (optional), source (optional), format (optional)
   • construct post request to https://youtubetranscript.dev/api/v2/batch
   • set headers: Authorization: Bearer {api_key}, Content-Type: application/json
   • set body: {video_ids: video_ids, language: language, source: source, format: format} (omit optional fields if not provided)
   • send request and capture response with batch_id
   • output: http response object with status code, batch_id, and json body

6. handle synchronous response (caption-based or manual)

   • input: http response from step 4 or 5
   • if response status is 200 and response.data.transcript exists, proceed to step 8
   • if response status is 202 (async job), proceed to step 7
   • if response status is not 200/202, proceed to step 9 (error handling)
   • output: transcript data or job_id

7. poll async job status (asr or batch)

   • input: job_id or batch_id from response, api_key
   • construct get request to https://youtubetranscript.dev/api/v2/jobs/{job_id} or /api/v2/batch/{batch_id}
   • set headers: Authorization: Bearer {api_key}
   • send request every 5 seconds (exponential backoff: 5s, 10s, 15s, max 30s between polls)
   • stop polling after 1 hour (3600 seconds) and timeout
   • if status is completed, extract transcript data and proceed to step 8
   • if status is processing, repeat polling
   • if status is failed, proceed to step 9 (error handling)
   • output: transcript data or timeout error

8. format and validate transcript output

   • input: transcript data array (segments with start time, duration, text fields)
   • validate that data.transcript is an array and not empty
   • if format is timestamp, keep segments as-is with start/duration fields
   • if format is paragraphs, group consecutive segments into logical paragraphs (join when gap < 2 seconds)
   • if format is words, flatten all text into individual word tokens with timing
   • output: formatted transcript array and metadata (video_id, language, source, total_duration, segment_count)

9. error handling and fallback

   • input: http response with non-200/202 status or error body
   • check status codes and error codes (see decision points)
   • output: structured error object with code, message, and remediation hint

decision points

• if http 401 (invalid_api_key): api_key is missing, malformed, or expired. ask user to verify key at youtubetranscript.dev or generate a new free key. do not retry.

• if http 402 (payment_required): account is out of credits. check remaining balance at account dashboard. for free tier, users must wait for daily reset or upgrade. do not retry immediately.

• if http 404 (no_captions): video has no native captions and asr was not requested. ask user if they want asr transcription (slower, async, requires webhook) or if they want to try a different video.

• if http 429 (rate_limit_exceeded): too many requests sent. check Retry-After response header for wait time (typically 60-300 seconds). implement exponential backoff and retry up to 3 times. after 3 retries, fail with "rate limit exceeded, please try again later".

• if http 400 (invalid_request): request json is malformed or missing required fields. check that video_id is 11 chars, video_ids array has 1-100 items, language is iso 639-1 (2 chars), source is one of auto/manual/asr. do not retry; fix input and resubmit.

• if network timeout or connection refused: youtubetranscript.dev api is unreachable. retry up to 3 times with 10-second delay. if still failing after 3 retries, report "api service unavailable" and suggest user check status at youtubetranscript.dev.

• if transcript array is empty: video exists but has no transcript in requested language. try omitting language parameter (use default/best available) or try source: auto to allow fallback to asr. do not report as error.

• if asr job polling times out after 1 hour: long videos or high server load may exceed expected 2-20 minute window. inform user that job is still processing and provide job_id for manual polling later. do not retry automatically.

• if source is asr but webhook_url is missing and polling is not available: require one of webhook_url or explicit polling mode. if neither provided, default to polling mode with 5-second intervals.

output contract

single video success response (http 200):

{
  "success": true,
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
    "transcript": [
      {
        "start": 0,
        "duration": 2.5,
        "text": "We're no strangers to love"
      },
      {
        "start": 2.5,
        "duration": 3.1,
        "text": "You know the rules and so do I"
      }
    ],
    "language": "en",
    "source": "manual",
    "total_duration": 213.5,
    "segment_count": 45
  }
}

batch request response (http 200 or 202):

{
  "success": true,
  "batch_id": "batch_xyz789",
  "status": "processing",
  "data": [
    {
      "video_id": "dQw4w9WgXcQ",
      "status": "completed",
      "transcript": [...]
    },
    {
      "video_id": "jNQXAC9IVRw",
      "status": "processing",
      "transcript": null
    }
  ]
}

asr job status response (http 200):

{
  "success": true,
  "job_id": "job_abc123",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "transcript": [...],
    "source": "asr",
    "confidence": 0.92
  }
}

error response (http 4xx/5xx):

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests",
    "retry_after": 120
  }
}

all output saved to variable or file as json. if batch processing, results are in array within data field. timestamps are in seconds (float).

outcome signal

• visual confirmation: transcript text is printed or displayed in application. timestamps are readable and match video timeline.
• successful extraction: api returns http 200 and transcript array contains at least one segment with text field populated.
• batch completion: all videos in batch_id show status: completed in polling response and transcript data is present.
• translation applied: returned language field matches requested language code and text is in that language (spot-check sentences).
• asr transcription done: for videos without captions, source field returns asr (not manual) and webhook receives POST or polling confirms status: completed.
• credit deduction: user account at youtubetranscript.dev shows reduced balance after successful request (1 credit for captions, 1 per 2500 chars for translation, 1 per 90 seconds for asr).