---
name: rainbow-prism-youtube
description: 한국·글로벌 유튜브 "떡상"(구독자 대비 조회수 폭발) 영상을 국가·니치·쇼츠 기준으로 발굴하고, 영상·채널 통계와 성장 추이, 쇼츠 트렌드(카테고리 모멘텀·KR↔US 선행지표)를 조회한다. 한국 콘텐츠·한국어 니치에 강함. 저평가/급상승 유튜브를 찾거나 영상·채널 성장 지표가 필요할 때 사용.
---

# Rainbow Prism API — 한국 유튜브 떡상 발굴·통계 (v1)

생성형 AI(ChatGPT·Claude·Cursor 등)에서 "구독자 대비 조회수가 폭발한(떡상) 유튜브 영상"을 발굴하고 통계를 조회하는 API. 한국 시장·한국어 니치 데이터와 KR↔US 선행지표가 강점입니다.

## 인증
- 모든 v1 요청에 헤더: `Authorization: Bearer <YOUR_API_KEY>`
- API 키는 Rainbow Prism → 설정 → API 에서 발급 (Expert 구독 필요).
- 레이트리밋(키별): 분당 120회, 일 5000회.

## Base URL
`https://prism.ai-teammate.net`

## Endpoints

### GET /api/v1/me
키 검증 + 플랜 + 잔여 레이트리밋(읽기전용, 쿼터 미소비). 본격 호출 전 키가 유효한지 먼저 확인하세요.
응답: `{ keyId, plan: "expert"|"pro"|"free", pro, apiAccess, rateLimit: { perMinute: { limit, used, remaining }, perDay: { limit, used, remaining } } }`

### GET /api/v1/youtube/finder
떡상 후보 영상 발굴(구독자 대비 조회수·급상승 순).
- `q` 색인 키워드 검색(제목·채널·주제, 부분일치·띄어쓰기 변형 지원) — 쿼터 0. 있으면 관련성순 기본(`sort` 지정 시 그 정렬)
- `country` 지역코드 (KR, US, JP, GB …)
- `category` 카테고리명
- `shorts` `true`(쇼츠) | `false`(롱폼)
- `within` 최근 N일 (기본 365, 0=전체)
- `maxSubs` 최대 구독자 수
- `minSubs` 최소 구독자 수
- `minDuration` 길이 하한(초) — 180=3분+, 480=8분+ 롱폼만 (쇼츠 제외엔 `shorts=false`와 병행)
- `maxDuration` 길이 상한(초) — `minDuration`과 함께 범위 질의(예: 180~480 = 3~8분)
- `minViews` 절대 조회수 하한 — `vps`만 높고 조회수 극소인 저품질/리업로드성 차단
- `excludeShortsTag` `1` — 제목에 #shorts/#short 태그가 든 영상 제외(롱폼 엄선)
- `sort` `vps`(구독대비·기본) | `velocity`(급상승) | `views` | `likes`(좋아요순) | `subs` | `recent`
- `limit` 1~50 (기본 20)
응답: `{ videos: [{ videoId, url, title, channelTitle, viewCount, viewsPerSub, subscribers, dailyVelocity, velocityTrend, hookScore, region, category, summaryKo, strategyKo }], count }`

### GET /api/v1/youtube/video/{videoId}
단일 영상 통계 + 조회수 시계열(최대 90일).
응답: `{ videoId, url, title, viewCount, likeCount, commentCount, subscribers, viewsPerSub, summaryKo, strategyKo, timeseries: [{ date, views, likes, comments }] }`

### GET /api/v1/youtube/channel/{channelId}
추적 채널 상세 + 구독자/조회수 성장 추이(최대 90일). 추적되지 않은 채널은 404.
응답: `{ channelId, url, title, handle, country, category, subscribers, growth: [{ date, subscribers, views, videos }] }`

### GET /api/v1/youtube/trends
쇼츠 트렌드 종합: 카테고리 모멘텀·급상승 쇼츠·급상승 키워드·후킹 포맷·KR↔US 선행지표.
- `region` 2자리 국가코드 (기본 ALL)
- `days` 모멘텀 구간 일수 3~90 (기본 14)
응답: `{ region, days, categories: [{ category, count, avgVps, momentum, trend }], rising: [<finder 영상 객체>], keywords: [{ topic, count, avgVps }], formats: [{ format, count, avgVps }], leading: [{ category, krVps, usVps, ratio }] }`

