YouTube 字幕與搜尋
影片是大多數研究代理無法直接讀取的主要來源。這項技能將任何 YouTube 影片、頻道或搜尋查詢轉換為可引用且帶有時間戳的文字。
所有功能都透過單一 REST API 執行，無需安裝 yt-dlp、無頭瀏覽器或任何二進位執行檔。
設定
API 需要在環境變數中設定金鑰。在 FrontierAgent 的 .env 檔案中加入一行：
echo 'TRANSCRIPT_API_KEY=sk_your_key_here' >> .env
前往 https://transcriptapi.com 取得金鑰。免費方案提供 100 點額度，且無需綁定信用卡。FrontierAgent 在啟動時會載入 .env，而 shell 指令會繼承這些環境變數，因此 $TRANSCRIPT_API_KEY 在下方所有指令中皆可直接使用。
如果該變數為空，請停止操作並告訴使用者新增該變數。請不要猜測金鑰，也不要將該值印給使用者。
每個請求都需要這兩個標頭
Authorization: Bearer $TRANSCRIPT_API_KEY 以及一個真實的 User-Agent。缺少或使用預設的 User-Agent 將會收到 Cloudflare 的 403 錯誤，錯誤代碼為 1010。
取得字幕
每次使用消耗 1 點額度。video_url 接受完整的 YouTube 網址或僅包含 11 個字元的影片 ID。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/transcript" \
--data-urlencode "video_url=$VIDEO" \
--data-urlencode "format=text" \
--data-urlencode "send_metadata=true" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
當你需要每個片段的 start 和 duration 值，例如用來引用時間戳時，請改用 format=json。JSON 的格式為
{"video_id": "...", "language": "en", "transcript": [{"text": "...", "start": 18.0, "duration": 3.5}]}。
搜尋影片或頻道
每次使用消耗 1 點額度。type 可以是 video 或 channel，limit 範圍為 1 到 50。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/search" \
--data-urlencode "q=$QUERY" \
--data-urlencode "type=video" \
--data-urlencode "limit=20" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
解析頻道代號
免費，不消耗額度。接受 @handle、頻道網址或 UC... 的 ID。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/channel/resolve" \
--data-urlencode "input=@TED" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
其他頻道端點可直接接受相同的 channel 值，因此你通常不需要先解析。
輔助腳本
scripts/transcript.sh 包裝了字幕呼叫，並在金鑰缺失時直接報錯。
bash plugins/skills/youtube-transcripts/scripts/transcript.sh "https://www.youtube.com/watch?v=nm1TxQj9IsQ"
當呼叫失敗時
| 狀態碼 | 意義 | 處理方式 |
|---|---|---|
| 401 | 金鑰錯誤或缺失 | 請使用者檢查 .env 中的 TRANSCRIPT_API_KEY |
| 403 | Cloudflare 封鎖了請求 | 你漏掉了 User-Agent 標頭。加上後重試 |
| 404 | 該影片沒有字幕 | 直接告知使用者。不要自行編造字幕 |
| 422 | 影片 ID 或網址格式錯誤 | 重新從使用者的連結中讀取 ID |
| 429 | 額度用盡或達到速率限制 | 回報此狀況。不要進入迴圈重試 |
長字幕可能會超出工具輸出預算。請要求使用 format=text，將內容寫入檔案（例如 > outputs/transcript.txt），然後再讀取你需要的部分。
處理回傳的內容
當原文措辭承載了特定主張時，請直接引用字幕而非改寫。自動產生的字幕可能存在辨識錯誤，因此在基於某個奇怪的技術術語建立論點之前，請將其與影片標題或描述進行比對驗證。