{
  "openapi": "3.1.0",
  "info": {
    "title": "MusicToMIDI API",
    "version": "1.0.0",
    "summary": "Audio to MIDI conversion and stem separation, callable by humans and AI agents",
    "description": "MusicToMIDI converts an audio file into a MIDI file or separates it into instrument stems.\n\n## How it works\n1. Send your file and start the job in **one request**: `POST /v1/jobs?name=song.wav&operation=midi&model=v2` with the audio file as the body, or as `multipart/form-data` with the file and the parameters as JSON (or, in JSON: `POST /v1/files`, `PUT` the file to the presigned URL, then `POST /v1/jobs` with its `fileKey`).\n2. `POST /v1/jobs` starts a conversion (`operation: midi`) or a stem separation (`operation: separation`). It answers as soon as the file is sent, with the `jobId` and `status: validating`: the service then checks the file (readable audio, true duration). Credits are estimated and reserved; a job is **debited only when it succeeds**, and failed jobs are refunded.\n3. `GET /v1/jobs/{jobId}` polls the job: `validating` (the file is being checked) → `starting` (waiting for a GPU or a server, or the converter is starting) → `running` (with `progress` and `stage`) → `done`. An unreadable file (`input_file_error`), a selection past the end of the file (`invalid_request`) or missing credits (`insufficient_credits`) end the job as `failed` with that `error.code`. Result download URLs are valid for **24 hours**, then everything is deleted.\n\n## Authentication\nCreate a key on https://musictomidi.com/developers (Manage your API keys). The complete key is shown **once**. Send it on every request:\n`Authorization: Bearer mtm_prod_…`\n\n## Test mode\nKeys come in two modes, visible in the key: `mtm_prod_…` runs real conversions and uses credits; `mtm_test_…` runs **no conversion and uses no credits**. With a test key the API behaves the same (same routes, validation, errors, idempotency) but the upload URL points to this service (the bytes are discarded) and every job becomes `done` after a few seconds with **always the same sample results** (a MIDI file, and audio stems for separation). Test and production files and jobs never mix.\n\n## GPU capacity\nModels `v3`, `multitrack_transformer`, `vocal_transformer`, `multitrack` and `separation` run on GPUs shared by all users (`multitrack_transformer` and `vocal_transformer` with `options.device: cpu` do not). When they are all busy, a job whose file is checked waits with `status: starting` and `queuedReason: gpu_capacity`; it starts automatically as soon as a GPU is free. Keep polling the same `jobId`.\n\n## Billing\nCredits come from your musictomidi.com account (free credits at signup, no card required). Cost depends on the true audio duration measured by the service and the model. Running jobs of the last 24 hours cannot engage more than your balance.\n\n## Idempotency\nSet an `Idempotency-Key` header (any opaque string of your choice, 8 to 255 chars) on `POST /v1/jobs`. Replaying the same request with the same header returns the same job instead of starting a second one.\n\n## Errors\nMachine-readable: `{\"error\": {\"code\": \"…\", \"message\": \"…\", \"details\": {…}}}`."
  },
  "servers": [
    {
      "url": "https://api.musictomidi.com",
      "description": "Target public URL"
    }
  ],
  "tags": [
    {"name": "Files", "description": "Input files and presigned upload URLs (24-hour retention)"},
    {"name": "Jobs", "description": "MIDI conversion and stem separation"},
    {"name": "Account", "description": "Credits and quotas"}
  ],
  "security": [{"bearerAuth": []}],
  "paths": {
    "/v1/files": {
      "post": {
        "tags": ["Files"],
        "operationId": "createFile",
        "security": [{"bearerAuth": []}],
        "summary": "Create an input file, get a presigned upload URL",
        "description": "Returns `fileKey`, `uploadUrl` (valid 1 hour) and the headers to use on the `PUT`. The file goes directly from you to storage; it is kept 24 hours.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateFileRequest"},
              "examples": {
                "simple": {"value": {"name": "song.wav"}}
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upload URL created.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/FileCreated"},
                "examples": {
                  "simple": {
                    "value": {
                      "name": "song.wav",
                      "contentType": "application/octet-stream",
                      "fileKey": "uploads/vps-1a2b…/song.wav",
                      "uploadUrl": "https://bucket.musictomidi.com/…presigned…",
                      "headers": {"Content-Type": "application/octet-stream"},
                      "expiresAt": "2026-11-07T13:30:00Z",
                      "retentionHours": 24,
                      "next": {"method": "PUT", "description": "Send the audio bytes to uploadUrl with headers."}
                    }
                  }
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "401": {"$ref": "#/components/responses/Generic401"}
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "tags": ["Jobs"],
        "operationId": "createJob",
        "security": [{"bearerAuth": []}],
        "summary": "Start a MIDI conversion or a stem separation",
        "description": "`operation: midi` converts the file to MIDI (`model`: v1, v2, v3, multitrack_transformer, vocal_transformer, multitrack). `operation: separation` returns audio stems (`model: separation`, stems subset with `instrumental` and `backing`, `formats` flac and/or mp3). The true duration is measured by the service (the file is fully decoded); it sets the paid duration (`maxSeconds`). With a selection (`startSeconds` and `endSeconds`), only the selection is converted and paid: `min(endSeconds, duration) − startSeconds` (the job is `failed` with `invalid_request` if it starts after the end of the file). Credits are reserved before launch and debited only on success. An option that is useless for the model is refused (`400 option_not_supported`); an option you do not send keeps its default.\n\n**In one request**: send the audio file as the body (any non-JSON `Content-Type`, e.g. `application/octet-stream`) with the parameters in the URL: `name` (file name, required), `operation`, `model`, `startSeconds`, `endSeconds`, `tempoKey`, the MIDI options by name (`noteThreshold=0.5`, `quantization=grid`, `detectBPM=false`…), and for separation `stems=vocals,instrumental`, `formats=flac,mp3` and `mp3=true`. The job is created as soon as the file is received (`status: validating`); the service then checks that it is readable audio (otherwise the job is `failed` with `input_file_error`), stores it, reserves credits and starts the job. Up to 4 GB (`413 file_too_large`).\n\n**Or in one multipart/form-data request**: 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), e.g. `curl -F file=@song.wav -F 'params={\"operation\":\"midi\",\"model\":\"v2\"}'`. Same checks, same JSON response.\n\n**Or in JSON**: `{\"fileKey\": …}` of a file sent with `POST /v1/files` + `PUT`. A `url` is refused (`400`): every job has its file in the service's storage, so its results always carry `audioUrl`.\n\nAdd an `Idempotency-Key` header to protect replays.",
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {"type": "string", "format": "binary", "description": "The audio file itself; parameters in the URL."}
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "params"],
                "properties": {
                  "file": {"type": "string", "format": "binary", "description": "The audio file (up to 4 GB). Its file name is the job name unless params.name is set."},
                  "params": {"type": "string", "description": "The parameters as a JSON object, like the JSON body without fileKey: operation, model, options, stems, mp3, formats, startSeconds, endSeconds, tempoKey, and optionally name. Example: {\"operation\":\"midi\",\"model\":\"v2\",\"options\":{\"noteThreshold\":0.5}}"}
                }
              }
            },
            "application/json": {
              "schema": {"oneOf": [{"$ref": "#/components/schemas/MidiJobRequest"}, {"$ref": "#/components/schemas/SeparationJobRequest"}]},
              "examples": {
                "midi": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "midi", "model": "v2"}},
                "midiWithOptions": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "midi", "model": "v3", "options": {"noteBias": -1, "minNoteMs": 30}}},
                "separation": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "separation", "model": "separation", "stems": ["vocals", "instrumental"], "mp3": true}},
                "backingTrack": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "separation", "model": "separation", "stems": ["guitar", "backing"], "formats": ["mp3"]}},
                "multitrack": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "midi", "model": "multitrack", "stems": ["vocals", "piano"]}},
                "voiceSelection": {"value": {"fileKey": "uploads/vps-1a2b…/song.wav", "operation": "midi", "model": "vocal_transformer", "startSeconds": 30, "endSeconds": 75, "options": {"isolate": true, "quantization": "grid"}}}
              }
            }
          }
        },
        "parameters": [
          {"$ref": "#/components/parameters/IdempotencyKey"},
          {"name": "name", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 200}, "description": "File name with its extension (e.g. song.wav). Required when the file is the request body."},
          {"name": "operation", "in": "query", "required": false, "schema": {"type": "string", "enum": ["midi", "separation"]}, "description": "With the file as the request body."},
          {"name": "model", "in": "query", "required": false, "schema": {"type": "string"}, "description": "With the file as the request body: v1, v2, v3, multitrack_transformer, vocal_transformer, multitrack or separation."},
          {"name": "stems", "in": "query", "required": false, "schema": {"type": "string"}, "description": "With the file as the request body: comma-separated stems (separation, multitrack)."},
          {"name": "mp3", "in": "query", "required": false, "schema": {"type": "boolean"}, "description": "With the file as the request body: separation only."},
          {"name": "formats", "in": "query", "required": false, "schema": {"type": "string"}, "description": "With the file as the request body: separation only, comma-separated (flac, mp3)."},
          {"name": "startSeconds", "in": "query", "required": false, "schema": {"type": "number", "minimum": 0}, "description": "With the file as the request body: selection start, with endSeconds."},
          {"name": "endSeconds", "in": "query", "required": false, "schema": {"type": "number"}, "description": "With the file as the request body: selection end."},
          {"name": "tempoKey", "in": "query", "required": false, "schema": {"type": "string"}, "description": "With the file as the request body: fileKey of the full mix (MIDI only)."}
        ],
        "responses": {
          "202": {
            "description": "Job created as soon as the file is sent: `status: validating`, the file is checked next (follow it with GET /v1/jobs/{jobId}). Test keys: `status: running` at once, `cost: 0`.",
            "content": {
              "application/json": {
                "schema": {"oneOf": [{"$ref": "#/components/schemas/JobWaiting"}, {"$ref": "#/components/schemas/JobStarted"}]},
                "examples": {
                  "validating": {"value": {"jobId": "e3f4c5…", "status": "validating", "operation": "midi", "model": "v2", "queuedAt": "2026-11-07T12:00:00Z", "credits": 30, "retentionHours": 24, "poll": {"method": "GET", "url": "/v1/jobs/e3f4c5…"}}},
                  "testKey": {"value": {"jobId": "test_1a2b", "operation": "midi", "model": "v2", "status": "running", "testMode": true, "cost": 0, "credits": 30, "retentionHours": 24, "poll": {"method": "GET", "url": "/v1/jobs/test_1a2b"}}}
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "403": {"$ref": "#/components/responses/FileForbidden"},
          "404": {"$ref": "#/components/responses/FileNotFound"},
          "409": {"$ref": "#/components/responses/IdempotencyConflict"},
          "410": {"$ref": "#/components/responses/FileExpired"},
          "401": {"$ref": "#/components/responses/Generic401"},
          "413": {"description": "The file sent in the request (body or `file` part) is larger than 4 GB (`file_too_large`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "502": {"$ref": "#/components/responses/UpstreamError"}
        }
      }
    },
    "/v1/jobs/{jobId}": {
      "get": {
        "tags": ["Jobs"],
        "operationId": "getJob",
        "security": [{"bearerAuth": []}],
        "summary": "Poll a job",
        "description": "States: `validating` (the file is being checked), `starting` (waiting for a GPU or a server, with `queuedReason`; or the converter is starting), `running` (with `progress` and `stage`), then `done` (with the results), `failed` or `expired`. The `jobId` stays the one returned by POST /v1/jobs. The request answers at once (no long polling): poll every 2-3 s. Download URLs of results are signed for 24 hours. Credits shown include the job debit on completion.",
        "parameters": [
          {"name": "jobId", "in": "path", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "Terminal state: done, failed or expired.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/JobOutcome"},
                "examples": {
                  "done": {"value": {"status": "done", "jobId": "call_1a2b", "operation": "midi", "model": "v2", "cost": 2, "results": {"midiUrl": "https://…", "rawMidiUrl": "https://…", "name": "song", "bpm": 124, "duration": 214.5, "audioUrl": "https://…"}, "resultsExpireIn": 86400, "resultsExpireAt": "2026-11-08T11:00:00Z", "credits": 28}},
                  "failed": {"value": {"status": "failed", "error": {"code": "job_failed", "message": "The conversion failed"}, "jobId": "call_1a2b", "credits": 30}},
                  "expired": {"value": {"status": "expired", "error": {"code": "result_expired", "message": "Results are only kept for 24 hours"}, "jobId": "call_1a2b", "credits": 30}}
                }
              }
            }
          },
          "202": {
            "description": "Not finished yet: validating, starting or running.",
            "content": {
              "application/json": {
                "schema": {"oneOf": [{"$ref": "#/components/schemas/JobWaiting"}, {"$ref": "#/components/schemas/JobRunning"}]},
                "examples": {"validating": {"value": {"status": "validating", "jobId": "e3f4c5…", "operation": "midi", "model": "v2", "queuedAt": "2026-11-07T12:00:00Z", "retentionHours": 24, "poll": {"method": "GET", "url": "/v1/jobs/e3f4c5…"}}}, "waitingForGpu": {"value": {"status": "starting", "queuedReason": "gpu_capacity", "jobId": "e3f4c5…", "operation": "separation", "model": "separation", "queuedAt": "2026-11-07T12:00:00Z", "retentionHours": 24, "poll": {"method": "GET", "url": "/v1/jobs/e3f4c5…"}}}, "running": {"value": {"status": "running", "jobId": "e3f4c5…", "operation": "midi", "model": "v2", "startedAt": "2026-11-07T11:00:12Z", "secondsElapsed": 63, "progress": 0.42, "stage": "converting", "resultsExpireIn": 86400}}}
              }
            }
          },
          "404": {"$ref": "#/components/responses/JobNotFound"},
          "401": {"$ref": "#/components/responses/Generic401"},
          "502": {"$ref": "#/components/responses/UpstreamError"}
        }
      }
    },
    "/v1/account": {
      "get": {
        "tags": ["Account"],
        "operationId": "getAccount",
        "security": [{"bearerAuth": []}],
        "summary": "Credits and quotas of the account",
        "responses": {
          "200": {
            "description": "Balance and limits.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Account"},
                "examples": {
                  "simple": {"value": {"credits": 30, "plan": "user", "email": "you@example.com", "quotas": {"maxApiKeys": 5, "uploadUrlTtlSeconds": 3600, "fileAndResultRetentionHours": 24}, "prices": [{"model": "v2", "creditsPerSegment": 1, "segmentSeconds": 60}, {"model": "separation", "creditsPerSegment": 1, "segmentSeconds": 30}]}}
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Generic401"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key created on https://musictomidi.com/developers: mtm_prod_… (real conversions) or mtm_test_… (no conversion, no credits, always the same sample result), sent as-is (no re-encoding)."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Opaque string (8-255 chars). The same value with the same body returns the same job and is never billed twice.",
        "schema": {"type": "string", "minLength": 8, "maxLength": 255}
      }
    },
    "responses": {
      "Generic401": {"description": "Missing, unknown or revoked API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "InvalidRequest": {"description": "Validation error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "FileNotFound": {"description": "Unknown file for this account.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "FileForbidden": {"description": "The file belongs to another account.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "FileExpired": {"description": "The uploaded file reached the 24-hour retention limit.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "InputFileError": {"description": "Unreadable or missing audio file.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "JobNotFound": {"description": "Unknown job for this account.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "IdempotencyConflict": {"description": "This Idempotency-Key was already used with a different request body.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "InsufficientCredits": {"description": "Not enough credits for this conversion.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Paused": {
        "description": "Maintenance in progress (container update): GET /ready answers 503 while the queue of accepted jobs is drained; public routes keep answering and new jobs are accepted, checked, then wait (see POST /v1/jobs).",
        "headers": {"Retry-After": {"schema": {"type": "integer"}, "description": "Seconds to wait before retrying /ready"}},
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "UpstreamError": {"description": "Conversion or storage service temporarily unavailable (never exposes upstream response bodies).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {"type": "string", "description": "machine-readable code, e.g. invalid_api_key, file_forbidden, insufficient_credits, idempotency_conflict"},
              "message": {"type": "string"},
              "details": {"type": "object", "nullable": true}
            },
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      },
      "CreateFileRequest": {
        "type": "object",
        "properties": {
          "name": {"type": "string", "minLength": 1, "maxLength": 200},
          "contentType": {"type": "string", "minLength": 1, "maxLength": 100, "default": "application/octet-stream"}
        },
        "required": ["name"]
      },
      "FileCreated": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "contentType": {"type": "string"},
          "fileKey": {"type": "string", "description": "Reference of the uploaded file, to send on POST /v1/jobs"},
          "uploadUrl": {"type": "string", "format": "uri", "description": "Presigned upload URL, valid 1 hour"},
          "headers": {"type": "object", "description": "Headers to send on the PUT"},
          "expiresAt": {"type": "string", "format": "date-time"},
          "retentionHours": {"type": "integer", "const": 24},
          "next": {"type": "object"}
        },
        "required": ["fileKey", "uploadUrl", "headers", "expiresAt", "retentionHours"]
      },
      "MidiJobRequest": {
        "type": "object",
        "properties": {
          "fileKey": {"type": "string", "pattern": "^uploads/"},
          "operation": {"type": "string", "const": "midi"},
          "model": {"type": "string", "enum": ["v1", "v2", "v3", "multitrack_transformer", "vocal_transformer", "multitrack"], "description": "v3 is GPU-only; vocal_transformer converts the singing voice; multitrack separates stems then converts each one"},
          "startSeconds": {"type": "number", "minimum": 0, "description": "Selection start (seconds of the file), with endSeconds: only the selection is converted and paid; tempo, meter and key are measured on the whole file"},
          "endSeconds": {"type": "number", "exclusiveMinimum": 0, "description": "Selection end, after startSeconds; past the end of the file, the selection stops at the end"},
          "tempoKey": {"type": "string", "pattern": "^uploads/", "description": "fileKey of the full mix (your account) when the file is a mix of separated stems: tempo, meter and key are measured on it"},
          "options": {
            "type": "object",
            "properties": {
              "noteThreshold": {"type": "number", "minimum": 0, "maximum": 1, "default": 0.65},
              "splitThreshold": {"type": "number", "minimum": 0, "maximum": 1, "default": 0.25},
              "minimumNoteDuration": {"type": "number", "minimum": 0, "maximum": 500, "default": 30},
              "minimumPitch": {"type": "number", "minimum": 0, "maximum": 3000, "default": 30},
              "maximumPitch": {"type": "number", "minimum": 0, "maximum": 12000, "default": 3000},
              "energyTolerance": {"type": "integer", "minimum": 0, "maximum": 100, "default": 11},
              "noteBias": {"type": "number", "minimum": -2, "maximum": 2, "description": "v3 and multitrack only"},
              "minNoteMs": {"type": "number", "minimum": 0, "maximum": 500, "default": 30, "description": "Minimum note duration in ms (0: keep all notes; drums are never removed)"},
              "quantization": {"type": "string", "enum": ["grid", "follow", "none", "legacy"], "default": "follow", "description": "grid: on the beats, constant tempo; follow: tempo map in sync with the audio; none: notes as played; legacy: former quantization (v1 and v2)"},
              "quantizeStrength": {"type": "number", "minimum": 0, "maximum": 1, "default": 1, "description": "0: notes as played, 1: notes on the grid"},
              "detectBPM": {"type": "boolean", "default": true, "description": "false: no tempo nor meter detection (no quantization, no bpm in the results)"},
              "timingGrid": {"type": "integer", "default": 4, "description": "v1 and v2 only (legacy quantization)"},
              "durationGrid": {"type": "integer", "default": 8, "description": "v1 and v2 only (legacy quantization)"},
              "isolate": {"type": "boolean", "default": false, "description": "vocal_transformer only: separate the voice first (its audio is returned in stemUrl)"},
              "device": {"type": "string", "enum": ["cpu", "gpu"], "default": "gpu", "description": "multitrack_transformer and vocal_transformer only; cpu runs without a shared GPU (never waits for one)"}
            },
            "additionalProperties": false
          },
          "stems": {"type": "array", "items": {"type": "string", "enum": ["vocals", "drums", "bass", "guitar", "piano", "other"]}, "description": "multitrack only"}
        },
        "required": ["fileKey", "operation", "model"],
        "additionalProperties": false
      },
      "SeparationJobRequest": {
        "type": "object",
        "properties": {
          "fileKey": {"type": "string", "pattern": "^uploads/"},
          "operation": {"type": "string", "const": "separation"},
          "model": {"type": "string", "const": "separation"},
          "startSeconds": {"type": "number", "minimum": 0, "description": "Selection start, with endSeconds: only the selection is separated and paid; the stems are returned over the whole file (silence outside the selection)"},
          "endSeconds": {"type": "number", "exclusiveMinimum": 0, "description": "Selection end, after startSeconds"},
          "stems": {"type": "array", "items": {"type": "string", "enum": ["vocals", "drums", "bass", "guitar", "piano", "other", "instrumental", "backing"]}, "description": "Default: all stems of the model. instrumental: the song without the voice; backing: the song without the other stems you list (keep at least one stem of the model out of the list)"},
          "formats": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["flac", "mp3"]}, "default": ["flac"], "description": "flac (url) and/or mp3 320 kbit/s (mp3Url); [\"mp3\"] alone returns no url"},
          "mp3": {"type": "boolean", "default": false, "description": "Also return an MP3 320 kbit/s per stem (karaoke use)"}
        },
        "required": ["fileKey", "operation", "model"],
        "additionalProperties": false
      },
      "JobStarted": {
        "type": "object",
        "description": "Test keys (mtm_test_): the sample job runs at once",
        "properties": {
          "testMode": {"type": "boolean", "description": "Present and true for mtm_test_ keys (no conversion, no credits)"},
          "jobId": {"type": "string"},
          "operation": {"type": "string", "enum": ["midi", "separation"]},
          "model": {"type": "string"},
          "status": {"type": "string", "const": "running"},
          "cost": {"type": "number", "description": "Test keys: always 0"},
          "credits": {"type": "number", "description": "Credits left before the job settles"},
          "retentionHours": {"type": "integer", "const": 24},
          "poll": {"type": "object"}
        },
        "required": ["jobId", "operation", "model", "status", "cost", "credits", "retentionHours"]
      },
      "JobRunning": {
        "type": "object",
        "properties": {
          "testMode": {"type": "boolean", "description": "Present and true for mtm_test_ keys (no conversion, no credits)"},
          "status": {"type": "string", "enum": ["starting", "running"], "description": "starting: launched, the converter is starting (no progress yet); running: progress known"},
          "jobId": {"type": "string"},
          "operation": {"type": "string", "enum": ["midi", "separation"]},
          "model": {"type": "string"},
          "startedAt": {"type": "string", "format": "date-time"},
          "secondsElapsed": {"type": "integer", "minLength": 0},
          "progress": {"type": "number", "minimum": 0, "maximum": 1, "description": "Progress of the conversion (0 to 1), when known"},
          "stage": {"type": "string", "description": "Current step (e.g. separating, converting), when known"},
          "resultsExpireIn": {"type": "integer"}
        },
        "required": ["status", "jobId"]
      },
      "JobDone": {
        "type": "object",
        "properties": {
          "testMode": {"type": "boolean", "description": "Present and true for mtm_test_ keys (no conversion, no credits)"},
          "status": {"type": "string", "const": "done"},
          "jobId": {"type": "string"},
          "operation": {"type": "string", "enum": ["midi", "separation"]},
          "model": {"type": "string"},
          "cost": {"type": "number", "description": "Credits finally charged (never more than announced)"},
          "results": {"$ref": "#/components/schemas/JobResults"},
          "resultsExpireIn": {"type": "integer", "minimum": 0, "description": "Seconds left before the results expire (24 hours after the end of the conversion)"},
          "resultsExpireAt": {"type": "string", "format": "date-time", "description": "End of the conversion + 24 hours; the same on every poll"},
          "credits": {"type": "number"}
        },
        "required": ["status", "jobId", "results", "resultsExpireIn", "credits"]
      },
      "JobResults": {
        "type": "object",
        "properties": {
          "midiUrl": {"type": "string", "description": "Quantified (intelligent) MIDI"},
          "rawMidiUrl": {"type": "string", "description": "Raw MIDI, before filtering and quantization"},
          "stemUrl": {"type": "string", "description": "Isolated stem audio (isolated instrument model)"},
          "stems": {
            "type": "array",
            "items": {"type": "object", "properties": {"name": {"type": "string"}, "url": {"type": "string", "description": "FLAC"}, "mp3Url": {"type": "string", "description": "MP3"}}, "required": ["name"]}
          },
          "startSeconds": {"type": "number", "description": "Selection converted or separated (when one was sent)"},
          "endSeconds": {"type": "number"},
          "audioUrl": {"type": "string", "description": "The audio you sent"},
          "audioName": {"type": "string"},
          "name": {"type": "string"},
          "bpm": {"type": "number"},
          "keySignature": {"type": "string"},
          "timeSignature": {"type": "string"},
          "notes": {"type": "integer"},
          "duration": {"type": "number"},
          "quantization": {"type": "string"}
        }
      },
      "JobFailed": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "const": "failed"},
          "error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["job_failed", "input_file_error", "invalid_request", "insufficient_credits", "upstream_error", "internal_error"], "description": "input_file_error: unreadable audio; invalid_request: selection past the end of the file; insufficient_credits: not enough credits; internal_error: interrupted by a server failure, submit again"}, "message": {"type": "string"}}, "required": ["code", "message"]},
          "jobId": {"type": "string"},
          "operation": {"type": "string", "enum": ["midi", "separation"]},
          "model": {"type": "string"},
          "credits": {"type": "number", "description": "Nothing is charged for failed jobs"}
        },
        "required": ["status", "jobId", "credits"]
      },
      "JobExpired": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "const": "expired"},
          "error": {"type": "object", "properties": {"code": {"type": "string", "const": "result_expired"}, "message": {"type": "string"}}, "required": ["code", "message"]},
          "jobId": {"type": "string"},
          "credits": {"type": "number", "description": "Nothing is charged for expired results"}
        },
        "required": ["status", "jobId", "credits"]
      },
      "JobOutcome": {
        "oneOf": [
          {"$ref": "#/components/schemas/JobDone"},
          {"$ref": "#/components/schemas/JobFailed"},
          {"$ref": "#/components/schemas/JobExpired"}
        ]
      },
      "JobWaiting": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "enum": ["validating", "starting"], "description": "validating: the file is being checked; starting: the file is checked and the job waits or is being launched; it starts automatically (its cost is not priced yet)"},
          "queuedReason": {"type": "string", "enum": ["gpu_capacity", "maintenance"], "description": "starting only, while the job waits: gpu_capacity: all shared GPUs are busy; maintenance: a server is being updated"},
          "jobId": {"type": "string"},
          "operation": {"type": "string", "enum": ["midi", "separation"]},
          "model": {"type": "string"},
          "credits": {"type": "number", "description": "POST /v1/jobs only: credits before the job"},
          "queuedAt": {"type": "string", "format": "date-time"},
          "retentionHours": {"type": "integer", "const": 24},
          "poll": {"type": "object"},
          "idempotentReplay": {"type": "boolean"}
        },
        "required": ["status", "jobId", "queuedAt", "retentionHours"]
      },
      "Account": {
        "type": "object",
        "properties": {
          "credits": {"type": "number"},
          "plan": {"type": "string"},
          "email": {"type": "string", "format": "email"},
          "mode": {"type": "string", "enum": ["prod", "test"], "description": "Mode of the key used for this request"},
          "quotas": {
            "type": "object",
            "properties": {
              "maxApiKeys": {"type": "integer"},
              "uploadUrlTtlSeconds": {"type": "integer"},
              "fileAndResultRetentionHours": {"type": "integer", "const": 24},
              "concurrency": {"type": "string"}
            },
            "required": ["maxApiKeys", "fileAndResultRetentionHours"]
          },
          "prices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {"model": {"type": "string"}, "creditsPerSegment": {"type": "integer"}, "segmentSeconds": {"type": "integer"}},
              "required": ["model", "creditsPerSegment", "segmentSeconds"]
            }
          }
        },
        "required": ["credits", "plan", "quotas", "prices"]
      }
    }
  }
}
