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

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만 사용할 수 있습니다. youtu.be 단축 링크도 지원하지만, @handle을 포함한 채널 링크와 재생목록은 지원하지 않습니다.

{
  "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 명령을 사용할 수 있습니다.