10 KiB

Raw Blame History

O2Sound API Documentation

개요

기본 정보

Base URL: http://localhost:8000
API Version: v1
Framework: FastAPI
Documentation: /docs (Swagger UI), /redoc (ReDoc)

기술 스택

백엔드 프레임워크: FastAPI
비동기 작업 처리: Celery
메시지 브로커: Redis
데이터베이스: PostgreSQL (추정)
인증: Session-based + OAuth 2.0 (Google)

응답 형식

모든 API 응답은 @response_wrapper 데코레이터를 통해 일관된 형식으로 반환됩니다.

인증

세션 기반 인증

로그인 후 세션 쿠키를 통한 인증
SessionMiddleware 사용

OAuth 2.0

Google OAuth 지원
임시 토큰을 통한 안전한 토큰 교환

API 엔드포인트

기본 엔드포인트

서비스 정보 확인

GET /

응답 예시:

{
  "message": "FastAPI DDD with Celery Workers",
  "version": "1.0.0",
  "docs": "/docs"
}

헬스 체크

GET /health

응답 예시:

{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "celery": "running"
}

인증 API

회원가입

POST /auth/join
Content-Type: application/json

요청 본문:

{
  "user_id": "testuser",
  "name": "홍길동",
  "password": "securepassword123",
  "email": "test@example.com",
  "phone_number": "010-1234-5678"
}

응답 (201 Created):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "홍길동"
}

소셜 로그인 API

Google OAuth 로그인 시작

GET /social/google/login?return_url=http://localhost:3300/dashboard

쿼리 파라미터:

return_url (선택): 로그인 성공 후 리다이렉트할 URL

응답:

Google OAuth 인증 페이지로 302 리다이렉트

Google OAuth 콜백

GET /social/google/callback?code=AUTHORIZATION_CODE&state=STATE

쿼리 파라미터:

code: Google에서 제공한 인증 코드
state: CSRF 방지를 위한 상태 값
error (선택): OAuth 에러 발생 시

응답:

성공: {return_url}?token={temp_token_id}&auth_success=true로 리다이렉트
실패: http://localhost:3300/auth/error?error={error_message}로 리다이렉트

Google 토큰 정보 조회

GET /social/google/token/{temp_token_id}

경로 파라미터:

temp_token_id: 임시 토큰 ID

응답 (200 OK):

{
  "access_token": "ya29.a0AfH6SMBx...",
  "refresh_token": "1//0gVO1VQ...",
  "token_type": "Bearer",
  "expires_in": 3599,
  "user_info": {
    "id": "google_user_id",
    "email": "user@gmail.com",
    "name": "사용자 이름",
    "picture": "https://lh3.googleusercontent.com/..."
  }
}

사용자 API

사용자 업체 목록 조회

POST /user/items
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

응답 (200 OK):

{
  "total_count": 2,
  "items": [
    {
      "item_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "카페 블루문",
      "address": "서울시 강남구 역삼동 123-45",
      "url": "https://bluemoon.cafe",
      "phone_number": "02-1234-5678",
      "thumbnail_url": "https://example.com/thumb1.jpg",
      "hashtags": ["카페", "브런치", "디저트"]
    }
  ]
}

업체 정보 수정

PUT /user/item/update
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "item_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "카페 블루문 강남점",
  "address": "서울시 강남구 역삼동 123-45",
  "url": "https://bluemoon-gangnam.cafe",
  "phone_number": "02-1234-5678",
  "thumbnail_url": "https://example.com/new-thumb.jpg"
}

응답 (200 OK):

{
  "success": true,
  "item_id": "550e8400-e29b-41d4-a716-446655440000"
}

업체 삭제

DELETE /user/item/delete
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "item_id": "550e8400-e29b-41d4-a716-446655440000"
}

응답 (200 OK):

{
  "success": true,
  "item_id": "550e8400-e29b-41d4-a716-446655440000"
}

사용자 비디오 목록 조회

POST /user/videos
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

응답 (200 OK):

{
  "total_count": 3,
  "videos": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "title": "카페 블루문 홍보 영상",
      "description": "아늑한 분위기의 카페 블루문을 소개합니다",
      "url": "/user/video/bluemoon_promo_2024.mp4",
      "is_uploaded": true,
      "download_count": 15,
      "resolution": "1920x1080",
      "status": "completed",
      "thumbnail_url": "https://example.com/video-thumb1.jpg"
    }
  ]
}

비디오 삭제

DELETE /user/video/delete
Content-Type: application/json

요청 본문:

{
  "user_id": "testuser",
  "video_id": "660e8400-e29b-41d4-a716-446655440000"
}

응답 (200 OK):

{
  "message": "비디오가 성공적으로 삭제되었습니다"
}

사용자 프로필 조회

POST /user/profile
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

응답 (200 OK):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "홍길동",
  "email": "test@example.com",
  "phone_number": "010-1234-5678",
  "created_at": "2024-01-15T10:30:00Z"
}

