API 合同参考
查询高级操作的 HTTP 参数、返回与错误，以及 Job 事件的消息结构。本页的合同区块与 TypeScript client 读取同一 FastAPI / Pydantic OpenAPI 导出；生成时不连接 Runtime。
先选一个用法入口
Section titled “先选一个用法入口”- 生成、试听 Candidate 与明确保存 Version
- 从选定 ABC 生成新 Candidate
- 参考音频转谱与导出 ABC/MIDI
- TypeScript client 与完整受控示例
- Job 事件与 HTTP 恢复
将路径中的 Project、Asset、Job、Candidate 与 Version id 换成应用实际返回的值。HTTP 下载的媒体类型、multipart 输入、必填值与校验限制都在下方合同中。结构里的 $ref 对应“结构索引”。错误结构以已导出的响应为准；业务错误码是开放字符串，用法与恢复见对应指南。
来源与能力边界
Section titled “来源与能力边界”导出入口 与 HTTP/事件合同 为事实来源。配置参考 说明上传预算与运行模式；文件预算不代表推理时长。创作能力与阶段限制见当前能力。本参考不会运行请求、保存 Version 或更新诊断收据。
HTTP 分类索引
Section titled “HTTP 分类索引”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
操作: settings_metadata_settings_metadata_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: SettingsMetadataRead · ErrorResponse
GET /runtime/diagnostics
Section titled “GET /runtime/diagnostics”Diagnostics
操作: diagnostics_runtime_diagnostics_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: DiagnosticsRead · ErrorResponse
GET /health
Section titled “GET /health”Health
操作: health_health_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: HealthRead · ErrorResponse
GET /runtime/capabilities
Section titled “GET /runtime/capabilities”Capabilities
操作: capabilities_runtime_capabilities_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: CapabilitiesRead · ErrorResponse
GET /runtime/models
Section titled “GET /runtime/models”Models
操作: models_runtime_models_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: ModelsRead · ErrorResponse
GET /projects
Section titled “GET /projects”List Projects
操作: list_projects_projects_get.
此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" } } } }}结构: ProjectRead · ErrorResponse
POST /projects
Section titled “POST /projects”Create Project
操作: create_project_projects_post.
请求正文与媒体类型：
{ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } }, "required": true}返回、错误状态与媒体类型：
{ "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" } } } }}结构: ProjectCreate · ProjectRead · ErrorResponse
GET /projects/{project_id}
Section titled “GET /projects/{project_id}”Get Project
操作: get_project_projects__project_id__get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: ProjectRead · ErrorResponse
POST /projects/{project_id}/assets
Section titled “POST /projects/{project_id}/assets”Upload Audio
操作: upload_audio_projects__project_id__assets_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_audio_projects__project_id__assets_post" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: Body_upload_audio_projects__project_id__assets_post · AssetRead · ErrorResponse
GET /projects/{project_id}/assets
Section titled “GET /projects/{project_id}/assets”List Assets
操作: list_assets_projects__project_id__assets_get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: AssetRead · ErrorResponse
GET /projects/{project_id}/assets/{asset_id}
Section titled “GET /projects/{project_id}/assets/{asset_id}”Get Asset
操作: get_asset_projects__project_id__assets__asset_id__get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: AssetRead · ErrorResponse
GET /projects/{project_id}/assets/{asset_id}/content
Section titled “GET /projects/{project_id}/assets/{asset_id}/content”Download Asset
操作: download_asset_projects__project_id__assets__asset_id__content_get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: ErrorResponse
POST /projects/{project_id}/transcriptions
Section titled “POST /projects/{project_id}/transcriptions”Create Transcription
操作: create_transcription_projects__project_id__transcriptions_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscribeCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: TranscribeCreate · JobRead · ErrorResponse
GET /projects/{project_id}/jobs
Section titled “GET /projects/{project_id}/jobs”List Jobs
操作: list_jobs_projects__project_id__jobs_get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: JobRead · ErrorResponse
GET /projects/{project_id}/jobs/{job_id}
Section titled “GET /projects/{project_id}/jobs/{job_id}”Get Job
操作: get_job_projects__project_id__jobs__job_id__get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: JobRead · ErrorResponse
POST /projects/{project_id}/jobs/{job_id}/cancel
Section titled “POST /projects/{project_id}/jobs/{job_id}/cancel”Cancel Job
操作: cancel_job_projects__project_id__jobs__job_id__cancel_post.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: JobRead · ErrorResponse
POST /projects/{project_id}/jobs/{job_id}/retry
Section titled “POST /projects/{project_id}/jobs/{job_id}/retry”Retry Job
操作: retry_job_projects__project_id__jobs__job_id__retry_post.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: JobRead · ErrorResponse
POST /projects/{project_id}/scores/validate
Section titled “POST /projects/{project_id}/scores/validate”Validate Edited Score
操作: validate_edited_score_projects__project_id__scores_validate_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreValidate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: ScoreValidate · ScoreValidationRead · ErrorResponse
POST /projects/{project_id}/scores
Section titled “POST /projects/{project_id}/scores”Create Edited Score
操作: create_edited_score_projects__project_id__scores_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: ScoreCreate · ScoreRead · ErrorResponse
GET /projects/{project_id}/scores
Section titled “GET /projects/{project_id}/scores”List Scores
操作: list_scores_projects__project_id__scores_get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: ScoreRead · ErrorResponse
GET /projects/{project_id}/scores/{score_id}
Section titled “GET /projects/{project_id}/scores/{score_id}”Get Score
操作: get_score_projects__project_id__scores__score_id__get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: ScoreRead · ErrorResponse
POST /projects/{project_id}/jobs/generate
Section titled “POST /projects/{project_id}/jobs/generate”Create Generate Job
操作: create_generate_job_projects__project_id__jobs_generate_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: 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
操作: create_generate_from_score_job_projects__project_id__jobs_generate_from_score_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFromScoreCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: GenerateFromScoreCreate · JobRead · ErrorResponse
GET /projects/{project_id}/candidates
Section titled “GET /projects/{project_id}/candidates”List Candidates
操作: list_candidates_projects__project_id__candidates_get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: CandidateRead · ErrorResponse
GET /projects/{project_id}/candidates/{candidate_id}
Section titled “GET /projects/{project_id}/candidates/{candidate_id}”Get Candidate
操作: get_candidate_projects__project_id__candidates__candidate_id__get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: CandidateRead · ErrorResponse
POST /projects/{project_id}/versions
Section titled “POST /projects/{project_id}/versions”Create Version
操作: create_version_projects__project_id__versions_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionSave" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: VersionSave · VersionRead · ErrorResponse
GET /projects/{project_id}/versions
Section titled “GET /projects/{project_id}/versions”List Versions
操作: list_versions_projects__project_id__versions_get.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: VersionRead · ErrorResponse
GET /projects/{project_id}/versions/{version_id}
Section titled “GET /projects/{project_id}/versions/{version_id}”Get Version
操作: get_version_projects__project_id__versions__version_id__get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: VersionRead · ErrorResponse
POST /projects/{project_id}/reference-audio/from-version
Section titled “POST /projects/{project_id}/reference-audio/from-version”Create Reference
操作: create_reference_projects__project_id__reference_audio_from_version_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionReferenceCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: 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
操作: read_reference_origin_projects__project_id__assets__asset_id__reference_origin_get.
参数、位置与必填值：
[ { "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" } }]此操作没有请求正文。
返回、错误状态与媒体类型：
{ "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" }}结构: ReferenceOriginRead · ErrorResponse
POST /projects/{project_id}/cover-inputs/validate
Section titled “POST /projects/{project_id}/cover-inputs/validate”Validate Cover
操作: validate_cover_projects__project_id__cover_inputs_validate_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverInputValidate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: CoverInputValidate · CoverValidationRead · ErrorResponse
POST /projects/{project_id}/jobs/cover
Section titled “POST /projects/{project_id}/jobs/cover”Create Cover
操作: create_cover_projects__project_id__jobs_cover_post.
参数、位置与必填值：
[ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }]请求正文与媒体类型：
{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverCreate" } } }}返回、错误状态与媒体类型：
{ "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" }}结构: CoverCreate · JobRead · ErrorResponse
Job 事件通道
Section titled “Job 事件通道”已注册 WebSocket 路径与消息结构来自同一 OpenAPI 扩展。HTTP 仍是恢复来源；用法见 Job 事件指南。
{ "/projects/{project_id}/jobs/{job_id}/events": { "message": { "$ref": "#/components/schemas/JobEventRead" } }}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"}源码版本:
1ce3268正文来源: docs/reference/api.md