# CastAD Backend AI 기반 광고 음악 생성 서비스의 백엔드 API 서버입니다. ## 기술 스택 - **Language**: Python 3.13 - **Framework**: FastAPI - **Database**: MySQL (asyncmy 비동기 드라이버), Redis - **ORM**: SQLAlchemy (async) - **Package Manager**: uv - **AI Services**: - OpenAI ChatGPT (가사 생성, 마케팅 분석) - Suno AI (음악 생성) - Creatomate (비디오 생성) ## 프로젝트 구조 ```text app/ ├── core/ # 핵심 설정 및 공통 모듈 (logging, exceptions) ├── database/ # 데이터베이스 세션 및 Redis 설정 ├── dependencies/ # FastAPI 의존성 주입 ├── home/ # 홈 API (크롤링, 영상 생성 요청) ├── lyric/ # 가사 API (가사 생성) ├── song/ # 노래 API (Suno AI 음악 생성) ├── user/ # 사용자 모듈 (카카오 로그인, JWT 인증) ├── video/ # 비디오 관련 모듈 └── utils/ # 유틸리티 (ChatGPT, Suno, 크롤러, 프롬프트) ``` ## API 엔드포인트 ### Home API | Method | Endpoint | 설명 | | ------ | ------------------ | ------------------------------ | | POST | `/crawling` | 네이버 지도 장소 크롤링 | | POST | `/generate` | 기본 영상 생성 요청 | | POST | `/generate/urls` | URL 기반 영상 생성 요청 | | POST | `/generate/upload` | 파일 업로드 기반 영상 생성 요청 | ### Lyric API | Method | Endpoint | 설명 | | ------ | ------------------------- | --------------------------- | | POST | `/lyric/generate` | ChatGPT를 이용한 가사 생성 | | GET | `/lyric/status/{task_id}` | 가사 생성 상태 조회 | | GET | `/lyric/{task_id}` | 가사 상세 조회 | | GET | `/lyrics` | 가사 목록 조회 (페이지네이션) | ### Song API | Method | Endpoint | 설명 | | ------ | -------------------------- | ----------------------------- | | POST | `/song/generate` | Suno AI를 이용한 노래 생성 요청 | | GET | `/song/status/{task_id}` | 노래 생성 상태 조회 (폴링) | ## 환경 설정 `.env` 파일에 다음 환경 변수를 설정합니다: ```env # ================================ # 프로젝트 기본 정보 # ================================ PROJECT_NAME=CastAD # 프로젝트 이름 PROJECT_DOMAIN=localhost:8000 # 프로젝트 도메인 (호스트:포트) PROJECT_VERSION=0.1.0 # 프로젝트 버전 DESCRIPTION=FastAPI 기반 CastAD 프로젝트 # 프로젝트 설명 ADMIN_BASE_URL=/admin # 관리자 페이지 기본 URL DEBUG=True # 디버그 모드 (True: 개발, False: 운영) # ================================ # MySQL 설정 # ================================ MYSQL_HOST=localhost # MySQL 호스트 주소 MYSQL_PORT=3306 # MySQL 포트 번호 MYSQL_USER=castad-admin # MySQL 사용자명 MYSQL_PASSWORD=o2o1324 # MySQL 비밀번호 MYSQL_DB=castad # 사용할 데이터베이스명 # ================================ # Redis 설정 # ================================ REDIS_HOST=localhost # Redis 호스트 주소 REDIS_PORT=6379 # Redis 포트 번호 # ================================ # CORS 설정 # ================================ CORS_ALLOW_ORIGINS='["*"]' # 허용할 Origin 목록 (JSON 배열 형식) CORS_ALLOW_CREDENTIALS=True # 자격 증명(쿠키 등) 허용 여부 CORS_ALLOW_METHODS='["*"]' # 허용할 HTTP 메서드 (JSON 배열 형식) CORS_ALLOW_HEADERS='["*"]' # 허용할 HTTP 헤더 (JSON 배열 형식) CORS_MAX_AGE=600 # Preflight 요청 캐시 시간 (초) # ================================ # Azure Blob Storage 설정 # ================================ AZURE_BLOB_SAS_TOKEN=your_sas_token # Azure Blob Storage SAS 토큰 AZURE_BLOB_BASE_URL=https://... # Azure Blob Storage 기본 URL # ================================ # Creatomate 템플릿 설정 # ================================ TEMPLATE_ID_VERTICAL=your_template_id # 세로형(9:16) 비디오 템플릿 ID TEMPLATE_DURATION_VERTICAL=60.0 # 세로형 비디오 기본 길이 (초) TEMPLATE_ID_HORIZONTAL=your_template_id # 가로형(16:9) 비디오 템플릿 ID TEMPLATE_DURATION_HORIZONTAL=20.0 # 가로형 비디오 기본 길이 (초) # ================================ # JWT 토큰 설정 # ================================ JWT_SECRET=your_secret_key # JWT 서명용 비밀키 (랜덤 문자열 권장) JWT_ALGORITHM=HS256 # JWT 알고리즘 (기본: HS256) JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60 # Access Token 만료 시간 (분) JWT_REFRESH_TOKEN_EXPIRE_DAYS=7 # Refresh Token 만료 시간 (일) # ================================ # 프롬프트 설정 # ================================ PROMPT_FOLDER_ROOT=./app/utils/prompts # 프롬프트 파일 루트 디렉토리 MARKETING_PROMPT_NAME=marketing_prompt # 마케팅 분석용 프롬프트 파일명 SUMMARIZE_PROMPT_NAME=summarize_prompt # 요약용 프롬프트 파일명 LYLIC_PROMPT_NAME=lyric_prompt # 가사 생성용 프롬프트 파일명 # ================================ # 로그 설정 # ================================ LOG_CONSOLE_ENABLED=True # 콘솔 로그 출력 여부 LOG_FILE_ENABLED=True # 파일 로그 저장 여부 LOG_LEVEL=DEBUG # 전체 로그 레벨 (DEBUG, INFO, WARNING, ERROR, CRITICAL) LOG_CONSOLE_LEVEL=DEBUG # 콘솔 출력 로그 레벨 LOG_FILE_LEVEL=DEBUG # 파일 저장 로그 레벨 LOG_MAX_SIZE_MB=15 # 로그 파일 최대 크기 (MB) LOG_BACKUP_COUNT=30 # 로그 백업 파일 보관 개수 LOG_DIR=logs # 로그 저장 디렉토리 경로 # - 절대 경로: 해당 경로 사용 # - 상대 경로: 프로젝트 루트 기준 # - /www/log/uvicorn 존재 시: 자동으로 해당 경로 사용 (운영) ``` ## 실행 방법 ### uv 설치 ```bash # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 의존성 설치 ```bash # 기본 설치 (uv가 자동으로 가상환경 생성) uv sync # 이미 venv를 만든 경우 (기존 가상환경 활성화 필요) uv sync --active ``` ### 서버 실행 ```bash # 개발 서버 실행 fastapi dev main.py # 프로덕션 서버 실행 fastapi run main.py ``` ## API 문서 서버 실행 후 `/docs` 에서 Scalar API 문서를 확인할 수 있습니다. ## 서버 아키텍처 ### 전체 시스템 흐름 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Client (Web/Mobile) │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ FastAPI Application │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Auth API │ │ Home API │ │ Lyric API │ │ Song/Video API │ │ │ │ (카카오) │ │ (크롤링) │ │ (가사생성) │ │ (음악/영상 생성) │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ └─────────┼────────────────┼────────────────┼─────────────────────┼───────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ Kakao OAuth │ │ Naver Maps │ │ ChatGPT │ │ External AI Services │ │ (로그인) │ │ (크롤링) │ │ (OpenAI) │ │ ┌───────┐ ┌──────────┐ │ └─────────────────┘ └─────────────┘ └─────────────┘ │ │ Suno │ │Creatomate│ │ │ │ (음악) │ │ (영상) │ │ │ └───────┘ └──────────┘ │ └─────────────────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Data Layer │ │ ┌─────────────┐ ┌─────────────────────┐ │ │ │ MySQL │ │ Azure Blob Storage │ │ │ │ (메인 DB) │ │ (미디어 저장소) │ │ │ └─────────────┘ └─────────────────────┘ │ │ ┌─────────────┐ │ │ │ Redis │ │ │ │ (캐시/세션) │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 광고 콘텐츠 생성 플로우 ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 1. 입력 │───▶│ 2. 크롤링 │───▶│ 3. 가사 │───▶│ 4. 음악 │───▶│ 5. 영상 │ │ │ │ │ │ 생성 │ │ 생성 │ │ 생성 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │장소 URL │ │Naver Maps│ │ ChatGPT │ │ Suno AI │ │Creatomate│ │or 이미지 │ │ 크롤러 │ │ API │ │ API │ │ API │ └────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │장소 정보 │ │ 광고 가사 │ │ MP3 │ │ 광고 영상 │ │이미지 수집 │ │ 텍스트 │ │ 파일 │ │ 파일 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ``` ### 인증 플로우 (카카오 OAuth) ``` ┌────────┐ ┌────────────┐ ┌───────────┐ ┌────────────┐ │ Client │ │ CastAD │ │ Kakao │ │ MySQL │ │ │ │ Backend │ │ OAuth │ │ │ └───┬────┘ └─────┬──────┘ └─────┬─────┘ └─────┬──────┘ │ │ │ │ │ 1. 로그인 요청 │ │ │ │───────────────▶│ │ │ │ │ │ │ │ 2. 카카오 URL │ │ │ │◀───────────────│ │ │ │ │ │ │ │ 3. 카카오 로그인 │ │ │ │────────────────────────────────▶ │ │ │ │ │ │ │ 4. 인가 코드 │ │ │ │◀──────────────────────────────── │ │ │ │ │ │ │ 5. 콜백 (code) │ │ │ │───────────────▶│ 6. 토큰 요청 │ │ │ │─────────────────▶│ │ │ │ 7. Access Token │ │ │ │◀─────────────────│ │ │ │ │ │ │ │ 8. 사용자 저장/조회 │ │ │ │─────────────────────────────────▶ │ │ │◀───────────────────────────────── │ │ │ │ │ │ 9. JWT 토큰 발급 │ │ │ │◀───────────────│ │ │ │ │ │ │ ```