### GET /api/v1/youtube/cadence
업로드 전략(떡상 케이던스): "이 카테고리·국가의 쇼츠는 얼마나 자주 올리는 채널이 떡상하나"를 채널 발행간격으로 분석. 케이던스 버킷별 평균 떡상비율(viewsPerSub)·떡상률, 권장 업로드 빈도, 업로드 요일/시간대(KST·성과 가중), 영상 길이 최적값.
- `country` 지역코드 (KR, US … / 생략·ALL=국가 무관)
- `category` 카테고리명 (쇼핑, 라이프, 뷰티 … / 생략=전체)
- `shorts` `true`(기본·쇼츠) | `false`(롱폼)
- `within` 최근 N일 (기본 180, 0=전체)
- `source` `all`(기본·전체 색인) | `tracked`(추적 채널만 — 표본 완전성↑·케이던스 정확도↑)
응답: `{ country, category, shorts, within, source, sampleChannels, sampleVideos, confidence: { level: "low"|"medium"|"high", label }, cadence: [{ bucket, label, channels, videos, avgVps, breakoutRate, avgDurationSec, maxVps }], recommended: { bucket, label, avgVps, breakoutRate }, duration: [{ bucket, label, videos, avgVps }], timing: { byWeekday, byHour, byWeekdayViews, byHourViews, medianViews, sampleSize } }`
주의: 색인은 전수가 아닌 표본(추적·발굴분)이라 케이던스는 방향성/하한. `confidence.level`로 표본 신뢰도를 함께 표시(low=참고용·high=신뢰도 높음). `source=tracked`가 더 정확.

### GET /api/v1/youtube/search
자유 쿼리 장르/취향 검색(예: "재즈 라이브", "바이올린 연주") — finder(색인된 떡상)와 달리 YouTube 실시간 검색이라 쿼터를 소모합니다. 키당 하루 50회 한도.
- `q` 검색어(필수, 한국어 가능)
- `country` regionCode (KR, US … 생략 가능)
- `order` `viewCount`(인기·기본) | `rating`(평점) | `date`(최신) | `relevance`
- `minDuration` 길이 하한(초)
- `limit` 1~50 (기본 20)
응답: `{ videos: […], count, source: "live"|"local", note?, query }` — 쿼터 소진 시 502 대신 수집분(색인) 검색으로 폴백(`source:"local"` + `note` 표기)

### GET /api/v1/youtube/transcript/{videoId}
단일 영상 자막(구조 분석용). `lang` 언어 지정(기본 ko). Expert 키 일 30건 한도. 자막 없으면 에러가 아니라 `{ available: false }`.
응답: `{ videoId, available, lang?, text?, title?, source? }`

### 개인 리포트 보관함(Expert·비공개)
- `POST /api/v1/me/reports` {type,title,subject,markdown} — 저장(계정당 100·200KB). `GET /api/v1/me/reports` 목록(메타). `GET/DELETE /api/v1/me/reports/{id}`.
- prism-report 스킬이 사용. (MCP `my_reports`=목록만, 저장/삭제는 REST.)

## 예시
    curl -H "Authorization: Bearer rp_live_..." \
      "https://prism.ai-teammate.net/api/v1/youtube/finder?country=KR&shorts=true&sort=vps&limit=10"

## 커넥터(function calling)
OpenAPI 스펙: `https://prism.ai-teammate.net/api/v1/openapi.json` — ChatGPT GPTs/Claude 웹 커넥터에 그대로 등록하면 위 기능을 도구로 호출할 수 있습니다.
MCP(Claude Code·Desktop·Cursor): `https://prism.ai-teammate.net/api/v1/mcp` (Streamable HTTP) — `claude mcp add --transport http rainbowprism https://prism.ai-teammate.net/api/v1/mcp --header "Authorization: Bearer rp_live_..."`. 떡상 발굴·트렌드·케이던스·코호트가 도구로 노출됩니다(읽기 전용·Expert).

## 창작 스튜디오(로컬 스킬)
`prism-story` — 급상승 신호 + (선택)자막 구조로 테마별 쇼츠·롱폼 대본을 뽑는 Claude Code 스킬. 위 데이터 툴을 소비합니다.
`prism-report` — 채널·니치·트렌드 데이터로 심층 분석 리포트(채널 딥다이브·니치 트렌드·떡상 포스트모템·경쟁 비교)를 만들고, 개인 비공개 보관함(`my_reports`)에 저장하는 Claude Code 스킬.
설치: `git clone https://github.com/mobiolabs25-ops/prism-creator-skills && cd prism-creator-skills && ./install.sh` (→ ~/.claude/skills/). MCP는 데이터 툴만 제공 — 위 두 스킬은 별도 설치합니다.