프로필 수정

PUT /user/profile/update
Content-Type: application/json

요청 본문:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "홍길동",
  "email": "newemail@example.com",
  "phone_number": "010-9876-5432"
}

응답 (200 OK):

{
  "user_id": "testuser",
  "name": "홍길동"
}

비디오 스트리밍 API

비디오 파일 스트리밍

GET /user/video/{filename}

경로 파라미터:

filename: 비디오 파일명 (URL 인코딩 지원)

예시:

GET /user/video/bluemoon_promo_2024.mp4

응답:

Content-Type: video/mp4
비디오 파일 스트리밍

에러 응답 (404 Not Found):

{
  "detail": "Video not found"
}

영상 제작 API

영상 제작 워크플로우 시작

POST /moviemaker/start-workflow
Content-Type: application/json

요청 본문:

{
  "url": "https://bluemoon.cafe"
}

응답 (200 OK):

{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "progress": {
    "metadata": false,
    "lyrics": false,
    "songs": false,
    "images": false,
    "movies": false,
    "combined": false
  }
}

워크플로우 진행률 확인

POST /moviemaker/progress
Content-Type: application/json

요청 본문:

{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

응답 (200 OK):

{
  "progress": {
    "metadata": true,
    "lyrics": true,
    "songs": true,
    "images": false,
    "movies": false,
    "combined": false
  }
}

에러 처리

표준 에러 응답 형식

{
  "error_code": "ERROR_CODE",
  "error_message": "사용자 친화적인 에러 메시지"
}

일반적인 HTTP 상태 코드

200 OK: 요청 성공
201 Created: 리소스 생성 성공
400 Bad Request: 잘못된 요청
401 Unauthorized: 인증 필요
403 Forbidden: 권한 없음
404 Not Found: 리소스를 찾을 수 없음
422 Unprocessable Entity: 유효성 검사 실패
500 Internal Server Error: 서버 오류

에러 코드 예시

AUTH_001: 잘못된 로그인 정보
AUTH_002: 이미 존재하는 사용자 ID
USER_001: 사용자를 찾을 수 없음
VIDEO_001: 비디오를 찾을 수 없음
TASK_001: 작업을 찾을 수 없음

워크플로우 상세

영상 제작 프로세스

URL 크롤링 (task1_crawl)
- 입력 URL에서 메타데이터 추출
- 업체명, 설명, 키워드 등 수집
병렬 처리

가사 및 음악 생성 브랜치:
- 가사 생성 (task2_generate_lyrics)
  - 크롤링한 메타데이터 기반 가사 생성
  - AI 모델을 통한 창의적인 가사 작성
- 음악 생성 (task3_generate_music)
  - 생성된 가사에 맞는 음악 제작
  - 장르, 템포, 분위기 자동 매칭
이미지 및 비디오 생성 브랜치:
- 이미지 크롤링 (task1_crawl_images)
  - 웹사이트에서 관련 이미지 수집
  - 품질 및 관련성 필터링
- 비디오 생성 (task4_generate_video)
  - 수집된 이미지로 비디오 제작
  - 전환 효과 및 애니메이션 적용
최종 병합 (task5_merge_results)
- 음악과 비디오 동기화
- 최종 영상 파일 생성
- 업로드 및 저장

진행률 추적

Redis를 통한 실시간 상태 업데이트
각 단계별 완료 상태 확인 가능
비동기 작업으로 긴 처리 시간 대응

개발 가이드

로컬 개발 환경 실행

# Poetry 환경 설정
poetry install

# 환경 변수 설정
cp .env.local .env

# Redis 실행 (Docker)
docker run -d -p 6379:6379 redis

# Celery Worker 실행
./run-celery.sh

# FastAPI 서버 실행
./run-local.sh

API 테스트

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

프로덕션 배포

# Docker 이미지 빌드
docker build -t o2sound-backend .

# 프로덕션 실행
./run-prod.sh

10 KiB Raw Blame History

O2Sound API Documentation

목차

개요

기본 정보

기술 스택

응답 형식

인증

세션 기반 인증

OAuth 2.0

API 엔드포인트

기본 엔드포인트

서비스 정보 확인

헬스 체크

인증 API

회원가입

로그인

소셜 로그인 API

Google OAuth 로그인 시작

Google OAuth 콜백

Google 토큰 정보 조회

사용자 API

사용자 업체 목록 조회

업체 정보 수정

업체 삭제

사용자 비디오 목록 조회

비디오 삭제

사용자 프로필 조회

프로필 수정

비디오 스트리밍 API

비디오 파일 스트리밍

영상 제작 API

영상 제작 워크플로우 시작

워크플로우 진행률 확인

에러 처리

표준 에러 응답 형식

일반적인 HTTP 상태 코드

에러 코드 예시

워크플로우 상세

영상 제작 프로세스

진행률 추적

개발 가이드

로컬 개발 환경 실행

API 테스트

프로덕션 배포

10 KiB

Raw Blame History