API contract reference
Look up HTTP parameters, responses, errors, and the Job event message schema for advanced operations. The contract blocks and TypeScript client read the same FastAPI / Pydantic OpenAPI export. Generation does not connect to Runtime.
Start with a usage guide
Section titled “Start with a usage guide”- Generate, inspect a Candidate, and explicitly save a Version
- Generate a new Candidate from selected ABC
- Transcribe Reference Audio and export ABC/MIDI
- TypeScript client and the complete controlled example
- Job events and HTTP recovery
Replace Project, Asset, Job, Candidate, and Version ids with values returned by the application. The contract below specifies download media types, multipart input, required values, and validation constraints. Each $ref points to the schema index. Use the exported response structure for errors. Business error codes are open strings; see the relevant guide for usage and recovery.
Sources and capability boundaries
Section titled “Sources and capability boundaries”The export entrypoint and HTTP/event contract are the sources of truth. The configuration reference describes upload budgets and Runtime modes; file budgets do not establish inference duration. See current capabilities for creative operations and stage limits. This reference does not send requests, save Versions, or renew diagnostic evidence.
HTTP index
Section titled “HTTP index”GET /settings/metadataGET /runtime/diagnosticsGET /healthGET /runtime/capabilitiesGET /runtime/modelsGET /projectsPOST /projectsGET /projects/{project_id}POST /projects/{project_id}/assetsGET /projects/{project_id}/assetsGET /projects/{project_id}/assets/{asset_id}GET /projects/{project_id}/assets/{asset_id}/contentPOST /projects/{project_id}/transcriptionsGET /projects/{project_id}/jobsGET /projects/{project_id}/jobs/{job_id}POST /projects/{project_id}/jobs/{job_id}/cancelPOST /projects/{project_id}/jobs/{job_id}/retryPOST /projects/{project_id}/scores/validatePOST /projects/{project_id}/scoresGET /projects/{project_id}/scoresGET /projects/{project_id}/scores/{score_id}POST /projects/{project_id}/jobs/generatePOST /projects/{project_id}/jobs/generate-from-scoreGET /projects/{project_id}/candidatesGET /projects/{project_id}/candidates/{candidate_id}POST /projects/{project_id}/versionsGET /projects/{project_id}/versionsGET /projects/{project_id}/versions/{version_id}POST /projects/{project_id}/reference-audio/from-versionGET /projects/{project_id}/assets/{asset_id}/reference-originPOST /projects/{project_id}/cover-inputs/validatePOST /projects/{project_id}/jobs/cover
GET /settings/metadata
Section titled “GET /settings/metadata”Settings Metadata
Operation: settings_metadata_settings_metadata_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsMetadataRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: SettingsMetadataRead · ErrorResponse
GET /runtime/diagnostics
Section titled “GET /runtime/diagnostics”Diagnostics
Operation: diagnostics_runtime_diagnostics_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticsRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: DiagnosticsRead · ErrorResponse
GET /health
Section titled “GET /health”Health
Operation: health_health_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: HealthRead · ErrorResponse
GET /runtime/capabilities
Section titled “GET /runtime/capabilities”Capabilities
Operation: capabilities_runtime_capabilities_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: CapabilitiesRead · ErrorResponse
GET /runtime/models
Section titled “GET /runtime/models”Models
Operation: models_runtime_models_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: ModelsRead · ErrorResponse
GET /projects
Section titled “GET /projects”List Projects
Operation: list_projects_projects_get.
This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ProjectRead" }, "type": "array", "title": "Response List Projects Projects Get" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: ProjectRead · ErrorResponse
POST /projects
Section titled “POST /projects”Create Project
Operation: create_project_projects_post.
Request body and media types:
{ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } }, "required": true}Responses, error statuses, and media types:
{ "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRead" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }}Schemas: ProjectCreate · ProjectRead · ErrorResponse
GET /projects/{project_id}
Section titled “GET /projects/{project_id}”Get Project
Operation: get_project_projects__project_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ProjectRead · ErrorResponse
POST /projects/{project_id}/assets
Section titled “POST /projects/{project_id}/assets”Upload Audio
Operation: upload_audio_projects__project_id__assets_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_audio_projects__project_id__assets_post" } } }}Responses, error statuses, and media types:
{ "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: Body_upload_audio_projects__project_id__assets_post · AssetRead · ErrorResponse
GET /projects/{project_id}/assets
Section titled “GET /projects/{project_id}/assets”List Assets
Operation: list_assets_projects__project_id__assets_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetRead" }, "title": "Response List Assets Projects Project Id Assets Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: AssetRead · ErrorResponse
GET /projects/{project_id}/assets/{asset_id}
Section titled “GET /projects/{project_id}/assets/{asset_id}”Get Asset
Operation: get_asset_projects__project_id__assets__asset_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: AssetRead · ErrorResponse
GET /projects/{project_id}/assets/{asset_id}/content
Section titled “GET /projects/{project_id}/assets/{asset_id}/content”Download Asset
Operation: download_asset_projects__project_id__assets__asset_id__content_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "text/vnd.abc": { "schema": { "type": "string", "format": "binary" } }, "audio/midi": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ErrorResponse
POST /projects/{project_id}/transcriptions
Section titled “POST /projects/{project_id}/transcriptions”Create Transcription
Operation: create_transcription_projects__project_id__transcriptions_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscribeCreate" } } }}Responses, error statuses, and media types:
{ "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: TranscribeCreate · JobRead · ErrorResponse
GET /projects/{project_id}/jobs
Section titled “GET /projects/{project_id}/jobs”List Jobs
Operation: list_jobs_projects__project_id__jobs_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobRead" }, "title": "Response List Jobs Projects Project Id Jobs Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: JobRead · ErrorResponse
GET /projects/{project_id}/jobs/{job_id}
Section titled “GET /projects/{project_id}/jobs/{job_id}”Get Job
Operation: get_job_projects__project_id__jobs__job_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Job Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: JobRead · ErrorResponse
POST /projects/{project_id}/jobs/{job_id}/cancel
Section titled “POST /projects/{project_id}/jobs/{job_id}/cancel”Cancel Job
Operation: cancel_job_projects__project_id__jobs__job_id__cancel_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Job Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } }, "description": "Accepted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: JobRead · ErrorResponse
POST /projects/{project_id}/jobs/{job_id}/retry
Section titled “POST /projects/{project_id}/jobs/{job_id}/retry”Retry Job
Operation: retry_job_projects__project_id__jobs__job_id__retry_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Job Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: JobRead · ErrorResponse
POST /projects/{project_id}/scores/validate
Section titled “POST /projects/{project_id}/scores/validate”Validate Edited Score
Operation: validate_edited_score_projects__project_id__scores_validate_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreValidate" } } }}Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreValidationRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ScoreValidate · ScoreValidationRead · ErrorResponse
POST /projects/{project_id}/scores
Section titled “POST /projects/{project_id}/scores”Create Edited Score
Operation: create_edited_score_projects__project_id__scores_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreCreate" } } }}Responses, error statuses, and media types:
{ "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRead" } } }, "description": "OK" }, "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ScoreCreate · ScoreRead · ErrorResponse
GET /projects/{project_id}/scores
Section titled “GET /projects/{project_id}/scores”List Scores
Operation: list_scores_projects__project_id__scores_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreRead" }, "title": "Response List Scores Projects Project Id Scores Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ScoreRead · ErrorResponse
GET /projects/{project_id}/scores/{score_id}
Section titled “GET /projects/{project_id}/scores/{score_id}”Get Score
Operation: get_score_projects__project_id__scores__score_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "score_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Score Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ScoreRead · ErrorResponse
POST /projects/{project_id}/jobs/generate
Section titled “POST /projects/{project_id}/jobs/generate”Create Generate Job
Operation: create_generate_job_projects__project_id__jobs_generate_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCreate" } } }}Responses, error statuses, and media types:
{ "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: GenerateCreate · JobRead · ErrorResponse
POST /projects/{project_id}/jobs/generate-from-score
Section titled “POST /projects/{project_id}/jobs/generate-from-score”Create Generate From Score Job
Operation: create_generate_from_score_job_projects__project_id__jobs_generate_from_score_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFromScoreCreate" } } }}Responses, error statuses, and media types:
{ "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: GenerateFromScoreCreate · JobRead · ErrorResponse
GET /projects/{project_id}/candidates
Section titled “GET /projects/{project_id}/candidates”List Candidates
Operation: list_candidates_projects__project_id__candidates_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateRead" }, "title": "Response List Candidates Projects Project Id Candidates Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: CandidateRead · ErrorResponse
GET /projects/{project_id}/candidates/{candidate_id}
Section titled “GET /projects/{project_id}/candidates/{candidate_id}”Get Candidate
Operation: get_candidate_projects__project_id__candidates__candidate_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Candidate Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: CandidateRead · ErrorResponse
POST /projects/{project_id}/versions
Section titled “POST /projects/{project_id}/versions”Create Version
Operation: create_version_projects__project_id__versions_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionSave" } } }}Responses, error statuses, and media types:
{ "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRead" } } }, "description": "OK" }, "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: VersionSave · VersionRead · ErrorResponse
GET /projects/{project_id}/versions
Section titled “GET /projects/{project_id}/versions”List Versions
Operation: list_versions_projects__project_id__versions_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionRead" }, "title": "Response List Versions Projects Project Id Versions Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: VersionRead · ErrorResponse
GET /projects/{project_id}/versions/{version_id}
Section titled “GET /projects/{project_id}/versions/{version_id}”Get Version
Operation: get_version_projects__project_id__versions__version_id__get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Version Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: VersionRead · ErrorResponse
POST /projects/{project_id}/reference-audio/from-version
Section titled “POST /projects/{project_id}/reference-audio/from-version”Create Reference
Operation: create_reference_projects__project_id__reference_audio_from_version_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionReferenceCreate" } } }}Responses, error statuses, and media types:
{ "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRead" } } }, "description": "OK" }, "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: VersionReferenceCreate · AssetRead · ErrorResponse
GET /projects/{project_id}/assets/{asset_id}/reference-origin
Section titled “GET /projects/{project_id}/assets/{asset_id}/reference-origin”Read Reference Origin
Operation: read_reference_origin_projects__project_id__assets__asset_id__reference_origin_get.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset Id" } }]This operation has no request body.
Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReferenceOriginRead" }, { "type": "null" } ], "title": "Response Read Reference Origin Projects Project Id Assets Asset Id Reference Origin Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: ReferenceOriginRead · ErrorResponse
POST /projects/{project_id}/cover-inputs/validate
Section titled “POST /projects/{project_id}/cover-inputs/validate”Validate Cover
Operation: validate_cover_projects__project_id__cover_inputs_validate_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverInputValidate" } } }}Responses, error statuses, and media types:
{ "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverValidationRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: CoverInputValidate · CoverValidationRead · ErrorResponse
POST /projects/{project_id}/jobs/cover
Section titled “POST /projects/{project_id}/jobs/cover”Create Cover
Operation: create_cover_projects__project_id__jobs_cover_post.
Parameters, locations, and required values:
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]Request body and media types:
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverCreate" } } }}Responses, error statuses, and media types:
{ "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRead" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable Entity" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service Unavailable" }}Schemas: CoverCreate · JobRead · ErrorResponse
Job event channel
Section titled “Job event channel”The registered WebSocket route and message schema come from the same OpenAPI extension. HTTP remains the recovery source; see the Job events guide.
{ "/projects/{project_id}/jobs/{job_id}/events": { "message": { "$ref": "#/components/schemas/JobEventRead" } }}Schema index
Section titled “Schema index”ActiveApplicationJobReadApplicationQueueReadAssetReadBackendHealthReadBody_upload_audio_projects__project_id__assets_postCandidateReadCapabilitiesReadCapabilityReadCodeRegistryReadCoverCreateCoverInputValidateCoverValidationReadDiagnosticReasonDiagnosticSourceDiagnosticValue_dict_str__list_str___DiagnosticValue_int_DiagnosticValue_list_str__DiagnosticValue_str_DiagnosticsReadErrorDetailErrorResponseGenerateCreateGenerateFromScoreCreateHealthReadJobReadJsonValueMemoryMetricReadModelReadModelsReadProjectCreateProjectReadReferenceOriginReadRuntimeHealthReadScoreCreateScoreReadScoreValidateScoreValidationReadSettingsMetadataReadTranscribeCreateVersionReadVersionReferenceCreateVersionSaveJobEventRead
ActiveApplicationJobRead
Section titled “ActiveApplicationJobRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "operation": { "type": "string", "enum": [ "Transcribe", "Generate", "GenerateFromScore", "Cover" ], "title": "Operation" }, "status": { "type": "string", "enum": [ "queued", "running" ], "title": "Status" }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phase" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" } }, "type": "object", "required": [ "id", "project_id", "operation", "status", "phase", "observation" ], "title": "ActiveApplicationJobRead"}ApplicationQueueRead
Section titled “ApplicationQueueRead”{ "properties": { "scope": { "type": "string", "const": "Application persisted active Job states; not native occupancy", "title": "Scope" }, "queued": { "type": "integer", "minimum": 0, "title": "Queued" }, "running": { "type": "integer", "minimum": 0, "title": "Running" }, "jobs": { "items": { "$ref": "#/components/schemas/ActiveApplicationJobRead" }, "type": "array", "title": "Jobs" }, "recorded_running_job": { "$ref": "#/components/schemas/DiagnosticValue_str_" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" } }, "type": "object", "required": [ "scope", "queued", "running", "jobs", "recorded_running_job", "observation" ], "title": "ApplicationQueueRead"}AssetRead
Section titled “AssetRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "kind": { "type": "string", "enum": [ "reference_audio", "score_abc", "score_midi", "generated_audio" ], "title": "Kind" }, "original_name": { "type": "string", "title": "Original Name" }, "format": { "type": "string", "enum": [ "wav", "abc", "mid", "flac" ], "title": "Format" }, "media_type": { "type": "string", "title": "Media Type" }, "size_bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Size Bytes" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "title": "Sha256" }, "duration_seconds": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Duration Seconds" }, "channels": { "anyOf": [ { "type": "integer", "maximum": 2, "minimum": 1 }, { "type": "null" } ], "title": "Channels" }, "sample_rate": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Sample Rate" }, "sample_width_bits": { "anyOf": [ { "type": "integer", "enum": [ 8, 16, 24, 32 ] }, { "type": "null" } ], "title": "Sample Width Bits" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "project_id", "kind", "original_name", "format", "media_type", "size_bytes", "sha256", "created_at" ], "title": "AssetRead"}BackendHealthRead
Section titled “BackendHealthRead”{ "properties": { "status": { "type": "string", "const": "ready", "title": "Status" }, "scope": { "type": "string", "const": "application HTTP process", "title": "Scope" }, "version": { "type": "string", "title": "Version" }, "python_version": { "type": "string", "title": "Python Version" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" } }, "type": "object", "required": [ "status", "scope", "version", "python_version", "observation" ], "title": "BackendHealthRead"}Body_upload_audio_projects__project_id__assets_post
Section titled “Body_upload_audio_projects__project_id__assets_post”{ "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_audio_projects__project_id__assets_post"}CandidateRead
Section titled “CandidateRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "job_id": { "type": "string", "format": "uuid", "title": "Job Id" }, "audio_asset_id": { "type": "string", "format": "uuid", "title": "Audio Asset Id" }, "score_id": { "type": "string", "format": "uuid", "title": "Score Id" }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/CoverCreate" }, { "$ref": "#/components/schemas/GenerateFromScoreCreate" }, { "$ref": "#/components/schemas/GenerateCreate" } ], "title": "Inputs" }, "provenance": { "additionalProperties": true, "type": "object", "title": "Provenance" }, "output_snapshot": { "additionalProperties": true, "type": "object", "title": "Output Snapshot" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "project_id", "job_id", "audio_asset_id", "score_id", "inputs", "provenance", "output_snapshot", "created_at" ], "title": "CandidateRead"}CapabilitiesRead
Section titled “CapabilitiesRead”{ "properties": { "mode": { "type": "string", "enum": [ "fake", "comfyui" ], "title": "Mode" }, "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "capabilities": { "items": { "$ref": "#/components/schemas/CapabilityRead" }, "type": "array", "title": "Capabilities" } }, "type": "object", "required": [ "mode", "checked_at", "capabilities" ], "title": "CapabilitiesRead"}CapabilityRead
Section titled “CapabilityRead”{ "properties": { "operation": { "type": "string", "enum": [ "Transcribe", "Generate", "GenerateFromScore", "Cover" ], "title": "Operation" }, "required_models": { "items": { "type": "string" }, "type": "array", "title": "Required Models" }, "ready": { "type": "boolean", "title": "Ready" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" }, "supported_modes": { "items": { "type": "string", "enum": [ "melody", "full" ] }, "type": "array", "title": "Supported Modes", "description": "Observed and declared Cover modes; empty for non-Cover or missing mode choices." } }, "type": "object", "required": [ "operation", "required_models", "ready", "observation", "reasons" ], "title": "CapabilityRead"}CodeRegistryRead
Section titled “CodeRegistryRead”{ "properties": { "component": { "type": "string", "enum": [ "runtime", "plugin" ], "title": "Component" }, "expected_revision": { "type": "string", "title": "Expected Revision" }, "code_license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code License" }, "license_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Source" }, "registry_source": { "type": "string", "title": "Registry Source" } }, "type": "object", "required": [ "component", "expected_revision", "code_license", "license_source", "registry_source" ], "title": "CodeRegistryRead"}CoverCreate
Section titled “CoverCreate”{ "properties": { "style": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Style" }, "lyrics": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Lyrics" }, "seed": { "type": "integer", "maximum": 9223372036854776000, "minimum": 0, "title": "Seed" }, "max_seconds": { "type": "integer", "maximum": 360, "minimum": 0, "title": "Max Seconds", "description": "Audio ceiling in seconds; 0 follows the lyrics (the pinned model default).", "default": 0 }, "abc": { "type": "string", "maxLength": 100000, "minLength": 1, "title": "Abc", "description": "Explicitly selected ABC; copied exactly into the Job input snapshot." }, "source_score_id": { "type": "string", "format": "uuid", "title": "Source Score Id", "description": "Existing source Score in this Project; edited ABC may differ from its original Asset." }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id", "description": "Optional same-Project Version owning the source Score or retained as its explicit editing parent; retained on Version save." }, "mode": { "type": "string", "enum": [ "melody", "full" ], "title": "Mode", "description": "Explicit Cover mode: melody omits written chord symbols; full retains them. Both keep the two musical voices." }, "reference_asset_id": { "type": "string", "format": "uuid", "title": "Reference Asset Id" }, "effective_abc_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "title": "Effective Abc Sha256", "description": "Hash of the effective ABC the creator inspected and selected." }, "mode_transform_version": { "type": "string", "const": "1.0.0", "title": "Mode Transform Version" } }, "additionalProperties": false, "type": "object", "required": [ "style", "lyrics", "seed", "abc", "source_score_id", "mode", "reference_asset_id", "effective_abc_sha256", "mode_transform_version" ], "title": "CoverCreate"}CoverInputValidate
Section titled “CoverInputValidate”{ "properties": { "abc": { "type": "string", "maxLength": 100000, "minLength": 1, "title": "Abc" }, "mode": { "type": "string", "enum": [ "melody", "full" ], "title": "Mode" } }, "additionalProperties": false, "type": "object", "required": [ "abc", "mode" ], "title": "CoverInputValidate"}CoverValidationRead
Section titled “CoverValidationRead”{ "properties": { "note_count": { "type": "integer", "exclusiveMinimum": 0, "title": "Note Count" }, "abc_sha256": { "type": "string", "title": "Abc Sha256" }, "effective_abc_sha256": { "type": "string", "title": "Effective Abc Sha256" }, "transformations": { "items": { "type": "string" }, "type": "array", "title": "Transformations" }, "adapter_version": { "type": "string", "title": "Adapter Version" }, "parser": { "type": "string", "title": "Parser" }, "effective_abc": { "type": "string", "title": "Effective Abc" }, "mode": { "type": "string", "enum": [ "melody", "full" ], "title": "Mode" }, "mode_transform_version": { "type": "string", "title": "Mode Transform Version" }, "source_chord_count": { "type": "integer", "minimum": 0, "title": "Source Chord Count" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "description": "full_without_written_chords means full is legal but has no explicit harmony guidance." } }, "type": "object", "required": [ "note_count", "abc_sha256", "effective_abc_sha256", "transformations", "adapter_version", "parser", "effective_abc", "mode", "mode_transform_version", "source_chord_count" ], "title": "CoverValidationRead"}DiagnosticReason
Section titled “DiagnosticReason”{ "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "recovery": { "type": "string", "title": "Recovery" } }, "type": "object", "required": [ "code", "message", "recovery" ], "title": "DiagnosticReason"}DiagnosticSource
Section titled “DiagnosticSource”{ "properties": { "source": { "type": "string", "title": "Source" }, "observed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Observed At" }, "age_seconds": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "title": "Age Seconds" }, "freshness": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ], "title": "Freshness" }, "max_age_seconds": { "type": "number", "exclusiveMinimum": 0, "title": "Max Age Seconds" } }, "type": "object", "required": [ "source", "observed_at", "age_seconds", "freshness", "max_age_seconds" ], "title": "DiagnosticSource"}DiagnosticValue_dict_str__list_str___
Section titled “DiagnosticValue_dict_str__list_str___”{ "properties": { "value": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Value" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "title": "Availability" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "value", "availability", "observation", "reasons" ], "title": "DiagnosticValue[dict[str, list[str]]]"}DiagnosticValue_int_
Section titled “DiagnosticValue_int_”{ "properties": { "value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Value" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "title": "Availability" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "value", "availability", "observation", "reasons" ], "title": "DiagnosticValue[int]"}DiagnosticValue_list_str__
Section titled “DiagnosticValue_list_str__”{ "properties": { "value": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Value" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "title": "Availability" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "value", "availability", "observation", "reasons" ], "title": "DiagnosticValue[list[str]]"}DiagnosticValue_str_
Section titled “DiagnosticValue_str_”{ "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "title": "Availability" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "value", "availability", "observation", "reasons" ], "title": "DiagnosticValue[str]"}DiagnosticsRead
Section titled “DiagnosticsRead”{ "properties": { "mode": { "type": "string", "enum": [ "fake", "comfyui" ], "title": "Mode" }, "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "source_observations": { "additionalProperties": { "$ref": "#/components/schemas/DiagnosticSource" }, "type": "object", "title": "Source Observations" }, "gpu_name": { "$ref": "#/components/schemas/DiagnosticValue_str_" }, "versions": { "additionalProperties": { "$ref": "#/components/schemas/DiagnosticValue_str_" }, "type": "object", "title": "Versions" }, "memory": { "items": { "$ref": "#/components/schemas/MemoryMetricRead" }, "type": "array", "title": "Memory" }, "loaded_models": { "$ref": "#/components/schemas/DiagnosticValue_list_str__" }, "generic_model_inventory": { "$ref": "#/components/schemas/DiagnosticValue_dict_str__list_str___" }, "application_queue": { "$ref": "#/components/schemas/ApplicationQueueRead" }, "native_queue_occupancy": { "$ref": "#/components/schemas/DiagnosticValue_int_" } }, "type": "object", "required": [ "mode", "checked_at", "source_observations", "gpu_name", "versions", "memory", "loaded_models", "generic_model_inventory", "application_queue", "native_queue_occupancy" ], "title": "DiagnosticsRead"}ErrorDetail
Section titled “ErrorDetail”{ "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "recovery": { "type": "string", "title": "Recovery" }, "resource_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource Id" } }, "type": "object", "required": [ "code", "message", "recovery" ], "title": "ErrorDetail"}ErrorResponse
Section titled “ErrorResponse”{ "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse"}GenerateCreate
Section titled “GenerateCreate”{ "properties": { "style": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Style" }, "lyrics": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Lyrics" }, "seed": { "type": "integer", "maximum": 9223372036854776000, "minimum": 0, "title": "Seed" }, "max_seconds": { "type": "integer", "maximum": 360, "minimum": 0, "title": "Max Seconds", "description": "Audio ceiling in seconds; 0 follows the lyrics (the pinned model default).", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "style", "lyrics", "seed" ], "title": "GenerateCreate"}GenerateFromScoreCreate
Section titled “GenerateFromScoreCreate”{ "properties": { "style": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Style" }, "lyrics": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Lyrics" }, "seed": { "type": "integer", "maximum": 9223372036854776000, "minimum": 0, "title": "Seed" }, "max_seconds": { "type": "integer", "maximum": 360, "minimum": 0, "title": "Max Seconds", "description": "Audio ceiling in seconds; 0 follows the lyrics (the pinned model default).", "default": 0 }, "abc": { "type": "string", "maxLength": 100000, "minLength": 1, "title": "Abc", "description": "Explicitly selected ABC; copied exactly into the Job input snapshot." }, "source_score_id": { "type": "string", "format": "uuid", "title": "Source Score Id", "description": "Existing source Score in this Project; edited ABC may differ from its original Asset." }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id", "description": "Optional same-Project Version owning the source Score or retained as its explicit editing parent; retained on Version save." } }, "additionalProperties": false, "type": "object", "required": [ "style", "lyrics", "seed", "abc", "source_score_id" ], "title": "GenerateFromScoreCreate"}HealthRead
Section titled “HealthRead”{ "properties": { "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "backend": { "$ref": "#/components/schemas/BackendHealthRead" }, "runtime": { "$ref": "#/components/schemas/RuntimeHealthRead" } }, "type": "object", "required": [ "checked_at", "backend", "runtime" ], "title": "HealthRead"}JobRead
Section titled “JobRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "operation": { "type": "string", "enum": [ "Transcribe", "Generate", "GenerateFromScore", "Cover" ], "title": "Operation" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phase" }, "progress": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Progress" }, "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs" }, "provenance": { "additionalProperties": true, "type": "object", "title": "Provenance" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error" }, "result": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Result" }, "recovery_required": { "type": "boolean", "title": "Recovery Required" }, "cancel_requested": { "type": "boolean", "title": "Cancel Requested", "default": false }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "project_id", "operation", "status", "phase", "inputs", "provenance", "error", "result", "recovery_required", "created_at", "updated_at" ], "title": "JobRead"}JsonValue
Section titled “JsonValue”{}MemoryMetricRead
Section titled “MemoryMetricRead”{ "properties": { "value": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Value" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "title": "Availability" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" }, "name": { "type": "string", "title": "Name" }, "scope": { "type": "string", "title": "Scope" }, "unit": { "type": "string", "const": "bytes", "title": "Unit" } }, "type": "object", "required": [ "value", "availability", "observation", "reasons", "name", "scope", "unit" ], "title": "MemoryMetricRead"}ModelRead
Section titled “ModelRead”{ "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "provider": { "type": "string", "title": "Provider" }, "repository": { "type": "string", "title": "Repository" }, "revision": { "type": "string", "title": "Revision" }, "filename": { "type": "string", "title": "Filename" }, "local_path": { "type": "string", "title": "Local Path" }, "registry_source": { "type": "string", "title": "Registry Source" }, "hash_source": { "type": "string", "title": "Hash Source" }, "components": { "items": { "type": "string" }, "type": "array", "title": "Components" }, "component_license_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Component License Notes" }, "expected_sha256": { "type": "string", "title": "Expected Sha256" }, "expected_size_bytes": { "type": "integer", "exclusiveMinimum": 0, "title": "Expected Size Bytes" }, "weights_license": { "type": "string", "title": "Weights License" }, "license_source": { "type": "string", "title": "License Source" }, "state": { "type": "string", "enum": [ "missing", "downloading", "ready", "invalid", "unavailable" ], "title": "State" }, "observed_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Observed Sha256" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "id", "name", "provider", "repository", "revision", "filename", "local_path", "registry_source", "hash_source", "components", "component_license_notes", "expected_sha256", "expected_size_bytes", "weights_license", "license_source", "state", "observed_sha256", "observation", "reasons" ], "title": "ModelRead"}ModelsRead
Section titled “ModelsRead”{ "properties": { "mode": { "type": "string", "enum": [ "fake", "comfyui" ], "title": "Mode" }, "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "code_registry": { "items": { "$ref": "#/components/schemas/CodeRegistryRead" }, "type": "array", "title": "Code Registry" }, "models": { "items": { "$ref": "#/components/schemas/ModelRead" }, "type": "array", "title": "Models" } }, "type": "object", "required": [ "mode", "checked_at", "code_registry", "models" ], "title": "ModelsRead"}ProjectCreate
Section titled “ProjectCreate”{ "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "type": "string", "maxLength": 2000, "title": "Description", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "ProjectCreate"}ProjectRead
Section titled “ProjectRead”{ "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "type": "string", "maxLength": 2000, "title": "Description", "default": "" }, "id": { "type": "string", "format": "uuid", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "additionalProperties": false, "type": "object", "required": [ "name", "id", "created_at" ], "title": "ProjectRead"}ReferenceOriginRead
Section titled “ReferenceOriginRead”{ "properties": { "reference_asset_id": { "type": "string", "format": "uuid", "title": "Reference Asset Id" }, "source_version_id": { "type": "string", "format": "uuid", "title": "Source Version Id" }, "source_asset_id": { "type": "string", "format": "uuid", "title": "Source Asset Id" }, "source_sha256": { "type": "string", "title": "Source Sha256" }, "start_frame": { "type": "integer", "title": "Start Frame" }, "frame_count": { "type": "integer", "title": "Frame Count" }, "sample_rate": { "type": "integer", "title": "Sample Rate" }, "derivation_version": { "type": "string", "title": "Derivation Version" } }, "type": "object", "required": [ "reference_asset_id", "source_version_id", "source_asset_id", "source_sha256", "start_frame", "frame_count", "sample_rate", "derivation_version" ], "title": "ReferenceOriginRead"}RuntimeHealthRead
Section titled “RuntimeHealthRead”{ "properties": { "mode": { "type": "string", "enum": [ "fake", "comfyui" ], "title": "Mode" }, "status": { "type": "string", "enum": [ "ready", "not_ready", "unavailable" ], "title": "Status" }, "reachable": { "type": "boolean", "title": "Reachable" }, "ready": { "type": "boolean", "title": "Ready" }, "binding_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Binding Verified" }, "observation": { "$ref": "#/components/schemas/DiagnosticSource" }, "reasons": { "items": { "$ref": "#/components/schemas/DiagnosticReason" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "mode", "status", "reachable", "ready", "binding_verified", "observation", "reasons" ], "title": "RuntimeHealthRead"}ScoreCreate
Section titled “ScoreCreate”{ "properties": { "abc": { "type": "string", "maxLength": 100000, "minLength": 1, "title": "Abc" }, "save_id": { "type": "string", "format": "uuid", "title": "Save Id", "description": "Stable save-intent id. Repeating identical input returns the same immutable Score." }, "source_score_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Score Id", "description": "Optional source Score in this Project; its files remain immutable." }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id", "description": "Optional Version owning the source Score, or its retained editing parent." } }, "additionalProperties": false, "type": "object", "required": [ "abc" ], "title": "ScoreCreate"}ScoreRead
Section titled “ScoreRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "job_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Job Id" }, "abc_asset_id": { "type": "string", "format": "uuid", "title": "Abc Asset Id" }, "source_reference_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Reference Asset Id" }, "source_score_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Score Id" }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "project_id", "job_id", "abc_asset_id", "source_reference_asset_id", "source_score_id", "parent_version_id", "created_at" ], "title": "ScoreRead"}ScoreValidate
Section titled “ScoreValidate”{ "properties": { "abc": { "type": "string", "maxLength": 100000, "minLength": 1, "title": "Abc" } }, "additionalProperties": false, "type": "object", "required": [ "abc" ], "title": "ScoreValidate"}ScoreValidationRead
Section titled “ScoreValidationRead”{ "properties": { "note_count": { "type": "integer", "exclusiveMinimum": 0, "title": "Note Count" }, "abc_sha256": { "type": "string", "title": "Abc Sha256" }, "effective_abc_sha256": { "type": "string", "title": "Effective Abc Sha256" }, "transformations": { "items": { "type": "string" }, "type": "array", "title": "Transformations" }, "adapter_version": { "type": "string", "title": "Adapter Version" }, "parser": { "type": "string", "title": "Parser" } }, "type": "object", "required": [ "note_count", "abc_sha256", "effective_abc_sha256", "transformations", "adapter_version", "parser" ], "title": "ScoreValidationRead"}SettingsMetadataRead
Section titled “SettingsMetadataRead”{ "properties": { "source": { "type": "string", "const": "music_api.config.Settings.model_json_schema", "title": "Source" }, "environment_prefix": { "type": "string", "title": "Environment Prefix" }, "environment_variables": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Environment Variables" }, "settings_schema": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Settings Schema" } }, "type": "object", "required": [ "source", "environment_prefix", "environment_variables", "settings_schema" ], "title": "SettingsMetadataRead"}TranscribeCreate
Section titled “TranscribeCreate”{ "properties": { "reference_asset_id": { "type": "string", "format": "uuid", "title": "Reference Asset Id" } }, "additionalProperties": false, "type": "object", "required": [ "reference_asset_id" ], "title": "TranscribeCreate"}VersionRead
Section titled “VersionRead”{ "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "job_id": { "type": "string", "format": "uuid", "title": "Job Id" }, "audio_asset_id": { "type": "string", "format": "uuid", "title": "Audio Asset Id" }, "score_id": { "type": "string", "format": "uuid", "title": "Score Id" }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/CoverCreate" }, { "$ref": "#/components/schemas/GenerateFromScoreCreate" }, { "$ref": "#/components/schemas/GenerateCreate" } ], "title": "Inputs" }, "provenance": { "additionalProperties": true, "type": "object", "title": "Provenance" }, "output_snapshot": { "additionalProperties": true, "type": "object", "title": "Output Snapshot" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "candidate_id": { "type": "string", "format": "uuid", "title": "Candidate Id" }, "name": { "type": "string", "title": "Name" }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id" } }, "type": "object", "required": [ "id", "project_id", "job_id", "audio_asset_id", "score_id", "inputs", "provenance", "output_snapshot", "created_at", "candidate_id", "name", "parent_version_id" ], "title": "VersionRead"}VersionReferenceCreate
Section titled “VersionReferenceCreate”{ "properties": { "source_version_id": { "type": "string", "format": "uuid", "title": "Source Version Id" }, "save_id": { "type": "string", "format": "uuid", "title": "Save Id", "description": "Immutable Reference save intent. Identical replay returns the same first16s PCM WAV." } }, "additionalProperties": false, "type": "object", "required": [ "source_version_id" ], "title": "VersionReferenceCreate"}VersionSave
Section titled “VersionSave”{ "properties": { "candidate_id": { "type": "string", "format": "uuid", "title": "Candidate Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "parent_version_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Version Id", "description": "Generate may choose a same-Project parent. GenerateFromScore retains its submitted parent when omitted and rejects a different parent." } }, "additionalProperties": false, "type": "object", "required": [ "candidate_id", "name" ], "title": "VersionSave"}JobEventRead
Section titled “JobEventRead”{ "properties": { "type": { "type": "string", "const": "job.updated", "title": "Type", "default": "job.updated" }, "sequence": { "type": "integer", "minimum": 0, "title": "Sequence" }, "job": { "$ref": "#/components/schemas/JobRead" } }, "type": "object", "required": [ "sequence", "job" ], "title": "JobEventRead"}Source version:
1ce3268Page source: docs/reference/api.en.md