Magic Chords 공개 API

코드 인식, 가사 전사, 악보 내보내기를 위한 버전 관리되는 REST API입니다. 모든 엔드포인트는 /api/v1/ 아래에 있으며 JSON을 주고받고(업로드·생성 파일 제외) 공정 사용 한도 내에서 익명 개발자에게 열려 있습니다.

모든 엔드포인트는 구현에서 직접 생성되어 항상 최신 상태로 유지되는 아래의 내장 레퍼런스에서 대화형으로 확인할 수 있습니다.

동작 방식

분석과 전사는 비동기로 실행됩니다. 작업을 제출하면 job_id를 받고, 상태를 확인한 뒤 처리가 끝나면 전체 결과를 가져옵니다.

빠른 시작

곡 URL로 코드 분석을 제출합니다:

curl -X POST https://magic-chords.dev/api/v1/analyze/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

응답에 작업 핸들이 포함됩니다:

{"job_id": "bBm3Zx8kQ7...", "status": "processing"}

상태가 complete가 될 때까지 폴링:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7...

코드, 템포, 키, 구조를 가져옵니다:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../result

또는 내보낸 파일을 바로 다운로드(pdf, midi, musicxml, txt, csv, json):

curl -o chords.pdf \
  "https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../export?format=pdf"

URL 대신 로컬 오디오 파일을 분석하려면:

curl -X POST https://magic-chords.dev/api/v1/analyze \
  -F "file=@song.mp3"

엔드포인트

메서드와 경로	용도
`POST /api/v1/analyze`	업로드한 오디오로 코드 분석 제출 (multipart 폼)
`POST /api/v1/analyze/url`	미디어 URL로 코드 분석 제출
`POST /api/v1/transcribe`	업로드한 오디오로 가사 전사 제출
`POST /api/v1/transcribe/url`	미디어 URL로 가사 전사 제출
`GET /api/v1/jobs/{job_id}`	폴링용 간결한 상태
`GET /api/v1/jobs/{job_id}/result`	전체 결과(코드, 단어, 템포, 키…)
`GET /api/v1/jobs/{job_id}/export?format=…`	완료된 분석을 pdf/midi/musicxml/txt/csv/json으로 내보내기
`GET /api/v1/limits`	현재 쿼터 정책(과금 없음)

사용량 제한

익명 클라이언트는 IP별로 제한됩니다. 현재 기본값(/api/v1/limits에서도 확인 가능):

버킷	제한
작업 제출 (heavy)	시간당 20건 / 클라이언트
상태·결과·내보내기 조회 (light)	분당 60회 / 클라이언트
동시 실행 작업	클라이언트당 2건

측정되는 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더가 포함됩니다. 한도에 도달하면 Retry-After 헤더와 함께 429가 반환되므로 준수해 주세요.

오류

상태	의미
`400`	잘못된 요청(잘못된 URL, 알 수 없는 형식)
`404`	알 수 없는 job_id
`409`	작업이 존재하지만 완료되지 않았거나 내보낼 수 없음
`413`	업로드가 최대 크기를 초과
`415`	오디오로 인식되지 않는 파일
`429`	요청 한도 또는 동시성 한도 초과
`503`	일시적으로 사용 불가(쿼터 백엔드 중단)

참고 사항

job_id는 기능 토큰처럼 취급하세요. 가진 사람은 누구나 결과를 읽을 수 있습니다.
URL은 공개적으로 접근 가능한 호스트여야 하며 내부 주소는 거부됩니다.
내보내기에는 완료된 코드 분석이 필요하며, 전사 전용 작업은 아직 내보낼 수 없습니다.
YouTube 쿠키 인증은 공개 API에서 사용할 수 없습니다.
악용 방지를 위해 클라이언트 IP가 기록될 수 있습니다.
교차 출처 브라우저 접근은 기본적으로 비활성화되어 있으며, 운영자가 PUBLIC_API_CORS_ORIGINS로 허용할 수 있습니다.

대화형 API 레퍼런스

전체 레퍼런스가 아래에 로드됩니다 — 모든 엔드포인트를 살펴보고 이 페이지에서 직접 요청을 해볼 수 있습니다.

대화형 레퍼런스를 불러오는 중…