🚀 AI Processing API Help

v2.1.0 Stable

🔄 통합 파이프라인

STT + 가공 + 번역 + 어휘를 한 번에 처리

⚡ Stateless API

경량 번역/전사 REST API

📐 자막 가공

LLM 기반 자막 호흡 재구성

🎨 번역 프리셋

Spicy, Disney 등 톤 스타일

🔄 통합 파이프라인 (Full Pipeline)

POST /api/tasks/process-full

가장 권장되는 통합 분석 방식입니다. STT부터 어휘 추출까지 자동 진행됩니다.

{
  "media_id": 589,
  "stt_engine": "groq", // groq, faster-whisper, deepgram
  "translate_engine": "deepseek", // deepseek, groq, deepl
  "source_lang": "en",
  "target_lang": "ko",
  "run_stt": true,
  "run_translate": true,
  "run_vocab": true,
  "include_notes": true,
  "max_chars": 60
}

Pro Tip: 작업이 시작되면 task_id가 즉시 반환됩니다. GET /api/tasks/{task_id}를 폴링하여 진행률(0-100%)을 확인할 수 있습니다.

⚡ Stateless REST API (경량 API)

POST /api/v1/translate

DB 저장 없이 단순 텍스트 번역 결과를 반환합니다.

curl -X POST "/api/v1/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "target": "ko",
    "engine": "deepseek"
  }'

POST /api/v1/transcribe

음성 파일을 업로드하고 즉시 JSON 전사 결과를 받습니다.

curl -X POST "/api/v1/transcribe?engine=groq" \
  -F "file=@audio.mp3"

📐 자막 가공 모드 (Refactor Modes)

모드 ID	설명	특징
normal	일반 롱폼 영상	자연스러운 문장 단위 분할. 가독성 중심.
shorts_medium	표준 쇼츠 스타일	5~8단어 단위. 화면 전환 호흡에 최적화.
shorts_short	초고속 쇼츠 스타일	2~4단어 단위. 틱톡/릴스 등 자극적 호흡.

🎨 번역 프리셋 (Translation Presets)

🌶️ youtube_spicy

HOT

"2 Broke Girls/OnlyFans" 감성. 성적 드립, 시사 풍자, 엣지 있는 드립을 한국어 정서에 맞춰 번역합니다. 드립과 신조어를 적극 활용합니다.

🏰 disney_colloquial

KIDS-SAFE

친근하고 건전한 한국어 구어체. 디즈니 애니메이션처럼 누구나 이해하기 쉽고 명확하며, 예의 바른 표준 말투를 사용합니다.

🌹 melo_drama

ROMANTIC

감성적이고 시적인 번역. 로맨스나 멜로드라마에 어울리는 진지하고 풍부한 감정 표현을 담아 대사 톤을 조절합니다.

👔 drama_formal

STANDARD

격식 있는 한국어 존댓말. 드라마 대사처럼 깔끔하고 안정적인 호칭(-요, -니다)을 사용합니다.

📚 어휘 및 해설 (Vocab & Notes)

모든 분석 결과는 원문 Row ID에 1:1로 매핑됩니다. 자막 조회 API 시 vocabs 필드와 ai_note 필드로 반환됩니다.

📌 데이터 구조 예시

{
  "id": 12345,
  "texts": { "en": "How you doin'?", "ko": "어떻게 지내?" },
  "vocabs": [
    { "term": "How you doin'?", "gloss": "어떻게 지내?", "nuance": "친구 사이 인사", "example": "Hey!" }
  ],
  "ai_note": "조이(Friends)의 유명한 작업 멘트로 쓰일 때가 많음."
}