YouTube 자막 및 검색은(는) 무엇을 하나요?

비디오는 대부분의 연구 에이전트가 읽을 수 없는 주요 소스입니다. 이 스킬은 YouTube 동영상, 채널 또는 검색어를 타임스탬프와 함께 인용할 수 있는 텍스트로 변환합니다.

모든 것은 하나의 REST API를 통해 실행됩니다. yt-dlp, 헤드리스 브라우저, 설치할 바이너리가 없습니다.

설정

API는 환경 변수에 키가 필요합니다. FrontierAgent의 .env에 한 줄을 추가하세요:

echo 'TRANSCRIPT_API_KEY=sk_your_key_here' >> .env

키는 https://transcriptapi.com 에서 받으세요. 무료 티어는 100크레딧을 제공하며 신용카드가 필요 없습니다. FrontierAgent는 시작 시 .env를 로드하고 셸 명령어가 이를 상속하므로 $TRANSCRIPT_API_KEY가 아래 모든 명령어 내에서 해결됩니다.

변수가 비어 있으면 사용자에게 추가하라고 지시하고 중단하세요. 키를 추측하지 말고 값을 사용자에게 출력하지 마세요.

모든 요청에는 두 가지 헤더가 필요합니다

Authorization: Bearer $TRANSCRIPT_API_KEY와 실제 User-Agent. 누락되었거나 기본 User-Agent는 Cloudflare 403, 오류 코드 1010으로 응답됩니다.

자막 가져오기

1크레딧. video_url은 전체 YouTube URL 또는 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"

채널 핸들 조회

무료, 크레딧 사용 없음. @핸들, 채널 URL 또는 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 또는 URL 형식이 잘못됨	사용자의 링크에서 ID를 다시 읽어보세요
429	크레딧 부족 또는 속도 제한	알리세요. 반복해서 재시도하지 마세요

긴 자막은 도구 출력 예산을 초과할 수 있습니다. format=text를 요청하고 본문을 > outputs/transcript.txt로 파일에 쓴 다음 필요한 부분을 읽으세요.

반환 데이터 활용하기

정확한 표현이 주장을 담고 있을 때는 의역보다 자막을 인용하세요. 자동 자막에는 인식 오류가 있을 수 있으므로, 특이한 기술 용어는 의심하고 동영상 제목이나 설명과 대조한 후에 주장의 근거로 삼으세요.

YouTube 자막 및 검색