MusicToMIDI API

Convert an audio file to MIDI or separate it into stems (vocals, drums, bass, guitar, piano, other), from a script, an app or an AI agent.

ReferenceOpenAPI 3.1 (openapi.json)

Prompt for AI agents

# MusicToMIDI API

Convert a local audio file into MIDI, or separate it into instrument stems (vocals, drums, bass,
guitar, piano, other), from any script or AI agent.

- Base URL: https://api.musictomidi.com/v1
- Auth: `Authorization: Bearer mtm_prod_…` (create a key on https://musictomidi.com/developers, keep it secret; shown only once)
- Test keys `mtm_test_…`: same API, no conversion, no credits, always the same sample result after a few seconds
- Account and credits: free credits come with the musictomidi.com account (no card required);
  jobs are debited only when they succeed, failed jobs are refunded.
- Retention: uploaded files and results are kept 24 hours, then deleted.

Documentation

- Guides and examples: https://musictomidi.com/developers
- OpenAPI 3.1 (machine-readable): https://api.musictomidi.com/developers/openapi.json

Endpoints (v1)

- POST /v1/files: get a presigned upload URL {fileKey, uploadUrl, headers, expiresAt}
- POST /v1/jobs: start MIDI conversion or stem separation {operation, model, fileKey}; answers as soon as the file
  is sent: 202 {jobId, status "validating"}
- GET /v1/jobs/{id}: poll (answers at once; poll every 2-3 s): status validating (the file is being checked) →
  starting (waiting for a GPU or a server, or the converter is starting) → running (with progress 0-1 and stage) →
  done; or failed|expired. An unreadable file (input_file_error), a selection past the end of the file
  (invalid_request) or missing credits (insufficient_credits) make the job failed, with error.code
- GET /v1/account: credits and quotas

Models: operation=midi → v1, v2, v3, multitrack_transformer, vocal_transformer (singing voice), multitrack;
operation=separation → model=separation (stems vocals, drums, bass, guitar, piano, other, instrumental, backing;
formats flac and/or mp3)

Options (an option you do not send keeps its default; one useless for the model → 400 option_not_supported):
- top level: startSeconds + endSeconds (selection: only it is converted and paid), tempoKey (fileKey of the full
  mix, MIDI); no url: every job sends its file, so results always carry audioUrl
- options (MIDI): quantization grid|follow|none|legacy, quantizeStrength 0-1, detectBPM true|false, minNoteMs 0-500,
  timingGrid/durationGrid (v1, v2), noteBias -2..2 (v3, multitrack), isolate (vocal_transformer),
  device cpu|gpu (multitrack_transformer, vocal_transformer; cpu never waits for a GPU)

Idempotency: send an `Idempotency-Key` header (8-255 chars) on POST /v1/jobs; a replayed identical request
returns the same job and is never billed twice.

Errors are machine-readable: {"error": {"code": "…", "message": "…", "details": {…}}}.

Maintenance: while a server is updated, it may be "paused": POST /v1/jobs stays ACCEPTED (202, status
"validating", with an immediate jobId), the file is checked, then the job waits (status "starting", queuedReason
"maintenance"); status routes keep answering; another server, or the updated one, launches it. The client just
polls its original jobId.
GET /ready answers 503 on a paused server.

GPU capacity: v3, multitrack_transformer, vocal_transformer, multitrack and separation run on shared GPUs (not with
device cpu). Once its file is checked, a job waits while all are busy: status "starting" with queuedReason
"gpu_capacity"; it starts by itself when a GPU frees up.

Minimal flow

```bash
# 1. send the audio file (request body) and start the job (parameters in the URL)
curl -s -X POST "https://api.musictomidi.com/v1/jobs?name=song.wav&operation=midi&model=v2" -H "Authorization: Bearer $MTM_API_KEY" -H "Idempotency-Key: midi-$(date +%s)-$RANDOM" -H 'Content-Type: application/octet-stream' --data-binary @song.wav
# 2. poll GET /v1/jobs/{jobId} until status "done", then download results (24-hour validity)
```

URL parameters: name (file name, required), operation, model, startSeconds, endSeconds, tempoKey, MIDI options by
name (noteThreshold=0.5, quantization=grid, detectBPM=false…), stems=vocals,instrumental, formats=flac,mp3 and
mp3=true for separation. The file must be readable audio (otherwise the job is failed with input_file_error), up
to 4 GB. The JSON way still works: POST /v1/files, PUT the bytes to uploadUrl, then POST /v1/jobs
with {"fileKey","operation","model"}.

The file and JSON parameters in one request (multipart/form-data): the audio in a file part "file", the
parameters as JSON in a text part "params" (the JSON body without fileKey: operation, model, options, stems, mp3,
formats, startSeconds, endSeconds, tempoKey, and optionally name, by default the file name). Same JSON response.

```bash
curl -s -X POST "https://api.musictomidi.com/v1/jobs" -H "Authorization: Bearer $MTM_API_KEY" -F file=@song.wav -F 'params={"operation":"midi","model":"v2","options":{"noteThreshold":0.5}}'
```

Manage your API keys

Code examples

Convert to MIDI

Model settings
#!/bin/bash
# Needs only curl, grep and sed
API=https://api.musictomidi.com/v1
KEY="YOUR_API_KEY"
AUDIOFILE_NAME="song.wav"
OPERATION="midi"
MODEL="v2"

# Job parameters, in JSON (MIDI options go in "options", e.g. "options":{"noteThreshold":0.5})
PARAMS="{\"operation\":\"$OPERATION\",\"model\":\"$MODEL\"}"
# Value of a JSON string field: echo "$JSON" | field name
field() { sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p"; }
# Log line, with the elapsed time: log "text"
log() { echo "[${SECONDS}s] $*"; }
# Download a URL to a file: download "$URL" "name"
download() { log "Downloading $2..."; curl -s "$1" > "$2"; log "Saved $2"; }
# JSON string of a text, non-ASCII characters as \uXXXX: curl in Git Bash (Windows) reads only ASCII arguments
json() {
  local LC_ALL=C s="$1" out="" i=0 b n k c
  while ((i < ${#s})); do
    c="${s:i:1}"; printf -v b '%d' "'$c"; i=$((i + 1))
    if ((b >= 128)); then
      # UTF-8: 2 to 4 bytes per character
      if ((b >= 240)); then n=$((b & 7)); k=3; elif ((b >= 224)); then n=$((b & 15)); k=2; else n=$((b & 31)); k=1; fi
      for ((; k > 0; k--)); do printf -v b '%d' "'${s:i:1}"; i=$((i + 1)); n=$(((n << 6) | (b & 63))); done
      if ((n > 65535)); then n=$((n - 65536)); printf -v c '\\u%04x\\u%04x' $((0xD800 + (n >> 10))) $((0xDC00 + (n & 1023)))
      else printf -v c '\\u%04x' "$n"; fi
    elif ((b < 32)); then printf -v c '\\u%04x' "$b"
    elif [[ $c == '"' || $c == "\\" ]]; then c="\\$c"
    fi
    out+="$c"
  done
  printf '"%s"' "$out"
}
# File name in the parameters, in any language (Chinese, Thai, Arabic...)
PARAMS="{\"name\":$(json "$AUDIOFILE_NAME"),${PARAMS#\{}"

# 1. Send the audio file and its parameters in one request (multipart/form-data): the file in the
#    "file" part, the parameters in the "params" part (credits are reserved, debited only on success)
log "Uploading $AUDIOFILE_NAME (operation: $OPERATION, model: $MODEL)..."
# The file is read by bash and sent on stdin (any file name)
JOB=$(curl -# -X POST "$API/jobs" \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: midi-$(date +%s)-$RANDOM" \
  -F "file=@-;filename=audio.${AUDIOFILE_NAME##*.}" -F "params=$PARAMS" < "$AUDIOFILE_NAME")
JOBID=$(echo "$JOB" | field jobId)
[ -z "$JOBID" ] && { echo "$JOB"; exit 1; }
log "Job created: $JOBID (status: $(echo "$JOB" | field status))"

# 2. Poll until done ("validating", "starting" and "running" are not final)
POLLING_URL=$API/jobs/$JOBID

while :; do
  RESULT=$(curl -s "$POLLING_URL" -H "Authorization: Bearer $KEY")
  STATUS=$(echo "$RESULT" | field status)
  PROGRESS=$(echo "$RESULT" | sed -n "s/.*\"progress\":\([0-9.]*\).*/\1/p")
  [ -n "$PROGRESS" ] && PROGRESS=" $(LC_ALL=C printf "%.0f" "${PROGRESS}e2")%"
  STAGE=$(echo "$RESULT" | field stage)
  # Why a job is waiting to start: gpu_capacity (all GPUs busy) or maintenance
  REASON=$(echo "$RESULT" | field queuedReason)
  log "Status: $STATUS$PROGRESS${STAGE:+ ($STAGE)}${REASON:+ ($REASON)}"
  case "$STATUS" in
    done) break ;;
    validating|starting|running) sleep 3 ;;
    *) echo "$RESULT"; exit 1 ;;
  esac
done

# 3. Download the results (signed URLs, valid 24 h), named after the audio file
# Smart MIDI: notes quantized on the tempo detected automatically ("bpm")
download "$(echo "$RESULT" | field midiUrl)" "${AUDIOFILE_NAME%.*}.mid"
# Raw MIDI: output of the model, before filtering and quantization
download "$(echo "$RESULT" | field rawMidiUrl)" "${AUDIOFILE_NAME%.*}.raw.mid"
# Original audio: the file you sent ("audioUrl")
download "$(echo "$RESULT" | field audioUrl)" "${AUDIOFILE_NAME%.*}.original.${AUDIOFILE_NAME##*.}"

Separate into stems

Stems
#!/bin/bash
# Needs only curl, grep and sed
API=https://api.musictomidi.com/v1
KEY="YOUR_API_KEY"
AUDIOFILE_NAME="song.wav"

# Job parameters, in JSON
PARAMS='{"operation":"separation","model":"separation","stems":["vocals","drums"],"mp3":true}'
# Value of a JSON string field: echo "$JSON" | field name
field() { sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p"; }
# Log line, with the elapsed time: log "text"
log() { echo "[${SECONDS}s] $*"; }
# Download a URL to a file: download "$URL" "name"
download() { log "Downloading $2..."; curl -s "$1" > "$2"; log "Saved $2"; }
# JSON string of a text, non-ASCII characters as \uXXXX: curl in Git Bash (Windows) reads only ASCII arguments
json() {
  local LC_ALL=C s="$1" out="" i=0 b n k c
  while ((i < ${#s})); do
    c="${s:i:1}"; printf -v b '%d' "'$c"; i=$((i + 1))
    if ((b >= 128)); then
      # UTF-8: 2 to 4 bytes per character
      if ((b >= 240)); then n=$((b & 7)); k=3; elif ((b >= 224)); then n=$((b & 15)); k=2; else n=$((b & 31)); k=1; fi
      for ((; k > 0; k--)); do printf -v b '%d' "'${s:i:1}"; i=$((i + 1)); n=$(((n << 6) | (b & 63))); done
      if ((n > 65535)); then n=$((n - 65536)); printf -v c '\\u%04x\\u%04x' $((0xD800 + (n >> 10))) $((0xDC00 + (n & 1023)))
      else printf -v c '\\u%04x' "$n"; fi
    elif ((b < 32)); then printf -v c '\\u%04x' "$b"
    elif [[ $c == '"' || $c == "\\" ]]; then c="\\$c"
    fi
    out+="$c"
  done
  printf '"%s"' "$out"
}
# File name in the parameters, in any language (Chinese, Thai, Arabic...)
PARAMS="{\"name\":$(json "$AUDIOFILE_NAME"),${PARAMS#\{}"

# 1. Send the audio file and its parameters in one request (multipart/form-data): the file in the
#    "file" part, the parameters in the "params" part (credits are reserved, debited only on success)
log "Uploading $AUDIOFILE_NAME (operation: separation)..."
# The file is read by bash and sent on stdin (any file name)
JOB=$(curl -# -X POST "$API/jobs" \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: stems-$(date +%s)-$RANDOM" \
  -F "file=@-;filename=audio.${AUDIOFILE_NAME##*.}" -F "params=$PARAMS" < "$AUDIOFILE_NAME")
JOBID=$(echo "$JOB" | field jobId)
[ -z "$JOBID" ] && { echo "$JOB"; exit 1; }
log "Job created: $JOBID (status: $(echo "$JOB" | field status))"

# 2. Poll until done ("validating", "starting" and "running" are not final)
POLLING_URL=$API/jobs/$JOBID

while :; do
  RESULT=$(curl -s "$POLLING_URL" -H "Authorization: Bearer $KEY")
  STATUS=$(echo "$RESULT" | field status)
  PROGRESS=$(echo "$RESULT" | sed -n "s/.*\"progress\":\([0-9.]*\).*/\1/p")
  [ -n "$PROGRESS" ] && PROGRESS=" $(LC_ALL=C printf "%.0f" "${PROGRESS}e2")%"
  STAGE=$(echo "$RESULT" | field stage)
  # Why a job is waiting to start: gpu_capacity (all GPUs busy) or maintenance
  REASON=$(echo "$RESULT" | field queuedReason)
  log "Status: $STATUS$PROGRESS${STAGE:+ ($STAGE)}${REASON:+ ($REASON)}"
  case "$STATUS" in
    done) break ;;
    validating|starting|running) sleep 3 ;;
    *) echo "$RESULT"; exit 1 ;;
  esac
done

# 3. Download each stem: FLAC, and MP3 with mp3=true (signed URLs, valid 24 h)
echo "$RESULT" | grep -o '{[^{}]*"url":"[^{}]*}' | while read -r STEM; do
  NAME=$(echo "$STEM" | field name)
  download "$(echo "$STEM" | field url)" "$NAME.flac"
  MP3=$(echo "$STEM" | field mp3Url)
  [ -n "$MP3" ] && download "$MP3" "$NAME.mp3"
done
# Original audio: the file you sent ("audioUrl")
download "$(echo "$RESULT" | field audioUrl)" "${AUDIOFILE_NAME%.*}.original.${AUDIOFILE_NAME##*.}"

Wait for a job (HTTP polling)

#!/bin/bash
# Needs only curl, grep and sed
# Usage: ./poll-job.sh <jobId>   (the jobId returned by POST /v1/jobs)
API=https://api.musictomidi.com/v1
KEY="YOUR_API_KEY"
# Value of a JSON string field: echo "$JSON" | field name
field() { sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p"; }
# Log line, with the elapsed time: log "text"
log() { echo "[${SECONDS}s] $*"; }

# Each GET may wait up to ~20 s; "validating", "starting" and "running" are not final
while :; do
  RESULT=$(curl -s "$API/jobs/$1" -H "Authorization: Bearer $KEY")
  STATUS=$(echo "$RESULT" | field status)
  PROGRESS=$(echo "$RESULT" | sed -n "s/.*\"progress\":\([0-9.]*\).*/\1/p")
  [ -n "$PROGRESS" ] && PROGRESS=" $(LC_ALL=C printf "%.0f" "${PROGRESS}e2")%"
  STAGE=$(echo "$RESULT" | field stage)
  # Why a job is waiting to start: gpu_capacity (all GPUs busy) or maintenance
  REASON=$(echo "$RESULT" | field queuedReason)
  log "Status: $STATUS$PROGRESS${STAGE:+ ($STAGE)}${REASON:+ ($REASON)}"
  case "$STATUS" in
    done) echo "$RESULT"; break ;;
    validating|starting|running) sleep 3 ;;
    *) echo "$RESULT"; exit 1 ;;
  esac
done

Pricing, quotas and limits

Cost = 1 credit per started segment of the model duration, computed on the true duration measured by the service (a 100 s file in v2 costs 2 credits: one full minute + one started minute).

ModelOperationCredits / segmentSegment
v1MIDI160 s
v2MIDI160 s
v3MIDI (GPU)145 s
multitrack_transformerMIDI multi-instruments120 s
vocal_transformerMIDI (singing voice)120 s
multitrackseparation + MIDI per stem120 s
separationstems130 s

Credit packs: PRO 500 credits for $4.99, PRO+ 1000 credits for $8.99, STUDIO 10000 credits for $84.99

  • Free credits: included with the account at signup, no card required.
  • Debit: only when the job succeeds; failed and expired jobs are refunded.
  • Concurrency: the total cost of your running jobs can never be more than your credits.
  • GPU capacity: v3, multitrack_transformer, vocal_transformer, multitrack and separation run on shared GPUs. When they are all busy, the job waits with status: starting and queuedReason: gpu_capacity, then starts by itself; keep polling the same jobId.
  • Job creation: POST /v1/jobs answers as soon as the file is uploaded: 202 {jobId, status: "validating", operation, model, credits}. The file is checked after that: an unreadable file, a selection outside the file or not enough credits make the job failed, with error.code input_file_error, invalid_request or insufficient_credits. The jobId never changes, from POST to the result.
  • Rate limit: 60 requests/min/key (429 rate_limited).
  • Keys: up to 5 active keys per account.
  • Retention: 24 h for uploaded files, results and download URLs.
  • Formats: audio MP3, WAV, WAVE, OGG, OGA, OPUS, FLAC, M4A, AAC, ALAC, WMA, AIF, AIFF, AIFC, CAF, AMR, AC3, MKA, WEBA, MP2, AU; video MP4, M4V, MOV, WEBM, MKV, AVI, WMV, FLV, 3GP, 3G2, MPG, MPEG, TS, MTS, M2TS, OGV, VOB (its audio track). The paid duration never exceeds the measured one.
  • MP3: generated by the service (separation mp3:true); the API never transcodes on your device.
  • Polling: GET /v1/jobs/{id}. A request can take up to 20 s: it answers as soon as the job is done. No webhook in v1.

Machine-readable errors

{ "error": { "code": "insufficient_credits",
             "message": "You need 2 credits, but you have only 1.",
             "details": { "cost": 2, "credits": 1 } } }
CodeHTTPMeaning
missing_api_key / invalid_api_key401Send Authorization: Bearer mtm_prod_… (or mtm_test_…); the key is unknown
revoked_api_key401The key has been revoked
rate_limited429Retry later (per-minute limit)
unknown_model / option_not_supported / option_out_of_range400Bad request body
file_not_found / file_forbidden / file_expired404 / 403 / 410Unknown, foreign or elapsed-for-24-h file
input_file_error200, status failedUnreadable or missing audio (found while the job is checked)
invalid_request200, status failedSelection outside the audio file (found while the job is checked)
insufficient_credits200, status failedNot enough credits for this job (found while the job is checked)
idempotency_conflict / idempotency_in_progress409Same Idempotency-Key, different body / first call still starting
job_not_found404Job unknown for this account
result_expired200, status expiredResults are only kept 24 h
upstream_error / storage_unavailable502Conversion or storage temporarily unavailable (never exposes upstream bodies)
pausedGET /ready 503Update in progress: POST /v1/jobs is still accepted, the job waits (status starting, queuedReason: maintenance); /ready answers 503 for load balancers. Queued jobs are launched by another server or after the update; nothing is lost or double-billed