{"openapi":"3.1.0","info":{"title":"AudioLasso API","version":"1.0.0","description":"Queue-based API for separating specific sounds from audio or video with plain-language prompts."},"servers":[{"url":"https://audiolasso.dev","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Audio","description":"Audio separation models"},{"name":"Files","description":"Temporary file uploads for local and private media"},{"name":"Queue","description":"Async request status and results"},{"name":"Models","description":"Available public API models"}],"paths":{"/v1/openapi.json":{"get":{"tags":["Models"],"operationId":"getOpenApiSpec","summary":"Get the OpenAPI specification","security":[],"responses":{"200":{"description":"OpenAPI specification"}}}},"/v1/models":{"get":{"tags":["Models"],"operationId":"listModels","summary":"List available models","description":"Requires the `models:read` API key scope.","responses":{"200":{"description":"Model list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/files":{"post":{"tags":["Files"],"operationId":"createFileUpload","summary":"Create a temporary upload URL","description":"Use this for local files, private files, and CLI/agent workflows. Requires the `files:write` API key scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileRequest"}}}},"responses":{"201":{"description":"Temporary upload URL created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/files/{file_id}":{"get":{"tags":["Files"],"operationId":"getFile","summary":"Get file upload metadata","description":"Requires the `files:read` API key scope.","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","examples":["file_01jabc"]}}],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/queue/audio/separate":{"post":{"tags":["Audio"],"operationId":"submitAudioSeparate","summary":"Submit an audio separation request","description":"Submit public HTTPS media with `audio_url`, or submit a temporary uploaded file with `file_id`. Requires the `audio:separate` API key scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitAudioSeparateRequest"}}}},"responses":{"202":{"description":"Request queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueSubmitResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/queue/requests/{request_id}/status":{"get":{"tags":["Queue"],"operationId":"getQueueRequestStatus","summary":"Get request status","description":"Requires the `audio:separate` API key scope.","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","examples":["req_01jabc"]}},{"name":"logs","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Request status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueStatusResponse"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/queue/requests/{request_id}/status/stream":{"get":{"tags":["Queue"],"operationId":"streamQueueRequestStatus","summary":"Stream request status","description":"Streams queue status updates as Server-Sent Events until the request reaches a terminal status or the stream window ends. Requires the `audio:separate` API key scope.","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","examples":["req_01jabc"]}},{"name":"logs","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"interval","in":"query","required":false,"description":"Polling interval in seconds while the SSE connection is open. Values are clamped from 1 to 10 seconds.","schema":{"type":"number","default":2,"minimum":1,"maximum":10}}],"responses":{"200":{"description":"SSE status stream","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events with `status`, `timeout`, or `error` event names. `status` event data matches QueueStatusResponse."},"examples":{"status":{"value":"event: status\\ndata: {\"request_id\":\"req_01jabc\",\"model\":\"audio/separate\",\"status\":\"IN_PROGRESS\"}\\n\\n"}}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/queue/requests/{request_id}/result":{"get":{"tags":["Queue"],"operationId":"getQueueRequestResult","summary":"Get request result","description":"Requires the `audio:separate` API key scope.","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","examples":["req_01jabc"]}}],"responses":{"200":{"description":"Completed separation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueResultResponse"}}}},"401":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{"audioSeparateCompleted":{"post":{"operationId":"audioSeparateCompletedWebhook","summary":"Audio separation completed","description":"Sent to `webhookUrl` when a queued audio separation request completes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCompletedEvent"}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge delivery."}}}},"audioSeparateFailed":{"post":{"operationId":"audioSeparateFailedWebhook","summary":"Audio separation failed","description":"Sent to `webhookUrl` when a queued audio separation request fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookFailedEvent"}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge delivery."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"AudioLasso API key"}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["INVALID_AUDIO_URL","INSUFFICIENT_CREDITS"]},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}}}}},"CreateFileRequest":{"type":"object","required":["file_name","content_type","file_size","purpose"],"properties":{"file_name":{"type":"string","examples":["local-audio.wav"]},"content_type":{"type":"string","examples":["audio/wav"]},"file_size":{"type":"integer","minimum":1,"maximum":524288000,"examples":[12345678]},"purpose":{"type":"string","const":"audio.separate.input"}}},"CreateFileResponse":{"type":"object","required":["file_id","upload_url","upload_method","headers","expires_at","retention"],"properties":{"file_id":{"type":"string","examples":["file_01jabc"]},"upload_url":{"type":"string","format":"uri"},"upload_method":{"type":"string","const":"PUT"},"headers":{"type":"object","properties":{"content-type":{"type":"string","examples":["audio/wav"]}}},"expires_at":{"type":"string","format":"date-time"},"retention":{"type":"object","properties":{"delete_after":{"type":"string","format":"date-time"}}}}},"File":{"type":"object","required":["file_id","file_name","content_type","file_size","purpose","status","created_at","expires_at"],"properties":{"file_id":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string"},"file_size":{"type":"integer"},"purpose":{"type":"string"},"status":{"type":"string","enum":["pending","uploaded","expired"]},"created_at":{"type":"string","format":"date-time"},"uploaded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"}}},"SubmitAudioSeparateRequest":{"type":"object","required":["input"],"properties":{"input":{"$ref":"#/components/schemas/AudioSeparateInput"},"webhookUrl":{"type":"string","format":"uri","description":"Public HTTPS endpoint that receives the terminal webhook event."},"webhookSecret":{"type":"string","minLength":16,"maxLength":256,"description":"Optional HMAC signing secret. If omitted, AudioLasso generates one and returns it once in the submit response."},"metadata":{"type":"object","additionalProperties":true}}},"AudioSeparateInput":{"allOf":[{"type":"object","required":["prompt"],"properties":{"audio_url":{"type":"string","format":"uri","description":"Public HTTPS URL for audio or video. Localhost, file URLs, and private network URLs are rejected.","examples":["https://example.com/audio.wav"]},"file_id":{"type":"string","description":"Temporary upload id returned by POST /v1/files.","examples":["file_01jabc"]},"prompt":{"type":"string","minLength":1,"maxLength":500,"examples":["separate the piano from the background music"]},"predict_spans":{"type":"boolean","default":false},"reranking_candidates":{"type":"integer","minimum":1,"maximum":8,"default":1},"acceleration":{"type":"string","enum":["fast","balanced","quality"],"default":"balanced"},"max_chunk_duration":{"type":"number","exclusiveMinimum":0,"maximum":300,"default":60},"chunk_overlap":{"type":"number","minimum":0,"maximum":30,"default":5},"output_format":{"type":"string","enum":["wav","mp3"],"default":"wav"},"spans":{"type":"array","items":{"$ref":"#/components/schemas/AudioSpan"}}}},{"oneOf":[{"required":["audio_url"]},{"required":["file_id"]}]}]},"AudioSpan":{"type":"object","required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"include":{"type":"boolean","default":true}}},"QueueSubmitResponse":{"type":"object","required":["request_id","status","model","created_at","status_url","stream_url","result_url"],"properties":{"request_id":{"type":"string","examples":["req_01jabc"]},"status":{"type":"string","const":"IN_QUEUE"},"model":{"type":"string","const":"audio/separate"},"created_at":{"type":"string","format":"date-time"},"status_url":{"type":"string","format":"uri"},"stream_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"webhook":{"$ref":"#/components/schemas/WebhookSubmitInfo"}}},"QueueStatusResponse":{"type":"object","required":["request_id","model","status","created_at","updated_at","result_url"],"properties":{"request_id":{"type":"string"},"model":{"type":"string","const":"audio/separate"},"status":{"type":"string","enum":["IN_QUEUE","IN_PROGRESS","COMPLETED","FAILED"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"result_url":{"type":"string","format":"uri"},"logs":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"message":{"type":"string"}}}},"webhook":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}}},"QueueResultResponse":{"type":"object","required":["request_id","model","status","data","usage","retention"],"properties":{"request_id":{"type":"string"},"model":{"type":"string","const":"audio/separate"},"status":{"type":"string","const":"COMPLETED"},"data":{"type":"object","required":["target","residual","sample_rate"],"properties":{"target":{"$ref":"#/components/schemas/OutputFile"},"residual":{"$ref":"#/components/schemas/OutputFile"},"duration":{"type":"number"},"sample_rate":{"type":"integer"}}},"usage":{"type":"object","properties":{"feature":{"type":"string","const":"audio_seconds"},"quantity":{"type":"integer"},"billing_status":{"type":"string","enum":["deducted","not_metered"]}}},"webhook":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"retention":{"type":"object","properties":{"delete_after":{"type":"string","format":"date-time"}}}}},"WebhookSubmitInfo":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"signing_secret":{"type":"string","description":"Returned only when AudioLasso generated the signing secret.","examples":["whsec_..."]}}},"WebhookDeliveryStatus":{"type":"object","required":["delivery_status","attempts","delivered_at","last_error"],"properties":{"delivery_status":{"type":"string","enum":["pending","sending","delivered","failed"]},"attempts":{"type":"integer"},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"WebhookCompletedEvent":{"type":"object","required":["type","request_id","model","status","created_at","completed_at","data","usage"],"properties":{"type":{"type":"string","const":"audio.separate.completed"},"request_id":{"type":"string"},"model":{"type":"string","const":"audio/separate"},"status":{"type":"string","const":"COMPLETED"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["target","residual","sample_rate"],"properties":{"target":{"$ref":"#/components/schemas/OutputFile"},"residual":{"$ref":"#/components/schemas/OutputFile"},"duration":{"type":"number"},"sample_rate":{"type":"integer"}}},"usage":{"type":"object","properties":{"feature":{"type":"string","const":"audio_seconds"},"quantity":{"type":"integer"},"billing_status":{"type":"string","enum":["deducted","not_metered"]}}},"metadata":{"type":"object","additionalProperties":true}}},"WebhookFailedEvent":{"type":"object","required":["type","request_id","model","status","created_at","failed_at","error"],"properties":{"type":{"type":"string","const":"audio.separate.failed"},"request_id":{"type":"string"},"model":{"type":"string","const":"audio/separate"},"status":{"type":"string","const":"FAILED"},"created_at":{"type":"string","format":"date-time"},"failed_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["MODEL_FAILED"]},"message":{"type":"string"}}},"metadata":{"type":"object","additionalProperties":true}}},"OutputFile":{"type":"object","required":["url","content_type","file_name"],"properties":{"url":{"type":"string","format":"uri"},"video_url":{"type":"string","format":"uri"},"content_type":{"type":"string","examples":["audio/wav"]},"file_name":{"type":"string","examples":["target.wav"]}}},"ModelList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"Model":{"type":"object","required":["id","object","description","input","output"],"properties":{"id":{"type":"string","examples":["audio/separate"]},"object":{"type":"string","const":"model"},"description":{"type":"string"},"input":{"type":"object"},"output":{"type":"object"}}}}}}