youtubewc/에이전트 API
최근 수정 시각: 2026-07-10 22:21:42
에이전트 API는 youtubewc를 사람이 브라우저로 쓰는 UI 대신 프로그램·자동화가 직접 호출하도록 열어 둔 인증된 엔드포인트 모음이다. 앱을 화면으로 클릭하지 않고도 곡을 대량으로 라벨링하고, 라벨을 바탕으로 자연어 플레이리스트를 만들어 넣을 수 있다. 주 소비자는 Claude Code 스킬(ytlabel·ytplaylist)이다.[1]
1. 개요
일반 사용자는 Google 계정으로 로그인해 브라우저에서 앱을 쓰지만, 곡 라벨을 수백 곡 단위로 채우거나 조건 문장으로 플레이리스트를 자동 생성하는 일은 사람이 손으로 하기엔 반복적이다. 에이전트 API는 이런 대량·자동화 작업을 앱 바깥에서 돌리기 위해 존재한다. 외부 자동화는 앱 서버(Cloudflare Worker)의 /api/* 경로에 HTTP로 접근하되, 사람용 로그인 세션 대신 전용 API 키로 자신을 인증한다.
2. 인증
에이전트는 모든 요청에 Authorization 헤더로 Bearer 토큰을 실어 보낸다. 이 토큰은 앱 운영자가 배포 환경에 심어 둔 AGENT_API_KEY 시크릿 값과 정확히 일치해야 한다.
Authorization: Bearer <AGENT_API_KEY>
이는 사람 UI의 인증 방식과 대비된다.
| 구분 | 사람 UI | 에이전트 API |
|---|---|---|
| 인증 수단 | Google OAuth → JWT 세션 쿠키(yt_session) |
Authorization: Bearer <AGENT_API_KEY> 헤더 |
| 신원 | 로그인한 Google 사용자 | 고정된 agent 신원 |
| 얻는 것 | 사용자 YouTube 권한(재생목록 발행 등) | 라벨·플레이리스트 스냅샷·바인딩 데이터 조작 |
AGENT_API_KEY는 선택 시크릿이다. 운영 환경에 키가 설정돼 있지 않으면 에이전트 인증은 항상 실패하고, 아래 에이전트 경로들은 사실상 닫힌다.[2]
3. 제공하는 엔드포인트
에이전트 키로 접근할 수 있는 작업은 크게 곡 라벨링, 글로벌 자연어 플레이리스트, 곡 바인딩 세 갈래다.
3.1. 곡 라벨링 (토너먼트 범위)
특정 월드컵/토너먼트에 담긴 곡들을 대상으로 라벨 현황을 확인하고, 미라벨 곡을 내보내(export) 로컬에서 배치 라벨링한 결과를 다시 올리는(upload) 흐름이다. 이 경로들은 X-Tournament-ID 헤더로 대상 토너먼트를 지정한다.
| 경로 | 용도 |
|---|---|
/api/song-labeling/status |
해당 토너먼트의 라벨 커버리지(전체·라벨됨·미라벨 곡 수, 미리보기) 조회 |
/api/song-labeling/export |
미라벨 곡 목록을 배치 라벨링용 JSON으로 내보내기 |
/api/song-labeling/upload-batch |
로컬에서 만든 라벨 배치를 검증 후 저장(이미 있는 라벨은 건너뜀) |
/api/song-labeling/run |
서버 내 직접 AI 라벨링 — 비활성화(410), export→로컬 배치→업로드 흐름을 쓰도록 유도 |
이 네 경로는 에이전트 키 또는 사람용 JWT 둘 다로 접근할 수 있는 공용 경로다.
3.2. 글로벌 곡 라벨링 (에이전트 전용)
토너먼트가 아니라 앱 전체 ELO 레지스트리에 등록된 모든 곡을 대상으로 라벨을 다루는 경로다. 개별 토너먼트에 묶이지 않으므로 대량 라벨링 자동화에 쓰인다. 이 global-* 경로들은 사람용 JWT 폴백이 없는 에이전트 전용이다.
| 경로 | 용도 |
|---|---|
/api/song-labeling/global-status |
전체 곡 기준 라벨 커버리지 조회 |
/api/song-labeling/global-export |
전체 미라벨 곡을 배치용 JSON으로 내보내기 |
/api/song-labeling/global-upload-batch |
라벨 배치 저장(이미 있는 라벨은 건너뜀) |
/api/song-labeling/global-update-batch |
라벨 배치 저장(기존 라벨을 덮어씀) |
global-upload-batch가 이미 저장된 라벨을 건드리지 않는 반면, global-update-batch는 같은 곡의 라벨을 새 값으로 갱신한다는 점이 다르다.
3.3. 글로벌 자연어 플레이리스트 (에이전트 전용)
라벨이 붙은 전체 곡 풀을 재료로, 자연어 조건에서 플레이리스트를 만들어 스냅샷으로 저장한다. 역시 JWT 폴백이 없는 에이전트 전용 경로다.
| 경로 | 용도 |
|---|---|
/api/natural-playlists/global-generate |
조건 문장(prompt)을 받아 AI가 라벨 기반으로 곡을 골라 플레이리스트 스냅샷 생성·저장 |
/api/natural-playlists/global-save |
에이전트가 이미 고른 제목·곡 목록을 그대로 스냅샷으로 저장(AI 선별 없이) |
global-generate는 전체 곡에 라벨이 모두 채워져 있어야 동작한다. 라벨이 빠진 곡이 있으면 생성이 막히므로, 실무에서는 글로벌 라벨링을 먼저 끝낸 뒤 자연어 생성을 돌린다.
3.4. 곡 바인딩
같은 곡의 여러 영상 버전을 하나로 묶는 바인딩 그룹을 조회·생성·삭제한다. /api/bindings 계열은 에이전트 키 또는 사람용 JWT 둘 다로 접근할 수 있다.
| 경로 | 메서드 | 용도 |
|---|---|---|
/api/bindings |
GET | 바인딩 그룹 전체 목록 |
/api/bindings |
POST | 바인딩 그룹 1개 생성(main + subs) |
/api/bindings/batch |
POST | 여러 바인딩 그룹 일괄 생성 |
/api/bindings/{mainId} |
DELETE | 특정 바인딩 그룹 해제 |
4. 에이전트 전용과 공용의 구분
같은 에이전트 키를 써도 경로마다 성격이 다르다.
- 에이전트 전용 —
song-labeling/global-*,natural-playlists/global-*. 사람용 JWT 폴백이 없어, 유효한 에이전트 키 없이는 아무도 접근할 수 없다. 키가 없거나 틀리면401을 돌려준다. - 공용(에이전트 키 또는 JWT) — 토너먼트 범위 라벨링(
song-labeling/status·export·upload-batch)과 바인딩(/api/bindings*). 에이전트 키가 유효하면 에이전트로 처리하고, 없거나 무효면 사람용 JWT 인증으로 넘어간다.
5. 발행은 사람의 몫
에이전트 API는 플레이리스트를 스냅샷으로 만들고 저장하는 데까지만 관여한다. 그 스냅샷을 실제 YouTube 재생목록으로 발행하는 동작(/api/natural-playlists/publish)은 에이전트 경로가 아니라 사람용 JWT 전용이다. 발행에는 로그인한 사용자의 Google 계정 권한이 필요하기 때문이다.[3] 즉 자동화가 후보 플레이리스트를 잔뜩 만들어 두면, 사람은 라이브러리에서 마음에 드는 것을 골라 발행만 하면 된다.
6. 응답 형식
모든 응답은 JSON이며 success 불리언과 함께 성공 시 data, 실패 시 error, 그리고 사람이 읽을 message·timestamp를 담는다. 라벨 업로드처럼 검증이 필요한 경로는 저장·건너뜀·무효 건수와 항목별 사유를 담은 리포트를 돌려줘, 자동화가 어떤 곡이 왜 반려됐는지 그대로 확인할 수 있다.