o2o-castad-backend/README.md

CastAD Backend

AI 기반 광고 음악 생성 서비스의 백엔드 API 서버입니다.

기술 스택

• Framework: FastAPI
• Database: MySQL (asyncmy 비동기 드라이버)
• ORM: SQLAlchemy (async)
• AI Services:
  • OpenAI ChatGPT (가사 생성, 마케팅 분석)
  • Suno AI (음악 생성)

프로젝트 구조

app/
├── core/           # 핵심 설정 및 공통 모듈
├── database/       # 데이터베이스 세션 및 설정
├── home/           # 홈 API (크롤링, 영상 생성 요청)
├── lyric/          # 가사 API (가사 생성)
├── song/           # 노래 API (Suno AI 음악 생성)
├── 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}	노래 생성 상태 조회 (폴링)
GET	/song/download/{task_id}	생성된 노래 MP3 다운로드

환경 설정

.env 파일에 다음 환경 변수를 설정합니다:

# 프로젝트 설정
PROJECT_NAME=CastAD
PROJECT_DOMAIN=localhost:8000
DEBUG=True

# MySQL 설정
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_user
MYSQL_PASSWORD=your_password
MYSQL_DB=castad

# API Keys
CHATGPT_API_KEY=your_openai_api_key
SUNO_API_KEY=your_suno_api_key
SUNO_CALLBACK_URL=https://your-domain.com/api/suno/callback

실행 방법

uv 설치

# 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

의존성 설치

# 기본 설치 (uv가 자동으로 가상환경 생성)
uv sync

# 이미 venv를 만든 경우 (기존 가상환경 활성화 필요)
uv sync --active

서버 실행

# 개발 서버 실행
fastapi dev main.py

# 프로덕션 서버 실행
fastapi run main.py

API 문서

서버 실행 후 /docs 에서 Scalar API 문서를 확인할 수 있습니다.