{"openapi":"3.1.0","info":{"title":"SoundBerry S.r.l. API","description":"AI music production API: generate tracks from text, split audio into stems, split drums into percussion parts, generate a single instrument stem that fits a reference mix, analyze BPM/key.\n\n**Model ids.** Ids start with the capability (`text-to-music-v2`, `stem-separation-6stems-v1`, `stem-generation-native-v1`). Older model ids keep working in the `model` field; responses always return the current id. A generation made with a retired model reports `<capability>-legacy` (e.g. `stem-separation-legacy`); sent back as `model`, it runs on that capability's default model.\n\n**Authentication.** Create an API key from *Dashboard → API keys* and send it as the `x-api-key` header (or `Authorization: Bearer <key>`). Keys act as your account: generations spend your credits and appear in your history.\n\n**Synchronous by default.** Requests made with an API key wait for the result and return it in the same response (up to 8 minutes) — no polling needed. `GET /gen/status/{generationId}` and `GET /gen/job-status/{jobId}` exist for clients that prefer to poll or that lost a response.\n\n**Audio inputs.** Any `audioPath` / `audioContextPath` / `audioReferencePath` accepts a public `https://` URL of a WAV/MP3 file, or the storage path of a previous result.\n\n**Audio outputs.** Results come back as a storage path plus a signed download URL (`audioUrl`) valid for 60 minutes. Files produced through the API are kept for 48 hours — download them.\n\n**Credits.** Each generation reserves the model's credit cost up-front and refunds it if the generation fails. `GET /gen/models` lists the models you can use and their cost; `GET /user/info` returns your balance.\n\n**MCP.** The same operations are available as tools to AI agents at `https://soundberry.ai/api/mcp` (Streamable HTTP, same API key as bearer). See /api/docs for client configuration.","version":"1.0.0"},"servers":[{"url":"https://soundberry.ai/api"}],"tags":[{"name":"auth"},{"name":"generations"}],"externalDocs":{"url":"https://soundberry.ai/api/docs"},"paths":{"/gen/text-to-music":{"post":{"operationId":"textToMusic","summary":"Generate music from text prompt","description":"Generate music from text prompt using AI. Optionally creates a project and triggers stem separation.","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":0,"maxLength":1000},"model":{"type":"string"},"createProject":{"default":true,"type":"boolean"},"triggerStemSeparation":{"type":"boolean"},"stemSeparationModel":{"type":"string"},"cutToLoop":{"default":false,"type":"boolean"},"audioDuration":{"description":"Approximate length for Text to Music v2/v3 (the model aims for it). Omit it and the model picks, usually a full song of about 3 minutes; v2/v3 do not go much under 1 minute, so for 30 s use model text-to-music-30s-v1, which ignores this field.","type":"string","enum":["30s","1m","2m","3m"]},"lyrics":{"type":"string","maxLength":4000},"seed":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"temperature":{"type":"number","minimum":0,"maximum":1}},"required":["prompt"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"anyOf":[{"type":"object","properties":{"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"generation":{"type":"object","properties":{"prompt":{"type":"string"},"seed":{"type":"number"}},"required":["prompt"],"additionalProperties":false},"creditsBalance":{"type":"number"},"generationId":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"metadata":{"type":"object","properties":{"bpm":{"anyOf":[{"type":"integer","minimum":20,"maximum":300},{"type":"null"}]},"key":{"anyOf":[{"type":"string","enum":["C","C#","Db","D","D#","Eb","E","F","F#","Gb","G","G#","Ab","A","A#","Bb","B","Cm","C#m","Dm","D#m","Em","Fm","F#m","Gm","G#m","Am","A#m","Bm"]},{"type":"null"}]},"bars":{"anyOf":[{"type":"integer","minimum":1,"maximum":128},{"type":"null"}]}},"required":["bpm","key","bars"],"additionalProperties":false}},"required":["audioPath","audioUrl","generation","creditsBalance","projectId","projectName","metadata"],"additionalProperties":false},{"type":"object","properties":{"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"generation":{"type":"object","properties":{"prompt":{"type":"string"},"seed":{"type":"number"}},"required":["prompt"],"additionalProperties":false},"creditsBalance":{"type":"number"},"generationId":{"type":"string"}},"required":["audioPath","audioUrl","generation","creditsBalance"],"additionalProperties":false},{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"queued"},"creditsBalance":{"type":"number"},"message":{"type":"string"}},"required":["generationId","status","creditsBalance","message"],"additionalProperties":false}]}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/stem-separation":{"post":{"operationId":"stemSeparation","summary":"Separate audio into stems","description":"Separate audio into individual instrument stems","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPath":{"type":"string"},"projectId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"model":{"type":"string"},"sync":{"type":"boolean"}},"required":["audioPath"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"anyOf":[{"type":"object","properties":{"generationId":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","const":"processing"},"message":{"type":"string"},"creditsBalance":{"type":"number"}},"required":["generationId","jobId","status","message","creditsBalance"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"completed"},"stems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string","enum":["drums","bass","guitar","piano","synth","strings","brass","woodwinds","vocals","lead","pad","fx","percussion","kick","snare","hihat","ride","crash","toms","other"]},{"type":"null"}]}},"required":["name","audioPath","audioUrl","instrument"],"additionalProperties":false}},"silentStems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string","enum":["drums","bass","guitar","piano","synth","strings","brass","woodwinds","vocals","lead","pad","fx","percussion","kick","snare","hihat","ride","crash","toms","other"]},{"type":"null"}]}},"required":["name","audioPath","audioUrl","instrument"],"additionalProperties":false}},"creditsBalance":{"type":"number"},"generationId":{"type":"string"},"jobId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","stems","silentStems","creditsBalance","generationId","jobId"],"additionalProperties":false},{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"queued"},"creditsBalance":{"type":"number"},"message":{"type":"string"}},"required":["generationId","status","creditsBalance","message"],"additionalProperties":false}]}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/drum-separation":{"post":{"operationId":"drumSeparation","summary":"Separate drums into individual percussion stems","description":"Separate a drum track into individual percussion components (kick, snare, hi-hat, toms, ride, crash, etc.)","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPath":{"type":"string"},"projectId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sourceStemId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"isDrumStemInput":{"default":false,"type":"boolean"},"model":{"type":"string"}},"required":["audioPath"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"completed"},"stems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string","enum":["drums","bass","guitar","piano","synth","strings","brass","woodwinds","vocals","lead","pad","fx","percussion","kick","snare","hihat","ride","crash","toms","other"]},{"type":"null"}]}},"required":["name","audioPath","instrument"],"additionalProperties":false}},"silentStems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string","enum":["drums","bass","guitar","piano","synth","strings","brass","woodwinds","vocals","lead","pad","fx","percussion","kick","snare","hihat","ride","crash","toms","other"]},{"type":"null"}]}},"required":["name","audioPath","instrument"],"additionalProperties":false}},"creditsBalance":{"type":"number"}},"required":["status","stems","creditsBalance"],"additionalProperties":false},{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"queued"},"creditsBalance":{"type":"number"},"message":{"type":"string"}},"required":["generationId","status","creditsBalance","message"],"additionalProperties":false}]}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/stem-sample":{"post":{"operationId":"stemSample","summary":"Generate individual instrument stem","description":"Generate an individual instrument stem that fits an existing mix. `audioContextPath` is the mix the part must play along with (it fixes tempo, key and structure). `audioReferencePath` steers timbre and style more precisely than words and usually yields a part that sits better in the mix; `textPrompt` works well on its own and the two can be combined.","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioContextPath":{"type":"string"},"audioReferencePath":{"type":"string"},"textPrompt":{"type":"string","minLength":3,"maxLength":500},"instrument":{"type":"string","enum":["drums","bass","guitar","piano","synth","strings","brass","woodwinds","vocals","lead","pad","fx","percussion","kick","snare","hihat","ride","crash","toms","other"]},"model":{"type":"string"},"providerParams":{"description":"Optional advanced settings for the selected model. Leave it out unless you were given specific values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"projectId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"stemId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"useProjectMix":{"type":"boolean"},"excludeStemId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"excludeMutedStemIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"n":{"default":1,"type":"integer","minimum":1,"maximum":4}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"anyOf":[{"type":"object","properties":{"outputAudioPath":{"type":"string"},"outputAudioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"outputAudioPaths":{"type":"array","items":{"type":"string"}},"outputAudioUrls":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},"mixAudioPath":{"type":"string"},"mixAudioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsBalance":{"type":"number"},"generationIds":{"type":"array","items":{"type":"string"}}},"required":["outputAudioPath","outputAudioUrl","outputAudioPaths","outputAudioUrls","creditsBalance"],"additionalProperties":false},{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"queued"},"creditsBalance":{"type":"number"},"message":{"type":"string"}},"required":["generationId","status","creditsBalance","message"],"additionalProperties":false}]}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/beat-analysis":{"post":{"operationId":"beatAnalysis","summary":"Analyze audio for BPM and key","description":"Analyze an audio file for BPM, key and scale","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPath":{"type":"string"}},"required":["audioPath"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"bpm":{"type":"number"},"key":{"type":"string"},"scale":{"type":"string"},"keyStrength":{"type":"number"},"creditsBalance":{"type":"number"}},"required":["bpm","key","scale","keyStrength","creditsBalance"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/extend-beat":{"post":{"operationId":"extendBeat","summary":"Extend audio by looping","description":"Extend audio by looping it a specified number of times","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPath":{"type":"string"},"loops":{"default":4,"type":"integer","minimum":1,"maximum":100}},"required":["audioPath"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration":{"type":"number"},"creditsBalance":{"type":"number"}},"required":["audioPath","audioUrl","duration","creditsBalance"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/beat-cut":{"post":{"operationId":"beatCut","summary":"Cut audio segment","description":"Cut a segment from audio file at specified start and end times","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPath":{"type":"string"},"startTime":{"type":"number","minimum":0},"endTime":{"type":"number","exclusiveMinimum":0}},"required":["audioPath","startTime","endTime"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration":{"type":"number"},"creditsBalance":{"type":"number"}},"required":["audioPath","audioUrl","duration","creditsBalance"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/generate-lyrics":{"post":{"operationId":"generateLyrics","summary":"Generate song lyrics from a music prompt","description":"Generate free-form song lyrics matching the prompt's language. Feed the returned lyrics into the `lyrics` field of `POST /api/gen/text-to-music` (models that sing lyrics, e.g. `text-to-music-v2`).","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":0,"maxLength":1000},"existingLyrics":{"type":"string","maxLength":4000}},"required":["prompt"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"lyrics":{"type":"string"}},"required":["lyrics"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/mix-audio":{"post":{"operationId":"mixAudio","summary":"Mix stems into single audio","description":"Mix multiple audio stems into a single audio file","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioPaths":{"minItems":1,"maxItems":32,"type":"array","items":{"type":"string"}}},"required":["audioPaths"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration":{"type":"number"}},"required":["audioPath","audioUrl","duration"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/job-status/{jobId}":{"get":{"operationId":"checkJobStatus","summary":"Check async job status","description":"Check the status of a generation job (e.g., stem separation) by the `jobId` or `generationId` a generation request returned.","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[{"in":"path","name":"jobId","schema":{"type":"string","minLength":1,"description":"The `jobId` (or `generationId`) returned by a generation request."},"required":true,"description":"The `jobId` (or `generationId`) returned by a generation request."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"generationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"outputs":{"anyOf":[{"type":"object","properties":{"stems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","audioPath","audioUrl","instrument"],"additionalProperties":false}},"silentStems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","audioPath","audioUrl","instrument"],"additionalProperties":false}}},"required":["stems"],"additionalProperties":false},{"type":"null"}]}},"required":["jobId","status","generationId","projectId","error","completedAt","createdAt","outputs"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/status/{generationId}":{"get":{"operationId":"getGenerationStatus","summary":"Get generation status","description":"Status and outputs of any generation, by the `generationId` a generation request returned.","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[{"in":"path","name":"generationId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"generation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"modelId":{"anyOf":[{"type":"string"},{"type":"null"}]},"jobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"stemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","modelId","jobId","projectId","stemId","prompt","error","errorCode","createdAt","completedAt"],"additionalProperties":false},"audioPath":{"anyOf":[{"type":"string"},{"type":"null"}]},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"audioPaths":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"audioUrls":{"anyOf":[{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"outputs":{"anyOf":[{"type":"object","properties":{"stems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","audioPath","audioUrl","instrument"],"additionalProperties":false}},"silentStems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audioPath":{"type":"string"},"audioUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"instrument":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","audioPath","audioUrl","instrument"],"additionalProperties":false}}},"required":["stems"],"additionalProperties":false},{"type":"null"}]},"creditsUsed":{"type":"number"},"creditsBalance":{"type":"number"},"isProcessing":{"type":"boolean"},"isTerminal":{"type":"boolean"}},"required":["generation","audioPath","audioUrl","audioPaths","audioUrls","outputs","creditsUsed","creditsBalance","isProcessing","isTerminal"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/gen/models":{"get":{"operationId":"listAvailableModels","summary":"List available models","description":"List available AI models for a given capability, filtered by the authenticated user's access. Only active (non-deprecated, non-sunset) models are returned. Deprecated models can still be used by passing their model ID directly to generation endpoints.","tags":["generations"],"security":[{"Authorization":[]}],"parameters":[{"in":"query","name":"capability","schema":{"type":"string","enum":["text-to-music","stem-separation","stem-generation","audio-variation","audio-analysis","text-completion","drum-separation","audio-repaint","audio-extend","audio-edit"]},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string"},"creditCost":{"type":"number","minimum":0},"isDeprecated":{"type":"boolean"},"deprecationMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"available":{"type":"boolean"},"maxSamples":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","name","creditCost","isDeprecated","deprecationMessage","createdAt","available","maxSamples"],"additionalProperties":false}},"defaultModelId":{"type":"string"}},"required":["models","defaultModelId"],"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/user/info":{"get":{"operationId":"getUserInfo","summary":"Get user info","description":"Get the authenticated user's name, email, image, credits balance, active subscription info, and credit bucket status. Always returns `payload.maintenanceMode: boolean` (true when the platform is in maintenance) on both success and auth-failure paths so clients can surface a maintenance notice regardless of session state. When the api key is missing/invalid/expired or the user no longer exists, returns HTTP 200 with `{ success: false, message, payload: { authError, maintenanceMode } }` instead of 401 — `payload.authError` is one of `api_key_missing` | `api_key_invalid` | `api_key_expired` | `user_not_found` and `message` is localized. Clients should treat any `authError` as a cue to discard the local api key and require re-login. `device_id` (optional) identifies the calling device.","tags":["auth"],"security":[{"Authorization":[]}],"parameters":[{"in":"query","name":"device_id","schema":{"type":"string","maxLength":255}},{"in":"query","name":"vst_version","schema":{"type":"string","maxLength":50}},{"in":"query","name":"vst_build","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditsBalance":{"type":"number"},"staticCredits":{"type":"number"},"dailyCredits":{"type":"number"},"weeklyCredits":{"type":"number"},"monthlyCredits":{"type":"number"},"subscription":{"anyOf":[{"type":"object","properties":{"status":{"type":"string"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"currentPeriodEnd":{"type":"string"},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["status","tier","productName","currentPeriodEnd","cancelAtPeriodEnd"],"additionalProperties":false},{"type":"null"}]},"creditBuckets":{"anyOf":[{"type":"object","properties":{"daily":{"type":"object","properties":{"balance":{"type":"number"},"limit":{"type":"number"},"resetAt":{"type":"string"}},"required":["balance","limit","resetAt"],"additionalProperties":false},"weekly":{"type":"object","properties":{"balance":{"type":"number"},"limit":{"type":"number"},"resetAt":{"type":"string"}},"required":["balance","limit","resetAt"],"additionalProperties":false},"monthly":{"type":"object","properties":{"balance":{"type":"number"},"limit":{"type":"number"},"resetAt":{"type":"string"}},"required":["balance","limit","resetAt"],"additionalProperties":false}},"required":["daily","weekly","monthly"],"additionalProperties":false},{"type":"null"}]},"authError":{"type":"string","enum":["api_key_missing","api_key_invalid","api_key_expired","user_not_found"]},"maintenanceMode":{"type":"boolean"}},"additionalProperties":false}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}},"components":{"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Invalid input data"},"code":{"type":"string","description":"The error code","example":"BAD_REQUEST"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information","example":{"code":"BAD_REQUEST","message":"Invalid input data","issues":[]}},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Authorization not provided"},"code":{"type":"string","description":"The error code","example":"UNAUTHORIZED"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information","example":{"code":"UNAUTHORIZED","message":"Authorization not provided","issues":[]}},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Insufficient access"},"code":{"type":"string","description":"The error code","example":"FORBIDDEN"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information","example":{"code":"FORBIDDEN","message":"Insufficient access","issues":[]}},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Internal server error"},"code":{"type":"string","description":"The error code","example":"INTERNAL_SERVER_ERROR"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information","example":{"code":"INTERNAL_SERVER_ERROR","message":"Internal server error","issues":[]}},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Not found"},"code":{"type":"string","description":"The error code","example":"NOT_FOUND"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information","example":{"code":"NOT_FOUND","message":"Not found","issues":[]}}},"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}}}}