변경 이력

버전날짜변경 사항
v1.4 2026-04-22
  • Insight API 신규 — 외부 LLM/MCP 연동을 위한 읽기 전용 API 11개 엔드포인트 (/api/insights/*)
  • MCP Server — FastMCP 기반 SSE 서버 (포트 8004), 12개 tool 제공. Claude Code 등 MCP 클라이언트에서 직접 분석 데이터 조회
  • GET /api/insights/summary — 전체 통계 (수집/분석 건수)
  • GET /api/insights/posts — 수집 포스트 검색 (platform/keyword/search)
  • GET /api/insights/reels-ranking — 릴스 참여도 랭킹 (grade 필터)
  • GET /api/insights/threads-ranking — 스레드 참여도 랭킹
  • GET /api/insights/carousel-ranking — 캐러셀 통합 랭킹
  • GET /api/insights/reel-analyses — 릴스 AI 분석 결과 (topic/category/grade 필터)
  • GET /api/insights/image-analyses — 이미지 AI 분석 결과
  • GET /api/insights/carousel-analyses — 캐러셀 AI 분석 결과
  • GET /api/insights/categories — 분석 카테고리 목록
  • GET /api/insights/hashtag-stats — 해시태그 성과 통계
  • GET /api/insights/content-filter-history — 콘텐츠 필터 이력
v1.3 2026-04-20
  • 캐러셀 전용 분석 시스템 — 기존 이미지 분석에서 캐러셀(Carousel/Sidecar)을 분리, 5개 영역 심층 분석 (슬라이드별 OCR, 서사 구조, 훅, 디자인, 종합)
  • POST /api/actions/analyze-carousels — 신규. 캐러셀 게시물 Claude Vision 분석 시작
  • GET /api/actions/analyze-carousels-status — 신규. 캐러셀 분석 진행 상태 폴링
  • GET /api/data/carousel-ranking — 신규. IG+Threads 통합 캐러셀 랭킹 (virality 50% + recency 50%, 5분 캐시)
  • GET /api/data/carousel-detail/{post_id} — 신규. 개별 캐러셀 media_url/text 조회
  • GET /api/data/carousel-analyses — 신규. 캐러셀 분석 결과 목록 조회
  • GET /api/data/carousel-analysis/{post_db_id} — 신규. 개별 캐러셀 분석 상세 조회
  • DELETE /api/data/carousel-analyses — 신규. 캐러셀 분석 결과 삭제
  • 이미지 분석기post_type 필터에 carousel/sidecar 제외 처리 (캐러셀 전용 분석기로 이관)
  • DBcarousel_analyses 테이블 신규 생성
v1.2 2026-04-13
  • GET /api/external/pending — 응답에 video_duration, scene_count, cuts_per_second, frame_paths 필드 추가. 캡처 시 프레임 자동 추출 + 비디오 메타데이터 포함
  • POST /api/actions/backfill-frames — 신규. 기존 캡처 완료 영상 중 프레임 미추출 건을 일괄 처리
  • GET /api/actions/backfill-frames-status — 신규. 프레임 백필 작업 진행 상황 폴링
v1.1 2026-04-12
  • GET /api/external/pending — 응답에 transcript 필드 추가. 서버 Whisper 전사 결과가 있으면 포함되므로 외부에서 별도 STT 불필요
  • POST /api/actions/backfill-transcripts — 신규. 기존 캡처 완료 영상 중 전사 미수행 건을 일괄 처리
  • GET /api/actions/backfill-transcripts-status — 신규. 백필 작업 진행 상황 폴링
v1.0 2026-03-20 최초 릴리즈 — External pending/analysis API, 이미지·릴스 분석 파이프라인, 빠른 테스트 UI

데이터 흐름

1
GET /api/external/pending 미분석 포스트 목록 조회 (transcript + 프레임 + 비디오 메타 포함)
2
GET /captures/{path} 미디어 파일 다운로드 (기존 StaticFiles)
3
로컬 분석 수행 자체 모델로 이미지/영상 분석
4
POST /api/external/analysis/{id} 분석 결과 DB 저장

인증

모든 /api/external/* 엔드포인트는 X-Api-Key 헤더로 인증합니다.

헤더비고
X-Api-Key EXTERNAL_API_KEY 환경변수 값 환경변수 미설정 시 인증 스킵 (개발 모드)
Example
curl -H "X-Api-Key: your-secret-key" https://threads.pyrocnc.co.kr/api/external/pending

GET /api/external/pending

캡처 완료(capture_status='done') 상태이면서 아직 분석되지 않은 포스트 목록을 반환합니다.

Query Parameters

파라미터타입기본값설명
platformstring?nullinstagram 또는 threads. 미지정 시 양쪽 모두 조회
analysis_typestringreelreel 또는 image. 어떤 분석 기준으로 미분석을 판별할지
limitint200최대 반환 수 (1~1000)

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": 42,
      "platform": "instagram",
      "post_id": "Cxyz123abc",
      "author": "user_handle",
      "text": "게시물 텍스트 (최대 200자)...",
      "post_type": "Reels",
      "screenshot_paths": "instagram/user_handle/screenshot_1.jpg",
      "video_path": "instagram/user_handle/video.mp4",
      "media_url": "https://...",
      "likes": 1234,
      "comments": 56,
      "views": 78900,
      "posted_at": "2025-03-15T12:00:00",
      "captured_at": "2025-03-16T03:22:10",
      "transcript": "[0.0s-2.5s] 오늘 소개할 레시피는...\n[2.5s-5.0s] 재료를 준비해주세요",
      "video_duration": 28.5,
      "scene_count": 7,
      "cuts_per_second": 0.25,
      "frame_paths": [
        "instagram/Cxyz123abc/frames/frame_000.0s.jpg",
        "instagram/Cxyz123abc/frames/frame_002.0s.jpg",
        "instagram/Cxyz123abc/frames/frame_004.0s.jpg"
      ]
    }
  ],
  "message": "15 pending posts"
}

Response 필드

필드타입설명
idintDB 기본키 (분석 업로드 시 path parameter로 사용)
platformstringinstagram 또는 threads
post_idstring외부 포스트 ID (분석 업로드 시 post_ext_id로 교차 검증)
authorstring게시물 작성자 핸들
textstring게시물 텍스트 (최대 200자)
post_typestring?게시물 유형 (Reels, Post, Carousel 등)
screenshot_pathsstring?스크린샷 경로 (JSON 배열 문자열)
video_pathstring?영상 파일 경로
media_urlstring?원본 미디어 URL
likesint좋아요 수
commentsint댓글 수
viewsint조회수
posted_atstring?게시 시각 (ISO 8601)
captured_atstring?캡처 완료 시각 (ISO 8601)
transcript string? [v1.1] 서버 Whisper STT 전사 결과. 타임스탬프 형식 [0.0s-2.5s] 텍스트. 전사 미수행 시 null. 있으면 외부 분석기에서 별도 STT 불필요
video_duration float? [v1.2] 영상 길이(초). ffprobe로 추출. 이미지 포스트는 null
scene_count int? [v1.2] 씬 전환 횟수 (ffmpeg scene=0.3 기준). 이미지 포스트는 null
cuts_per_second float? [v1.2] 초당 컷 수 (scene_count / video_duration). 영상 페이스 지표
frame_paths string[]? [v1.2] 타임스탬프 프레임 경로 배열. 파일명 형식 frame_002.0s.jpg. GET /captures/{path}로 다운로드. 프레임 미추출 시 null. 0.5fps, 384px, 최대 30장

cURL 예시

Bash
# 릴스 미분석 포스트 (Instagram만)
curl "https://threads.pyrocnc.co.kr/api/external/pending?platform=instagram&analysis_type=reel&limit=50"

# 이미지 미분석 포스트 (전체)
curl "https://threads.pyrocnc.co.kr/api/external/pending?analysis_type=image"

GET /captures/{path}

캡처된 스크린샷/영상 파일을 다운로드합니다. 기존 StaticFiles 마운트를 그대로 사용합니다.

pending 응답의 screenshot_paths 또는 video_path 값을 경로로 사용합니다.

cURL 예시

Bash
# 스크린샷 다운로드
curl -O "https://threads.pyrocnc.co.kr/captures/instagram/user_handle/screenshot_1.jpg"

# 영상 다운로드
curl -O "https://threads.pyrocnc.co.kr/captures/instagram/user_handle/video.mp4"

POST /api/actions/backfill-transcripts v1.1

캡처 완료된 영상 중 transcript가 없는 건을 일괄 Whisper 전사합니다. 비동기 실행되며 상태는 별도 엔드포인트에서 폴링합니다.

Query Parameters

파라미터타입기본값설명
platformstringinstagraminstagram 또는 threads

Response

200 OK
{
  "success": true,
  "data": null,
  "message": "스크립트 백필이 시작되었습니다"
}

cURL 예시

Bash
curl -X POST "https://threads.pyrocnc.co.kr/api/actions/backfill-transcripts?platform=instagram"

GET /api/actions/backfill-transcripts-status v1.1

백필 작업의 진행 상황을 조회합니다. 프론트엔드에서 2초 간격으로 폴링합니다.

Response

200 OK
{
  "success": true,
  "data": {
    "running": true,
    "total": 45,
    "done": 12,
    "current_post_id": 1234,
    "errors": []
  },
  "message": ""
}

Response 필드

필드타입설명
runningbool현재 실행 중 여부
totalint전사 대상 총 건수
doneint완료된 건수
current_post_idint?현재 처리 중인 포스트 DB ID
errorsstring[]오류 메시지 목록

POST /api/actions/backfill-frames v1.2

캡처 완료된 영상 중 프레임이 추출되지 않은 건을 일괄 처리합니다. 0.5fps로 384px JPEG 프레임을 추출하고 비디오 메타데이터(duration, scene_count, cuts_per_second)도 함께 저장합니다.

Query Parameters

파라미터타입기본값설명
platformstringinstagraminstagram 또는 threads

Response

200 OK
{
  "success": true,
  "data": null,
  "message": "프레임 백필이 시작되었습니다"
}

cURL 예시

Bash
curl -X POST "https://threads.pyrocnc.co.kr/api/actions/backfill-frames?platform=instagram"

GET /api/actions/backfill-frames-status v1.2

프레임 백필 작업의 진행 상황을 조회합니다. 프론트엔드에서 2초 간격으로 폴링합니다.

Response

200 OK
{
  "success": true,
  "data": {
    "running": true,
    "total": 30,
    "done": 8,
    "current_post_id": 567,
    "errors": []
  },
  "message": ""
}

Response 필드

필드타입설명
runningbool현재 실행 중 여부
totalint프레임 추출 대상 총 건수
doneint완료된 건수
current_post_idint?현재 처리 중인 포스트 DB ID
errorsstring[]오류 메시지 목록

POST /api/external/analysis/{post_db_id}

분석 결과를 DB에 저장합니다. post_db_idpending 응답의 id 필드입니다.

Path Parameters

파라미터타입설명
post_db_idintDB 기본키 (pending 응답의 id)

Request Body

필드타입필수설명
analysis_typestringY"reel" 또는 "image"
reelobject조건부analysis_type="reel" 시 필수
imageobject조건부analysis_type="image" 시 필수

reel 객체 필드

필드타입필수설명
post_ext_idstringY외부 포스트 ID (pending의 post_id와 일치해야 함)
captionstring?캡션 텍스트
transcriptstring?음성 트랜스크립트
duration_secondsfloat?영상 길이 (초)
scene_countint장면 수 (기본 0)
cuts_per_secondfloat초당 컷 수 (기본 0.0)
hook_analysisstring?훅 분석 결과
structure_analysisstring?구조 분석 결과
visual_pace_analysisstring?시각적 페이스 분석
audio_trend_analysisstring?오디오 트렌드 분석
cta_analysisstring?CTA 분석 결과
category_analysisstring?카테고리 분석 (JSON 문자열)
overall_scorefloat?종합 점수 (0~10)
overall_summarystring?종합 요약
raw_ai_responsestring?원본 AI 응답 전문

image 객체 필드

필드타입필수설명
post_ext_idstringY외부 포스트 ID (pending의 post_id와 일치해야 함)
platformstring플랫폼 (기본 "instagram")
captionstring?캡션 텍스트
image_countint이미지 수 (기본 0)
content_summarystring?콘텐츠 요약
extracted_textstring?이미지에서 추출한 텍스트
visual_compositionstring?시각적 구성 분석
category_analysisstring?카테고리 분석 (JSON 문자열)
overall_scorefloat?종합 점수 (0~10)
overall_summarystring?종합 요약
raw_ai_responsestring?원본 AI 응답 전문

Response

200 OK
{
  "success": true,
  "data": { "post_db_id": 42, "analysis_type": "image" },
  "message": "Analysis saved successfully"
}

에러 응답

코드상황예시
401API 키 불일치{"detail": "Invalid or missing API key"}
404post_db_id가 DB에 없음{"detail": "Post with id=999 not found"}
400post_ext_id 불일치{"detail": "post_ext_id mismatch: sent 'abc', DB has 'xyz'"}
422필수 필드 누락 / 잘못된 analysis_type{"detail": "reel field is required when analysis_type='reel'"}

cURL 예시

릴스 분석 업로드
curl -X POST "https://threads.pyrocnc.co.kr/api/external/analysis/42" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-secret-key" \
  -d '{
    "analysis_type": "reel",
    "reel": {
      "post_ext_id": "Cxyz123abc",
      "hook_analysis": "첫 1초에 강렬한 비주얼 훅...",
      "structure_analysis": "도입-전개-CTA 3단 구성...",
      "visual_pace_analysis": "빠른 컷 전환, 평균 0.8초...",
      "audio_trend_analysis": "트렌딩 BGM 사용...",
      "cta_analysis": "팔로우 유도 CTA 명확...",
      "category_analysis": "{\"primary_category\": \"뷰티/패션\"}",
      "overall_score": 8.5,
      "overall_summary": "높은 완성도의 뷰티 릴스..."
    }
  }'
이미지 분석 업로드
curl -X POST "https://threads.pyrocnc.co.kr/api/external/analysis/42" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-secret-key" \
  -d '{
    "analysis_type": "image",
    "image": {
      "post_ext_id": "Cxyz123abc",
      "platform": "instagram",
      "content_summary": "제품 리뷰 카드뉴스 형식...",
      "extracted_text": "BEST 5 추천 아이템...",
      "visual_composition": "깔끔한 그리드 레이아웃...",
      "category_analysis": "{\"primary_category\": \"뷰티/패션\"}",
      "overall_score": 7.8,
      "overall_summary": "정보성 높은 카드뉴스..."
    }
  }'

POST /api/actions/analyze-carousels v1.3

캐러셀 게시물에 대해 Claude Vision 심층 분석을 시작합니다. 비동기 실행되며 상태는 별도 엔드포인트에서 폴링합니다. 5개 영역 분석: 슬라이드별 OCR, 서사 구조, 훅, 디자인, 종합 평가.

Request Body

필드타입기본값설명
post_idsint[]?null분석할 포스트 DB ID 목록. null이면 캡처된 전체 캐러셀 대상 (최대 200건)
platformstring"instagram"instagram 또는 threads

Response

200 OK
{
  "success": true,
  "data": null,
  "message": "캐러셀 분석이 시작되었습니다"
}

cURL 예시

Bash
# 특정 포스트 분석
curl -X POST "https://threads.pyrocnc.co.kr/api/actions/analyze-carousels" \
  -H "Content-Type: application/json" \
  -d '{"post_ids": [101, 102, 103], "platform": "instagram"}'

# 전체 캐러셀 일괄 분석
curl -X POST "https://threads.pyrocnc.co.kr/api/actions/analyze-carousels" \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram"}'

GET /api/actions/analyze-carousels-status v1.3

캐러셀 분석 작업의 진행 상황을 조회합니다. 프론트엔드에서 2초 간격으로 폴링합니다.

Response

200 OK
{
  "success": true,
  "data": {
    "running": true,
    "total": 15,
    "done": 5,
    "current_post_id": 101,
    "current_step": "analyzing",
    "errors": []
  },
  "message": ""
}

Response 필드

필드타입설명
runningbool현재 실행 중 여부
totalint분석 대상 총 건수
doneint완료된 건수
current_post_idint?현재 처리 중인 포스트 DB ID
current_stepstring현재 단계 (preparing, loading_images, analyzing)
errorsstring[]오류 메시지 목록

빠른 테스트

분석 유형 선택 후 Pending 조회

Insight API 개요

외부 LLM이 소셜 대시보드의 릴스, 캐러셀, 이미지 분석 데이터를 참조하여 콘텐츠 기획에 활용할 수 있도록 하는 읽기 전용 API입니다.

R
REST API (포트 8003) /api/insights/* — 범용 HTTP 접근
M
MCP Server (포트 8004) FastMCP SSE — Claude Code 등 LLM 도구 직접 연동

두 인터페이스 모두 동일한 데이터를 제공합니다. REST API는 범용 클라이언트용, MCP는 LLM 도구 연동용입니다.

인증

/api/insights/* 엔드포인트는 External API와 동일하게 X-Api-Key 헤더로 인증합니다.

헤더비고
X-Api-Key EXTERNAL_API_KEY 환경변수 값 환경변수 미설정 시 인증 스킵 (개발 모드)
Example
curl -H "X-Api-Key: your-secret-key" https://your-host/api/insights/summary

공통 응답 형식

모든 엔드포인트는 동일한 ApiResponse 래퍼를 사용합니다. 대용량 필드 (raw_json, raw_ai_response)는 자동 제거됩니다.

ApiResponse
{
  "success": true,
  "data": { ... },
  "message": ""
}

GET /api/insights/summary

대시보드 전체 현황 요약. 수집 건수, 활성 키워드, 분석 건수(릴스/이미지/캐러셀) 등.

Query Parameters

없음

Response

200 OK
{
  "success": true,
  "data": {
    "total_posts": 12039,
    "instagram_posts": 10771,
    "threads_posts": 1268,
    "active_keywords": 37,
    "today_collected": 0,
    "reel_analyses": 933,
    "image_analyses": 407,
    "carousel_analyses": 144
  }
}

GET /api/insights/posts

수집된 Instagram/Threads 포스트를 검색합니다.

Query Parameters

파라미터타입기본값설명
platformstringinstagraminstagram 또는 threads
keywordstring?null수집 키워드로 필터
searchstring?null텍스트, 작성자, 키워드, 해시태그에서 검색
limitint50최대 반환 수 (1~500)
offsetint0페이지네이션 오프셋

Response 주요 필드

필드타입설명
idintDB 기본키
platformstringinstagram / threads
authorstring작성자 핸들
textstring게시물 텍스트
likes, comments, viewsint참여 지표
post_typestring?Post / Reels / Carousel
hashtagsstring?해시태그 목록
posted_atstring게시 시각

GET /api/insights/reels-ranking

Instagram 릴스를 참여도 종합 점수로 랭킹. virality(45%) + recency(35%) + richness(20%) 가중 합산.

Query Parameters

파라미터타입기본값설명
limitint100최대 반환 수 (1~1000)
min_gradestring?nullA, B, C, D — 최소 등급 필터

Response 주요 필드

필드타입설명
priority_scorefloat종합 점수 (0~100)
gradestringA (80+) / B (60+) / C (40+) / D
virality_scorefloat바이럴 점수 (조회 대비 반응률)
recency_scorefloat최신성 점수 (지수 감쇠)
richness_scorefloat콘텐츠 풍부도 (해시태그, 음악 등)

GET /api/insights/threads-ranking

Threads 포스트 참여도 랭킹. virality(60%) + recency(40%) 가중 합산.

Query Parameters

파라미터타입기본값설명
limitint100최대 반환 수 (1~1000)
min_gradestring?null최소 등급 필터

응답 형식은 reels-ranking과 동일 (virality_score, recency_score, priority_score, grade)

GET /api/insights/carousel-ranking

Instagram + Threads 캐러셀/카드뉴스 통합 랭킹. virality(50%) + recency(50%) 합산 후 양 플랫폼 합산 정렬.

Query Parameters

파라미터타입기본값설명
limitint100최대 반환 수 (1~1000)
min_gradestring?null최소 등급 필터

응답에 platform (instagram/threads), slide_count 추가 포함

GET /api/insights/reel-analyses

완료된 릴스 AI 분석 결과. 훅, 구조, 시각 페이스, CTA, 카테고리 분석과 종합 점수 포함.

Query Parameters

파라미터타입기본값설명
topicstring?null캡션/분석 텍스트에서 키워드 검색
categorystring?null카테고리 필터 (예: 푸드/요리)
min_gradestring?null최소 등급 (A=8+, B=7+, C=5+)
limitint100최대 반환 수 (1~500)

Response 주요 필드

필드타입설명
hook_analysisJSON string첫 3초 훅 분석 (점수, 유형, 시각적 훅)
structure_analysisJSON string영상 구조 분석 (포맷, 페이싱, 서사 흐름)
visual_pace_analysisJSON string시각 페이스 분석 (장면 전환, 리듬, 구도)
cta_analysisJSON stringCTA 분석 (유형, 배치, 효과)
category_analysisJSON string카테고리 분류 (주/부 카테고리, 타겟)
overall_scorefloat종합 점수 (0~10)
overall_summarystring종합 요약문
transcriptstring?음성 전사 텍스트

GET /api/insights/image-analyses

완료된 이미지 포스트 AI 분석 결과.

Query Parameters

파라미터타입기본값설명
platformstring?nullinstagram / threads 필터
topicstring?null키워드 검색
categorystring?null카테고리 필터
min_gradestring?null최소 등급
limitint100최대 반환 수 (1~500)

Response 주요 필드

필드타입설명
content_summarystring콘텐츠 요약
extracted_textstring?이미지 내 텍스트 추출
visual_compositionstring?시각 구도 분석
category_analysisJSON string카테고리 분류
overall_scorefloat종합 점수 (0~10)
overall_summarystring종합 요약문

GET /api/insights/carousel-analyses

완료된 캐러셀/카드뉴스 AI 분석 결과.

Query Parameters

파라미터타입기본값설명
platformstring?nullinstagram / threads 필터
limitint100최대 반환 수 (1~500)

Response 주요 필드

필드타입설명
slide_countint슬라이드 수
slide_ocrstring?슬라이드별 OCR 텍스트
narrative_analysisstring?서사 구조 분석
hook_analysisstring?훅 분석
design_analysisstring?디자인 분석
overall_scorefloat종합 점수 (0~10)
overall_summarystring종합 요약문

GET /api/insights/categories

분석에서 감지된 콘텐츠 카테고리 목록. 분석 결과 필터링에 활용.

Query Parameters

파라미터타입기본값설명
content_typestringreelreel 또는 image

Response

200 OK
{
  "success": true,
  "data": ["가족/육아", "건강/피트니스", "게임", "교육", "뉴스/시사", "라이프스타일", "마케팅", "뷰티/패션", "여행/관광", "유머/엔터테인먼트", "음악/K-POP", "직장/비즈니스", "테크/개발", "푸드/요리", ...]
}

GET /api/insights/hashtag-stats

해시태그 성과 통계. 사용 횟수, 평균 참여 지표, 랭크 점수.

Query Parameters

파라미터타입기본값설명
platformstringinstagraminstagram / threads
limitint50최대 반환 수 (1~200)

Response 주요 필드

필드타입설명
tagstring해시태그
countint사용 횟수
avg_likesfloat평균 좋아요
avg_commentsfloat평균 댓글
avg_viewsfloat평균 조회수
rank_scorefloat종합 랭크 점수

GET /api/insights/content-filter-history

콘텐츠 필터 워크플로우 이력. 검색 조건, 패턴 분석, 브랜드 파라미터, 생성된 제안 포함.

Query Parameters

파라미터타입기본값설명
limitint30최대 반환 수 (1~100)
history_idint?null특정 이력 상세 조회 (지정 시 단건 반환)

Response (목록)

200 OK (목록)
{
  "success": true,
  "data": [
    {
      "id": 15,
      "platform": "instagram",
      "search_topic": "맛집",
      "search_category": "푸드/요리",
      "brand_name": "MyBrand",
      "search_post_count": 8,
      "created_at": "2026-04-20 14:30:00"
    }
  ]
}

Response (상세 — history_id 지정 시)

추가 필드: search_posts_json, analysis_json, proposals_json (JSON 파싱된 객체), target_audience, key_message, content_purpose, tone, duration, slide_count, notes

MCP Server (포트 8004)

FastMCP 기반 SSE 서버로, Claude Code 등 MCP 클라이언트에서 tool로 직접 호출할 수 있습니다.

연결 설정

Claude Code MCP Config
{
  "mcpServers": {
    "social-dashboard": {
      "url": "http://YOUR_HOST:8004/sse"
    }
  }
}

제공 Tools (12개)

ToolParameters설명
get_dashboard_summary전체 현황 요약
search_postsplatform, keyword, search, limit포스트 검색
get_reels_rankinglimit, min_grade릴스 랭킹
get_threads_rankinglimit, min_grade스레드 랭킹
get_carousel_rankinglimit, min_grade캐러셀 랭킹
get_reel_analysestopic, category, min_grade, limit릴스 분석 결과
get_image_analysesplatform, topic, category, min_grade, limit이미지 분석 결과
get_carousel_analysesplatform, limit캐러셀 분석 결과
get_categoriescontent_type카테고리 목록
get_hashtag_statsplatform, limit해시태그 통계
get_content_filter_historylimit, history_id콘텐츠 필터 이력
query_dbsql, db_name읽기 전용 SQL (SELECT만)

Live Test

분석 시스템 개요

Social Dashboard는 Claude Sonnet (claude-sonnet-4-20250514) 모델을 사용하여 소셜 미디어 콘텐츠를 자동 분석합니다. 이미지 분석, 캐러셀 분석, 릴스(동영상) 분석 세 가지 파이프라인으로 나뉩니다.

IMG
이미지 분석 Claude Vision으로 단일 이미지 게시물 분석 (carousel/sidecar 제외)
CRS
캐러셀 분석 Claude Vision으로 캐러셀 슬라이드 심층 분석 (OCR+서사+훅+디자인)
VID
릴스 분석 ffmpeg 프레임 추출 + Whisper STT + Claude 멀티모달

이미지 분석 파이프라인

처리 흐름

1
이미지 로드 screenshot_paths에서 이미지 파일 읽기
2
전처리 & 리사이즈 JPEG 변환, 최대 768px, Base64 인코딩
3
Claude Vision 분석 멀티모달 API로 이미지 + 메타데이터 전송
4
결과 저장 JSON 파싱 후 DB 저장

이미지 전처리 설정

설정설명
MAX_IMAGE_WIDTH768px이미지 최대 가로 폭 (비율 유지 리사이즈)
JPEG_QUALITY85%JPEG 압축 품질
MAX_IMAGES20장게시물당 최대 이미지 수
색상 모드RGBRGBA/P 모드는 RGB로 자동 변환
인코딩Base64Claude API 전송을 위한 Base64 인코딩

Claude에 전달되는 컨텍스트

데이터형식설명
작성자텍스트@username 형식의 작성자 핸들
이미지 수숫자게시물에 포함된 이미지 장수
좋아요/댓글/조회수숫자게시물 인게이지먼트 지표
캡션텍스트게시물 캡션 전문
해시태그텍스트게시물에 포함된 해시태그
이미지Base64 이미지슬라이드 번호와 함께 순차적으로 전송

분석 항목

content_summary
이미지 콘텐츠에 대한 상세 요약 (2-3문장)
extracted_text (OCR)
각 슬라이드별 이미지 내 텍스트, 위치(상단/중앙/하단), 스타일(제목/본문/CTA) 추출
visual_composition
레이아웃, 색감/톤, 브랜드 일관성, 텍스트 오버레이, 시각적 계층, 캐러셀 흐름, 슬라이드 관계, 디자인 통일성 (1-10점)
category
주요/세부 카테고리, 타겟 오디언스, 콘텐츠 유형(정보형/감성형/홍보형/교육형/엔터테인먼트)
overall
종합 점수(1-10), 강점, 개선점, 종합 요약

System Prompt (이미지 분석)

System Prompt
당신은 소셜 미디어 이미지 콘텐츠 분석 전문가입니다.

이 메시지에는 게시물의 이미지가 포함되어 있습니다. 캐러셀 게시물의 경우 여러 슬라이드가 순서대로 전달됩니다.

각 이미지를 직접 보고 다음을 분석하세요:
- 이미지에 포함된 텍스트 (OCR)
- 화면 구성 및 레이아웃
- 색감, 톤, 브랜드 일관성
- 텍스트 오버레이 디자인
- 시각적 계층 구조
- 콘텐츠 카테고리 및 타겟 오디언스

**캐러셀 게시물(2장 이상)의 경우 슬라이드 간 관계를 반드시 분석하세요:**
- 내러티브/정보 흐름: 슬라이드가 어떤 순서와 논리로 연결되는지
- 디자인 일관성: 폰트, 색상, 레이아웃의 통일성
- 각 슬라이드의 역할: 표지/본문/요약/CTA 등

응답 JSON 구조

Expected JSON Response
{
  "content_summary": "이미지 콘텐츠에 대한 상세 요약 (2-3문장)",
  "extracted_text": [
    {
      "slide": 1,
      "text": "이미지 내 텍스트",
      "position": "상단/중앙/하단",
      "style": "제목/본문/CTA"
    }
  ],
  "visual_composition": {
    "score": "1-10",
    "layout": "레이아웃 분석",
    "color_palette": "색감/톤 분석",
    "brand_consistency": "브랜드 일관성",
    "text_overlay_design": "텍스트 오버레이 디자인 품질",
    "visual_hierarchy": "시각적 계층 구조",
    "carousel_flow": "슬라이드 간 내러티브/정보 흐름",
    "slide_relationship": "연결 방식 (순차적 스토리/주제별 분류/단계적 설명/대비 등)",
    "design_consistency": "슬라이드 간 디자인 통일성",
    "summary": "비주얼 구성 종합 평가"
  },
  "category": {
    "primary_category": "주요 카테고리",
    "sub_category": "세부 카테고리",
    "target_audience": "타겟 오디언스",
    "content_type": "정보형/감성형/홍보형/교육형/엔터테인먼트"
  },
  "overall": {
    "score": "1-10",
    "strengths": ["강점1", "강점2"],
    "improvements": ["개선점1", "개선점2"],
    "summary": "종합 분석 요약"
  }
}

캐러셀 분석 파이프라인 v1.3

처리 흐름

1
캐러셀 포스트 필터 post_type=Carousel + screenshot_paths 존재 필터링
2
이미지 로드 & 리사이즈 최대 20슬라이드, 768px, JPEG 85%, Base64
3
Claude Vision 심층 분석 5개 영역: OCR, 서사, 훅, 디자인, 종합
4
결과 저장 carousel_analyses 테이블에 JSON 저장

이미지 전처리 설정

설정설명
MAX_IMAGE_WIDTH768px슬라이드 최대 가로 폭 (비율 유지 리사이즈)
JPEG_QUALITY85%JPEG 압축 품질
MAX_SLIDES20장캐러셀당 최대 슬라이드 수
색상 모드RGBRGBA/P 모드는 RGB로 자동 변환
max_tokens6144Claude 응답 최대 토큰 (이미지 분석 4096보다 큼)

분석 항목 (5개 영역)

slide_ocr (슬라이드별 OCR)
각 슬라이드의 텍스트 추출, 위치(상단/중앙/하단), 스타일(제목/본문/CTA/강조), 폰트 크기(대/중/소), 슬라이드 역할(표지/도입/전개/클라이맥스/요약/CTA)
narrative (서사 구조 분석)
서사 유형(문제→해결/순차정보/비교대조/Q&A/스토리텔링/튜토리얼), 슬라이드 간 논리적 흐름, 도입→전개→마무리 진행 구조, 연결성 평가 (1-10점)
hook (훅 분석)
첫 슬라이드의 훅 유형(질문형/충격형/공감형/호기심유발/통계형/도발형), 시각적·텍스트 후킹 요소, 스크롤 멈춤 효과 평가 (1-10점)
design (디자인 분석)
색상 팔레트, 타이포그래피, 레이아웃 패턴, 슬라이드 간 디자인 일관성, 시각적 계층 구조, 가독성 평가 (1-10점)
overall (종합 평가)
종합 점수(1-10), 강점, 개선점, 핵심 전략, 종합 분석 요약

System Prompt (캐러셀 분석)

System Prompt
당신은 소셜 미디어 캐러셀 콘텐츠 분석 전문가입니다.

이 메시지에는 캐러셀 게시물의 슬라이드 이미지가 순서대로 포함되어 있습니다.

각 슬라이드를 직접 보고 다음 5개 영역을 심층 분석하세요:

1. **슬라이드별 OCR**: 각 슬라이드의 텍스트, 위치, 스타일, 역할을 추출
2. **서사 구조**: 슬라이드 간 논리적 흐름, 서사 유형, 진행 구조
3. **훅 분석**: 첫 슬라이드의 스크롤 멈춤 효과, 훅 유형과 전략
4. **디자인 분석**: 색상, 타이포, 레이아웃, 일관성, 가독성
5. **종합 평가**: 전체 점수, 강점, 개선점

응답 JSON 구조

Expected JSON Response
{
  "slide_ocr": [
    {
      "slide": 1,
      "texts": [
        {"text": "추출된 텍스트", "position": "상단/중앙/하단", "style": "제목/본문/CTA/강조", "font_size": "대/중/소"}
      ],
      "role": "표지/도입/전개/클라이맥스/요약/CTA"
    }
  ],
  "narrative": {
    "score": "1-10",
    "type": "문제→해결/순차정보/비교대조/Q&A/스토리텔링/튜토리얼",
    "flow": "슬라이드 간 서사 흐름 상세 설명",
    "progression": "도입→전개→마무리 구조 분석",
    "coherence": "논리적 연결성 평가",
    "summary": "서사 구조 종합 평가"
  },
  "hook": {
    "score": "1-10",
    "hook_type": "질문형/충격형/공감형/호기심유발/통계형/도발형",
    "first_slide_analysis": "첫 슬라이드 상세 분석",
    "visual_hook": "시각적 후킹 요소",
    "text_hook": "텍스트 후킹 요소",
    "scroll_stop_power": "스크롤 멈춤 효과 평가",
    "summary": "훅 종합 평가"
  },
  "design": {
    "score": "1-10",
    "color_palette": "색상 팔레트 분석",
    "typography": "타이포그래피 분석",
    "layout": "레이아웃 패턴 분석",
    "consistency": "슬라이드 간 디자인 일관성",
    "visual_hierarchy": "시각적 계층 구조",
    "readability": "가독성 평가",
    "summary": "디자인 종합 평가"
  },
  "category": {
    "primary_category": "주요 카테고리",
    "sub_category": "세부 카테고리",
    "target_audience": "타겟 오디언스",
    "content_type": "정보형/감성형/홍보형/교육형/엔터테인먼트"
  },
  "overall": {
    "score": "1-10",
    "strengths": ["강점1", "강점2"],
    "improvements": ["개선점1", "개선점2"],
    "key_takeaway": "이 캐러셀의 핵심 전략",
    "summary": "종합 분석 요약"
  }
}

DB 스키마 (carousel_analyses 테이블)

컬럼타입설명
idINTEGER PK자동 증가 기본키
post_idINTEGER포스트 DB 기본키
post_ext_idTEXT외부 포스트 ID
platformTEXTinstagram / threads
captionTEXT캡션 텍스트
slide_countINTEGER슬라이드 수
slide_ocrTEXT (JSON)슬라이드별 OCR 결과
narrative_analysisTEXT (JSON)서사 구조 분석
hook_analysisTEXT (JSON)훅 분석
design_analysisTEXT (JSON)디자인 분석
category_analysisTEXT (JSON)카테고리 분류
overall_scoreREAL종합 점수 (0-10)
overall_summaryTEXT (JSON)종합 평가
raw_ai_responseTEXT (JSON)원본 AI 응답 전문
analysis_statusTEXTpending / processing / done / failed
errorTEXT에러 메시지 (실패 시)
created_atTEXT생성 시각
updated_atTEXT수정 시각

릴스(동영상) 분석 파이프라인

처리 흐름

1
오디오 추출 + 씬 감지 ffmpeg로 WAV 변환 + 장면 전환 분석
2
프레임 추출 0.5fps로 JPEG 프레임 캡처
3
음성 전사 (STT) faster-whisper로 음성을 텍스트로 변환
4
Claude 멀티모달 분석 프레임 + 텍스트 + 메타데이터 종합 분석

Step 1: 오디오 추출 & 씬 감지 (ffmpeg)

처리설정설명
영상 길이 측정ffprobe영상 duration 추출 (timeout 30초)
오디오 추출PCM 16kHz monoffmpeg -vn -acodec pcm_s16le -ar 16000 -ac 1 → WAV 파일
씬 감지threshold 0.3select='gt(scene,0.3)',showinfo 필터로 장면 전환점 검출
컷 속도 계산자동scene_count / duration = cuts_per_second

Step 2: 프레임 추출 설정

설정설명
FRAMES_PER_SECOND0.5 fps2초당 1장 추출 (30초 영상 = 15장)
FRAME_MAX_WIDTH384px프레임 최대 가로 폭 (비율 유지)
FRAME_JPEG_QUALITY5 (ffmpeg q:v)JPEG 품질 (2=최고, 31=최저, 5=분석용 적정)
MAX_FRAMES30장긴 영상도 최대 30장으로 제한
인코딩Base64Claude API 전송을 위한 Base64 인코딩

Step 3: 음성 전사 (STT)

설정설명
모델faster-whisper base속도와 정확도의 균형. 싱글턴(transcriber.py)으로 로드
디바이스CPUcompute_type="int8" 양자화로 메모리 절감
빔 서치beam_size=5전사 정확도 향상을 위한 빔 크기
출력 형식타임스탬프 포함[0.0s-2.5s] 텍스트... 형식으로 출력
캡처 시 자동 전사v1.1릴스 캡처 시 자동으로 STT 수행 → collected_posts.transcript에 저장
분석 시 재사용v1.1DB에 이미 transcript가 있으면 Whisper 스킵 (로그: "Using existing transcript")

Step 4: Claude에 전달되는 컨텍스트

데이터형식설명
작성자텍스트@username 형식의 작성자 핸들
영상 메타데이터숫자길이(초), 프레임 수, 씬 전환 수, 초당 컷
좋아요/댓글/조회수숫자게시물 인게이지먼트 지표
캡션텍스트릴스 하단 캡션 텍스트
해시태그텍스트게시물에 포함된 해시태그
음악 정보텍스트사용된 음악 제목/아티스트
STT 전사텍스트타임스탬프 포함 음성 전사 결과
프레임 이미지Base64 이미지타임스탬프별 프레임 (e.g. [0초], [2초], ...)

분석 항목 (7개 영역)

hook (훅 분석)
첫 3초(프레임 0-2초) 화면 구성, 훅 유형(질문형/충격형/공감형/정보형/스토리형), 자막/텍스트 오버레이, 시각적 후킹 요소 (1-10점)
structure (구조 분석)
포맷(정보전달/스토리텔링/튜토리얼/브이로그/챌린지/리뷰), 페이싱(빠름/보통/느림), 서사 흐름 (1-10점)
visual_pace (시각적 페이스)
씬 전환 패턴, 리듬(빠른/적절한/느린 컷), 구도(중앙/삼등분/대각선), 자막/그래픽 활용, 시각 스타일 (1-10점)
audio_trend (오디오/트렌드)
음악과 콘텐츠 적합도, 트렌드 반영도, 오디오 품질 (1-10점)
cta (CTA 분석)
CTA 유형(직접적/간접적/없음), 배치 위치, 화면 CTA 텍스트/그래픽, 효과 평가 (1-10점)
category (카테고리)
주요/세부 카테고리, 타겟 오디언스 (1-10점)
overall (종합)
종합 점수(1-10), 강점 3개, 개선점 3개, 시각+음성+텍스트 종합 요약

System Prompt (릴스 분석)

System Prompt
당신은 Instagram Reels 콘텐츠 전략 분석 전문가입니다.

이 메시지에는 릴스 영상의 프레임 이미지(1초당 1장)가 포함되어 있습니다.
프레임 이미지를 직접 보고 다음을 반드시 분석하세요:
- 화면 구성 및 레이아웃 (인물 위치, 배경, 구도)
- 후킹 자막/텍스트 오버레이 (위치, 크기, 내용, 등장 타이밍)
- 등장인물의 표정, 제스처, 시선 방향
- 컷 전환 패턴과 시각적 리듬
- 제품/브랜드 노출 요소
- 첫 1-3초(첫 3장 프레임)의 시각적 후킹 요소

텍스트 데이터(캡션, STT 전사, 메타데이터)와 프레임 이미지를 종합하여 분석하세요.

응답 JSON 구조

Expected JSON Response
{
  "hook": {
    "score": "1-10",
    "first_3_seconds": "첫 3초 화면 구성 + 음성/자막 분석",
    "hook_type": "질문형/충격형/공감형/정보형/스토리형",
    "text_overlay": "후킹 자막/텍스트 내용과 위치",
    "visual_hook": "시각적 후킹 요소",
    "attention_grab": "종합적 시선 끌기 요소",
    "summary": "Hook 평가 요약"
  },
  "structure": {
    "score": "1-10",
    "format": "정보 전달/스토리텔링/튜토리얼/브이로그/챌린지/리뷰",
    "pacing": "빠름/보통/느림",
    "narrative_flow": "프레임 기반 서사 흐름 (도입-전개-마무리)",
    "summary": "구조 평가 요약"
  },
  "visual_pace": {
    "score": "1-10",
    "scene_transitions": "씬 전환 패턴",
    "rhythm": "빠른 컷/적절한 컷/느린 컷",
    "composition": "화면 구도 (중앙/삼등분/대각선 등)",
    "text_graphics": "자막, 그래픽, 이모지 활용",
    "visual_style": "전체적 시각 스타일",
    "summary": "비주얼 페이스 평가 요약"
  },
  "audio_trend": {
    "score": "1-10",
    "music_fit": "음악과 콘텐츠 적합도",
    "trend_relevance": "트렌드 반영도",
    "audio_quality": "오디오 품질",
    "summary": "오디오/트렌드 평가 요약"
  },
  "cta": {
    "score": "1-10",
    "cta_type": "직접적/간접적/없음",
    "cta_placement": "CTA 배치 위치",
    "cta_visual": "CTA 텍스트/그래픽",
    "effectiveness": "CTA 효과 평가",
    "summary": "CTA 평가 요약"
  },
  "category": {
    "score": "1-10",
    "primary_category": "주요 카테고리",
    "sub_category": "세부 카테고리",
    "target_audience": "타겟 오디언스",
    "summary": "카테고리 평가 요약"
  },
  "overall": {
    "score": "1-10",
    "strengths": ["강점1", "강점2", "강점3"],
    "improvements": ["개선점1", "개선점2", "개선점3"],
    "summary": "종합 분석 요약 (시각 + 음성 + 텍스트 종합)"
  }
}

기술 스택 요약

구성 요소기술용도
AI 모델claude-sonnet-4-20250514이미지/영상 멀티모달 분석
이미지 처리Pillow (PIL)리사이즈, JPEG 변환, Base64 인코딩
영상 처리ffmpeg / ffprobe프레임 추출, 오디오 분리, 씬 감지
음성 인식faster-whisper (base, int8)음성 → 텍스트 (타임스탬프 포함)
API 클라이언트anthropic Python SDKClaude API 호출 (sync client in thread)
비동기 처리asyncio.to_thread()동기 작업(ffmpeg, Whisper, Claude)을 비동기로 래핑
DBaiosqlite분석 결과 저장 (reel_analyses, image_analyses, carousel_analyses 테이블)