유튜브 다운로드 도우미
서포트 서버

Developer

문서

유튜브 다운로드 도우미의 화면, API, 실행 환경, 오류 응답을 정리한 개발 문서입니다.

개요

이 서비스는 YouTube URL을 입력받아 MP3 또는 MP4 파일로 내려받을 수 있도록 FastAPI 기반 API를 제공합니다. 웹 화면은 동일한 API를 호출하며, 서버는 요청 처리 중 생성된 임시 파일을 응답 완료 1분 후 삭제합니다.

상태 확인

GET /api/health 서비스 상태, 서비스 이름, ffmpeg 감지 여부를 반환합니다. 
{
  "ok": true,
  "service": "mlkc-youtube-downloader",
  "ffmpeg_detected": true
}

다운로드 요청

POST /api/download YouTube URL과 다운로드 형식을 받아 파일 응답을 반환합니다.

요청 본문은 JSON 형식이며, format은 mp3 또는 mp4만 사용할 수 있습니다.

{
  "url": "https://www.youtube.com/watch?v=...",
  "format": "mp4"
}

성공 응답

다운로드가 성공하면 application/octet-stream 파일 응답을 반환합니다. 파일명은 영상 ID, 제목, 업로더 정보를 기반으로 생성되며 Windows 파일명에 사용할 수 없는 문자는 안전하게 치환됩니다.

오류 응답

요청 실패 시 JSON 응답으로 ok, message를 반환합니다. 고객지원 이동이 필요한 오류에는 redirect_url이 포함될 수 있습니다.

400 URL 누락, 지원하지 않는 형식, 유효하지 않은 YouTube 링크
503 쿠키 설정 오류, YouTube 인증 필요, ffmpeg 감지 실패
500 예상하지 못한 다운로드 처리 오류

서버 환경 변수

  • PORT: 개발 실행 또는 server.py 실행 포트
  • HOST: 프로덕션 실행 바인딩 주소
  • WEB_CONCURRENCY: uvicorn worker 수
  • FFMPEG_LOCATION 또는 FFMPEG_PATH: ffmpeg/ffprobe 위치
  • YTDLP_COOKIES_FILE: Netscape 형식 쿠키 파일 경로
  • YTDLP_COOKIES_FROM_BROWSER: 브라우저 쿠키 직접 사용 설정
  • DISCORD_SUPPORT_URL: 서포트 서버 버튼 링크

실행 예시

python -m pip install -r requirements.txt
python server.py

개발 중에는 uvicorn app:app --host 0.0.0.0 --port 5000 --reload 명령을 사용할 수 있습니다.