AI 에이전트에게 숏폼 영상 시각 능력 부여하기: Claude 및 Cursor를 위한 Reelyze API + 스킬

대부분의 소셜 분석 도구들은 여러분의 _대시보드 (dashboard)_에 숫자 더미를 던져줄 뿐입니다. 그 어떤 도구도 _AI 에이전트 (AI agent)_가 영상을 직접 보고 왜 성과가 저조했는지 추론하게 해주지는 않습니다. 저는 Claude와 Cursor가 Reel URL을 받아 후크 (hook)의 무엇이 잘못되었는지 말해줄 수 있기를 원했습니다. 그래서 Reelyze의 엔진을 일반 HTTP API로 공개하고, 즉시 사용할 수 있는 에이전트 스킬 (agent skill)로 패키징했습니다.

작동 방식과 여러분의 에이전트에 연결하는 방법은 다음과 같습니다.

API의 기능

공개된 Instagram Reel, TikTok 또는 YouTube Short URL을 제공하면 다음과 같은 작업을 수행할 수 있습니다:

• 분석 (Analyze): 영상을 프레임 단위로 분석합니다. 후크 (hook)의 강도, 초기 3초 유지율 (retention), 장면별 신호, 시청자가 이탈할 것으로 예측되는 정확한 초 단위 시점 등을 파악하여 판결 및 구체적인 수정 사항을 제공합니다.
• 전사 (Transcribe): 음성 오디오를 텍스트로 변환합니다.
• 다운로드 (Download): 깨끗한 MP4 파일을 다운로드하거나, 오디오를 MP3로 **추출 (extract)**합니다.
• 생성 (Generate): 전체 타임스탬프가 포함된 스크립트 (후크 → 본문 → CTA, 캡션, 해시태그, 샷 리스트) 또는 특정 주제로부터 일괄적인 콘텐츠 아이디어를 생성합니다.

전사, 다운로드 및 오디오 도구는 무료이며 사용량이 제한됩니다 (키당 일일 50회 호출 가능). 따라서 API 키만 있으면 이를 활용해 빌드할 수 있습니다. 분석, 스크립트 및 아이디어 생성 기능은 유료 플랜에서 제공됩니다.

인증 (Auth)

Reelyze 대시보드의 API keys 섹션에서 생성한 하나의 Bearer 키 (rk_live_...)를 사용합니다. 기본 URL (Base URL)은 https://api.getreelyze.com입니다. CORS가 개방되어 있어 백엔드, 브라우저 도구 또는 모든 에이전트에서 작동합니다.

export REELYZE_API_KEY=rk_live_xxx
export REELYZE_BASE_URL=https://api.getreelyze.com

비디오 도구는 비동기 방식입니다 (제출 → 폴링)

분석은 즉각적으로 이루어지지 않습니다. 프레임을 가져오고, 화면상의 텍스트를 OCR(광학 문자 인식)하고, 전사하며, 유지율을 점수화하는 과정이 필요하므로, 작업을 제출(submit)한 후 폴링 (poll)을 통해 확인해야 합니다.

# 1) 제출 (Submit)
curl -s -X POST "$REELYZE_BASE_URL/v1/analyze" \
  -H "Authorization: Bearer $REELYZE_API_KEY" \
...

완료된 analyze 작업은 판정(verdict), 후크 평가(hook assessment), 장면별 유지율(scene-by-scene retention), 그리고 이탈 타임스탬프(drop-off timestamps)가 포함된 report_markdown을 반환합니다. Transcript/download/audio 기능 역시 동일한 '제출 후 폴링(submit-then-poll)' 구조를 사용하며, 대신 transcript_text 또는 artifact_url을 읽으면 됩니다.

간단한 Node 폴러(poller):

async function analyze(url) {
  const base = process.env.REELYZE_BASE_URL, key = process.env.REELYZE_API_KEY;
  const h = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
...

콘텐츠 도구는 동기식(synchronous)입니다

/v1/script와 /v1/ideas는 폴링 없이 결과를 직접 반환합니다.

curl -s -X POST "$REELYZE_BASE_URL/v1/script" \
  -H "Authorization: Bearer $REELYZE_API_KEY" -H "Content-Type": "application/json" \
  -d '{"topic":"how I edit reels in 10 minutes","duration_seconds":30,"language":"English"}'
...

에이전트 스킬 (Claude / Cursor)

폴링 루프를 직접 작성하는 대신, 스킬 파일을 넣어주세요. 이는 에이전트에게 엔드포인트(endpoints), 비동기 패턴(async pattern), 그리고 분석 보고서를 읽는 방법을 가르치는 단일 독립형 SKILL.md (MIT-0) 파일입니다. 환경 변수 하나만 설정하면 에이전트가 나머지를 수행합니다:

REELYZE_API_KEY=rk_live_xxx

그 후 에이전트에게 다음과 같이 말하기만 하면 됩니다:

> audit this reel and tell me why it flopped: <url>
→ Verdict: strong concept, buried payoff.
→ Hook: weak - lost ~62% by 0:03.
...

이 기능은 Bearer 키와 개방형 CORS를 사용하는 일반 HTTP 방식이므로, SDK나 별도의 설치 없이 Claude, Cursor, 브라우저 도구 또는 자체 백엔드에서 동일한 스킬을 사용할 수 있습니다.

단순한 API가 아닌 스킬로 제공하는 이유

핵심은 단일 호출이 아니라 '체이닝(chaining, 연결)'에 있습니다. 이 스킬을 가진 에이전트는 전사(transcribe) → 분석(analyze) → 후크 재작성(rewrite the hook) → 다음 스크립트 생성(generate the next script) 과정을 하나의 흐름으로 처리할 수 있습니다. 또는 두 릴(reel)의 후크를 비교하거나, 경쟁사의 성공 사례를 감사(audit)한 뒤 보고서 내용을 바탕으로 자신의 버전을 초안할 수도 있습니다. 분석이 단순히 확인해야 할 탭이 아니라, 워크플로우(workflow)의 한 단계가 되는 것입니다.

직접 시도해보세요

무료 도구(자막(transcript), 다운로더(downloader), 오디오(audio))는 하루 50회까지 어떤 키로든 사용할 수 있으며, 첫 번째 전체 분석은 무료입니다 - getreelyze.com. 대시보드에서 키를 가져오거나 https://github.com/usamalatif/reelyze-skill에서 스킬(skill) 파일을 가져오세요.

만약 크리에이터용 도구(creator tooling)를 제작 중이시라면, 다음 두 가지 사항에 대해 진심 어린 피드백을 받고 싶습니다. 이탈 시점(drop-off timestamp)이 귀하의 자체 유지율 그래프(retention graphs)에서 보이는 것과 일치하는지, 그리고 귀하의 에이전트(agent) 내부에서 API를 더 유용하게 만들기 위해 무엇이 필요한지입니다. 여기에 답글을 남기거나 저(Usama)를 찾아주세요.