Jam Jam
완전히 동일한 엔진을 사용하는 REST API
이 API는 jam-jam.org/api/v1에 있으며, 웹 앱과 모바일 앱, jam-jam.org/app/convert와 똑같은 처리 과정을 거칩니다. 어디에서 보내든 같은 코드를 거쳐 같은 결과를 얻습니다. 실제 curl과 Python 예제, 키 발급 방법을 포함한 전체 문서는 jam-jam.org/developers에 있습니다. 기계가 읽을 수 있는 OpenAPI 3.1 명세서(jam-jam.org/api/v1/openapi.json)에는 에이전트나 스크립트를 위한 권장 호출 순서가 포함되어 있고, jam-jam.org/llms.txt는 이를 직접 읽는 어시스턴트를 위해 아래의 모든 기능을 나열합니다. 공식 MCP(Model Context Protocol) 서버인 @jam-jam/convert-mcp는 같은 API를 list_formats, convert_file, convert_text, get_job, get_usage라는 다섯 가지 도구로 제공하여 Claude Desktop, Claude Code, Cursor 같은 MCP 지원 에이전트가 바로 사용할 수 있습니다.
키 하나, 한도 하나, 줄 설 필요 없음
GET /formats 호출은 인증이 전혀 필요 없으며, 이 서버가 현재 지원하는 모든 형식과 크기·길이 제한을 돌려주므로 스크립트가 업로드 전에 미리 확인할 수 있습니다. 그 외 모든 요청은 Authorization: Bearer 헤더가 필요하며, Supabase 세션 토큰이나 jj_live_로 시작하는 개인 API 키(앱 내 설정 > API 키에서 무료로 생성) 중 하나를 사용합니다. 키가 없으면 익명 요청으로 처리되어 이동하는 24시간마다 3회까지 변환할 수 있습니다. 무료 계정은 송북의 내보내기·가져오기가 이미 사용하는 것과 같은 주 10회 한도로 올라가고, Premium은 월 500회까지 올라갑니다. 한도를 소비하는 모든 응답에는 정확한 잔여량을 담은 X-Quota-* 헤더가 붙으며, 업로드한 파일과 결과물은 작업 성공 여부와 관계없이 생성 24시간 뒤에 삭제됩니다.
작업을 제출하고, 폴링하거나 스트리밍으로 확인
변환은 즉시 응답이 아니라 하나의 작업입니다. 파일을 multipart/form-data로, 또는 URL이나 붙여넣은 텍스트를 JSON으로 POST /jobs에 보내면 작업 id가 담긴 202 응답이 돌아옵니다. 이후 GET /jobs/{id}로 상태를 폴링하거나(Retry-After 헤더를 지키면서), GET /jobs/{id}/events로 같은 작업의 Server-Sent Events 스트림을 열어 매번 물어보는 대신 기다리는 스크립트에 대응할 수 있습니다. phase가 done에 이르면 GET /jobs/{id}/result로 완성된 파일을 내려받거나, GET /jobs/{id}/result/songbook으로 Jam Jam 고유의 JSON 피벗(코드, 가사, 섹션, 조성, 템포)을 바로 읽을 수 있습니다. 모든 오류는 단순한 상태 코드가 아니라 표준 application/problem+json 형식으로 돌아옵니다.
입력: 녹음, 링크, 스캔, 사진
오디오나 비디오 파일은 코드, 가사, 조성, 템포가 이미 분석된 송북이 됩니다. 앱이 실시간 마이크나 업로드된 녹음에 대해 수행하는 것과 같은 인식입니다. 여기서 바로 생성된 카라오케 영상이나 반주 트랙으로 이어질 수 있습니다. URL로 붙여넣은 페이지나 검색어는 앱 안의 탭 사이트와 같은 방식으로 읽힙니다. PDF나 사진, 인쇄된 코드 악보, 스캔한 악보, 송북 전체, 기타 탭, 심지어 휴대폰으로 찍은 화이트보드 사진까지 OCR과 광학 악보 인식을 거쳐 같은 피벗으로 들어갑니다. 원본 오디오 자체를 악보나 탭으로 바꾸는 방향은 아직 품질 관문 뒤에 있어서, 실시간 녹음이 아니라 이미 멜로디를 담고 있는 소스가 필요합니다.
입력: 이미 가지고 있는 텍스트와 악보
ChordPro와 OnSong 파일, 코드나 가사 또는 ASCII 탭이 담긴 일반 텍스트, Word나 RTF 문서, 프레젠테이션 슬라이드, 스프레드시트나 CSV 세트리스트, 붙여넣은 웹페이지의 HTML까지 모두 같은 송북으로 변환됩니다. 코드 악보는 한 가지 형태로만 오는 경우가 드물기 때문입니다. MusicXML과 MIDI 파일은 자체 음표와, 있다면 가사까지 가져옵니다. Guitar Pro나 MuseScore 프로젝트 파일(.gp, .gpx, .mscz 및 관련 확장자)도 베타로 같은 방식으로 송북에 도달합니다. 동기화된 가사 파일(.lrc, .srt, .vtt, .ass)은 타이밍을 가져오고, .jamsong 파일이나 압축된 내보내기는 Jam Jam을 떠날 때와 정확히 같은 상태로 손실 없이 다시 가져와집니다.
출력: 작업에 실제로 필요한 어떤 형식이든
같은 송북에서 API는 코드 PDF, 가사 PDF, 빈 그리드, PNG 이미지, HTML 페이지, 일반 텍스트, ChordPro, chords-lab이나 chords-csv 코드 주석, 또는 조성과 템포만을 내보낼 수 있습니다. 조옮김한 버전이나 카포 버전, 기타·우쿨렐레·피아노 등 Jam Jam이 지원하는 악기의 코드 다이어그램, .lrc나 .srt 동기화 가사, 카라오케 영상, 생성된 반주 트랙, 손실 없는 .jamsong 파일(요청 시 인쇄용 레이아웃도)도 가능합니다. MusicXML, MIDI, Guitar Pro 프로젝트, 스캔한 악보, 탭처럼 원본 오디오가 아니라 이미 멜로디를 담은 소스에서 가져온 경우에는, 같은 송북이 악보, 기타 탭 PDF, MIDI, MusicXML로도 내보내지며 뒤의 두 가지는 Premium에서 제공됩니다.
Jam Jam 변환 파이프라인의 전체 그림은 다음 글에서 확인하세요: 범용 파일 변환 소개 글.
API에 대해 자주 묻는 질문
Jam Jam API란 무엇인가요?
jam-jam.org/api/v1에 있는 공개 REST API로, Jam Jam 고유의 변환 엔진을 그대로 실행합니다. 오디오 파일, PDF, 사진, 링크, MIDI, MusicXML, ChordPro, 일반 텍스트 등을 보내면 구조화된 송북(코드, 가사, 조성, 템포)이나 PDF, 카라오케 영상, 반주 트랙 같은 다른 형식의 결과물을 돌려받습니다.
API는 무료로 쓸 수 있나요?
네, 한도 내에서 무료입니다. 익명 요청은 이동하는 24시간마다 3회, 무료 계정은 주 10회, Premium은 월 500회까지 사용할 수 있습니다. 업로드한 파일과 결과물은 작업 실행 24시간 뒤에 삭제됩니다.
API가 오디오 파일을 코드와 가사로 바꿀 수 있나요?
네. output: songbook으로 오디오나 비디오 파일을 보내면 시간이 찍힌 코드, 조성, 템포, 가사를 돌려받습니다. 앱 자체가 수행하는 것과 같은 인식입니다. 원본 오디오로부터의 완전한 멜로디 악보화(MIDI, MusicXML, 오선보, 탭)는 여기에 포함되지 않으며, 이미 멜로디를 담은 소스가 필요합니다.
AI 에이전트를 위한 MCP 서버가 있나요?
네, @jam-jam/convert-mcp가 같은 API를 list_formats, convert_file, convert_text, get_job, get_usage라는 다섯 가지 도구로 제공하여 Claude Desktop, Claude Code, Cursor 같은 MCP 지원 에이전트가 직접 호출할 수 있습니다.
API 키는 어디서 받나요?
무료 Jam Jam 계정을 만든 뒤 앱(모바일 또는 웹)에서 설정 > API 키를 열어 생성하세요. 키는 한 번만 표시되고 jj_live_로 시작하며 언제든 취소할 수 있습니다. 계정당 최대 5개까지 발급할 수 있습니다.
실제 curl과 Python 예제가 담긴 전체 레퍼런스는 jam-jam.org/developers에서 확인하세요: