Have a YouTube link and want readable captions, timestamped notes, or an SRT file? ytapi-youtube-transcript teaches an agent how to retrieve captions through YTAPI. It reads existing creator-uploaded or automatically generated captions; it does not promise audio transcription for arbitrary videos without captions.
Install the standalone caption skill
Prepare a Node.js environment with npm/npx, Claude Code or Codex, and an agent that can run terminal curl requests. In your project terminal:
npx skills add ytapi/youtube-skills --skill ytapi-youtube-transcript
Follow the installer to choose your agent and project scope. Confirm installation, then start a conversation in that project. Installed skill files do not mean the external service is authenticated.
Sign in to the YTAPI dashboard, create your own API key, and make it available as YTAPI_API_KEY through your client's secret configuration or launch environment. Keep the real key out of examples, Git, and shared chat transcripts. Some API documentation uses YT_API_KEY in samples; this standalone skill expects YTAPI_API_KEY. New agent processes must inherit it too.
For a Bash terminal on macOS/Linux, enter bash, then use the following hidden prompt. Start your agent from that same terminal so it inherits the variable. Closing the terminal loses this setting; provide it again next time or use your client's persistent secret configuration.
read -r -s -p "YTAPI key: " YTAPI_API_KEY
printf "\n"
export YTAPI_API_KEY
If you already installed the YTAPI Claude plugin and authenticated with /mcp, use its existing get_transcript tools instead. That MCP login and the standalone skill's API-key setup are separate entry points; you need not configure both.
First task: one video, timestamped reading notes
Choose a public video you can watch that already has captions. Replace the placeholder and enter this example in your agent conversation:
Use ytapi-youtube-transcript for this one video: <YouTube video URL>.
Read basic-info first to confirm its identity and available_languages.
Retrieve the original-language captions as segments and save transcript.json.
Never include the API key in the file or conversation.
Read the whole transcript, then write notes.md with three main points,
each linked to the corresponding moment in the video.
Separate explicit statements from your inferences. Do not infer screen visuals.
If captions are unavailable, report why; do not invent a summary or buy credits.
Confirm the title and video ID before selecting a language and manual or asr track. Read long files in parts. When an MCP result includes another offset, retrieve the remaining pages before describing the notes as covering the entire transcript.
Check video_id, language, and track_kind in the JSON. Sample segments near the beginning, middle, and end: timestamps should be ordered, and the end should not be an accidental truncation. A caption track need not end at exactly the video's duration, for example when an outro has no speech. Open one timestamped note in the video to check its meaning and timing. Review names, numbers, and code terms particularly carefully in automatic captions.
Inspect the request directly
In a terminal where YTAPI_API_KEY is already set, replace VIDEO_ID with the target's 11-character ID. Make sure the output filename will not overwrite a file you need.
curl --fail-with-body --get 'https://api.ytapi.dev/v1/transcripts' --data-urlencode 'video_id=VIDEO_ID' --data-urlencode 'format=segments' --data-urlencode 'languages=*' -H "Authorization: Bearer $YTAPI_API_KEY" -o transcript.json
On failure, the saved body may be an error object, not captions. For a subtitle file, change the format to srt and the output name to transcript.srt. Formats text, markdown, srt, and vtt return the document directly; do not parse them as a JSON wrapper with a text property. Use segments for structured passages with second-based offsets.
Choosing a language is not translating
languages=* selects the original language. en,* tries an existing English track and otherwise falls back to the original; it does not create an English translation. The default manual_first prefers creator captions within the matched language. exact_only needs the precise language code: en does not match en-GB. Inspect available tracks before repeatedly requesting a nonexistent one.
For notes in another language, retrieve the original and translate or summarize it separately. A playable translated subtitle file also needs translation and timing review; retrieving an English SRT does not produce Chinese subtitles.
Credits and troubleshooting
This guide covers skill 1.2.0. Current official documentation lists 200 signup credits, one credit per successful transcript request, and free basic-info requests. Free keys also have a one-request-per-second and 100-request-per-day limit (UTC). Signup credits are not unlimited free service; check the dashboard for current purchasing terms.
- 401: verify the key, the running agent's
YTAPI_API_KEY, and whether you used a different variable name. - 402: the balance is exhausted. Stop and decide yourself whether to buy credits; do not automatically recharge.
- 404 or unavailable captions: check public availability and the requested language. Try the original language when appropriate; missing captions are not a reason to invent a transcript.
- 429: follow
Retry-After. A daily request allowance and a credit balance are separate limits; avoid endless retries. - A file exists but notes are incomplete: check for an error body, a first-page-only result, or an unread second half before summarizing again.
The video address and request go to YTAPI. Respect the creator's rights when reusing captions. The first task above is a documentation-based exercise, not a reported extraction run. For your own local audio without captions, see the Whisper local transcription guide.