{ "openapi": "3.1.0", "info": { "title": "Taoyuan Music API", "version": "1.0.0", "summary": "桃源：为一个人写一首歌 / Taoyuan: a finished song for one person, in about three minutes.", "description": "桃源（Taoyuan）音乐生成接口。一句话需求 → 歌词、风格、封面和两版完整歌曲（约 3 分钟）。适合 Agent、脚本和产品集成；同一套接口也以 MCP 形式提供（https://api.musicsforyou.com/mcp）。\n\n典型流程：`POST /v1/prompts/compile`（免费，看歌词和风格）→ `POST /v1/generations`（扣 1 次）→ 轮询 `GET /v1/generations/{id}` 直到 `finished`。不想分步就用 `POST /v1/songs` 一次完成。\n\nTaoyuan turns one sentence into a finished song: lyrics, style, cover art and two full candidate tracks in about three minutes. Typical flow: compile (free, preview lyrics and style) → generate (1 credit) → poll until finished. Or call `POST /v1/songs` to do it all in one request.\n\n**Billing.** Generation and replace-section cost 1 credit each (one credit = one song with two candidates). Compile, revise, lint, get and list are free. Stems: the 2-track vocal/instrumental split is free once per song for non-members and unlimited for members; the 12-stem split is Pro only; neither costs credits. API and MCP calls draw only from prepaid API credits (never the Pro monthly allowance). Failed generations are refunded. New API keys come with 3 free credits.\n\n**Rate limits.** Generation submissions: 5 per minute per IP. Compile/revise: 30 per hour per account (guests 5 per day per IP). **Errors.** Every failure is `{ success: false, code, error }`; branch on `code`.\n\nDocs and keys: https://www.musicsforyou.com/developers · Plain-text guide for LLMs: https://www.musicsforyou.com/llms.txt", "termsOfService": "https://www.musicsforyou.com/terms", "contact": { "name": "Taoyuan support", "email": "2368082693@qq.com", "url": "https://www.musicsforyou.com/developers" } }, "servers": [ { "url": "https://api.musicsforyou.com", "description": "Production" } ], "tags": [ { "name": "Compose", "description": "编译与修改（免费）/ Compile and revise (free)" }, { "name": "Generate", "description": "生成与查询 / Generate and poll" }, { "name": "Edit", "description": "局部替换与分轨 / Replace a section, stems" }, { "name": "Library", "description": "作品 / Tracks" }, { "name": "Catalog", "description": "目录 / Presets and capabilities" }, { "name": "Account", "description": "额度与用量 / Credits and usage" }, { "name": "Keys", "description": "API Key 管理（仅网站登录）/ Key management (website session only)" }, { "name": "Billing", "description": "额度购买 / Buying credits" } ], "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "paths": { "/v1/prompts/compile": { "post": { "operationId": "compile_music_prompt", "tags": [ "Compose" ], "summary": "编译：一句需求 → 歌词与风格（免费）/ Compile a request into a spec (free)", "description": "把一句自然语言需求编译成可直接生成的 GenerationSpec：标题、英文风格标签、带段落标记的歌词、负面标签、时长。不扣额度。\n\nTurns one sentence into a ready-to-generate spec (title, style tags, sectioned lyrics, negative tags, duration). Free. If `spec.status` is `needs_input`, ask the user `spec.question.question` and call again with `clarificationAnswer`. Guests: 5 calls/day per IP (cached 24 h). Signed-in or API key: 30 calls/hour.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileRequest" } } } }, "responses": { "200": { "description": "编译结果 / Compiled spec", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "compile_music_prompt" } }, "/v1/prompts/revise": { "post": { "operationId": "revise_generation_prompt", "tags": [ "Compose" ], "summary": "修改：对 spec 应用一句指令（免费）/ Apply a one-line change to a spec (free)", "description": "返回新的 spec（revision + 1，parentSpecId 指向旧的）。Returns a new spec with revision + 1.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviseRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "revise_generation_prompt" } }, "/v1/prompts/lint": { "post": { "operationId": "lint_generation_spec", "tags": [ "Compose" ], "summary": "只做代码校验，不调模型（免费）/ Validate a spec without calling a model (free)", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/GenerationSpec" } }, "required": [ "spec" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } }, "ready": { "type": "boolean" } }, "required": [ "success", "diagnostics", "ready" ] } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0 } }, "/v1/presets": { "get": { "operationId": "list_presets", "tags": [ "Catalog" ], "summary": "场景与流派目录（免费，无需鉴权）/ Scenes and genres (free, public)", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetsResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "list_presets" } }, "/v1/capabilities": { "get": { "operationId": "get_capabilities", "tags": [ "Catalog" ], "summary": "启用的模型能力表（免费，无需鉴权）/ Enabled model profiles (free, public)", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } } }, "x-credit-cost": 0 } }, "/v1/songs": { "post": { "operationId": "create_song", "tags": [ "Generate" ], "summary": "一步到位：一句话 → 完整歌曲（扣 1 次）/ One-shot: text in, finished song out (1 credit)", "description": "服务端自动完成编译 → 生成 → 等待。最多等待 `waitSeconds`（默认 120 秒，上限 180）：完成返回 200，超时仍在生成返回 202，之后用 GET /v1/generations/{id} 继续查。扣 1 次额度，返回 2 首候选。\n\nCompiles, submits and waits in one call. Waits up to `waitSeconds` (default 120, max 180): 200 when finished, 202 if still running (keep polling GET /v1/generations/{id}). Costs 1 credit; returns 2 candidate tracks in `generation.clips`. A typical song takes 1–3 minutes.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongRequest" } } } }, "responses": { "200": { "description": "已完成 / Finished (generation.status = finished)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "202": { "description": "仍在生成，请轮询 / Still running; poll get_generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "额度不足 / No credits（NEED_TOPUP、NEED_PURCHASE）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 1 } }, "/v1/generations": { "post": { "operationId": "generate_music", "tags": [ "Generate" ], "summary": "提交生成（扣 1 次）/ Submit a generation (1 credit)", "description": "`spec`（推荐）、`rendered`、`prompt` 三选一。立即返回 202 与 generation id，然后轮询 GET /v1/generations/{id} 或订阅 SSE，直到 status 为 finished（clips[] 有两首候选的 audioUrl）或 failed（自动退回额度）。\n\nProvide one of `spec` (recommended), `rendered` or `prompt`. Returns 202 immediately; poll until `finished` (two clips with audioUrl) or `failed` (credit refunded). Use `idempotencyKey` to make retries safe. Rate limit: 5 submissions per minute per IP.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" } } } }, "responses": { "202": { "description": "已受理 / Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "额度不足 / No credits（NEED_TOPUP、NEED_PURCHASE）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "幂等键冲突 / IDEMPOTENCY_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "供应商拒绝 / PROVIDER_REJECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "供应商不可用 / PROVIDER_UNAVAILABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 1, "x-mcp-tool": "generate_music" } }, "/v1/generations/{id}": { "get": { "operationId": "get_generation", "tags": [ "Generate" ], "summary": "查询生成状态（免费）/ Get a generation (free)", "description": "带 `waitSeconds`（最多 60）时为长轮询：到达终态或超时后返回。公开作品无需鉴权；自己的作品带 Key 查看。\n\nPass `waitSeconds` (max 60) to long-poll: returns as soon as the job finishes or the wait elapses. Public songs need no auth; your own need the key.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "generation id" }, { "name": "waitSeconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 60, "default": 0 }, "description": "长轮询等待秒数 / Long-poll wait, seconds" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationDetailResponse" } } } }, "403": { "description": "无权访问 / FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "不存在 / GENERATION_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "get_generation" } }, "/v1/generations/{id}/events": { "get": { "operationId": "stream_generation_events", "tags": [ "Generate" ], "summary": "SSE 状态流（免费）/ Server-sent events (free)", "description": "`text/event-stream`，每 3 秒一条 `event: status`（data 为 Generation JSON），终态后关闭，最长 10 分钟；出错时 `event: error`。\n\nEmits `status` events every 3 s with the Generation JSON until finished/failed (max 10 min); `error` event on failure.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "generation id" } ], "responses": { "200": { "description": "事件流 / Event stream", "content": { "text/event-stream": { "schema": { "type": "string", "description": "event: status\\ndata: {Generation}\\n\\n" } } } } }, "x-credit-cost": 0 } }, "/v1/generations/{id}/replace-section": { "post": { "operationId": "replace_section", "tags": [ "Edit" ], "summary": "只重做一段（扣 1 次）/ Redo one section (1 credit)", "description": "只重做 `[startS, endS]`，其余保持不变。区间 ≥10 秒且 ≤ 原曲一半。返回新的 generation（parentId 指向原作品）。\n\nRegenerates only the given range; the rest stays. Returns a new generation whose parentId is the original.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "原作品 id / source generation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceSectionRequest" } } } }, "responses": { "202": { "description": "已受理 / Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "额度不足 / No credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "不存在 / GENERATION_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "原作品未完成 / NOT_FINISHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 1, "x-mcp-tool": "replace_section" } }, "/v1/tracks/{id}/stems": { "post": { "operationId": "separate_stems", "tags": [ "Edit" ], "summary": "分轨 / Stem separation", "description": "`separate_vocal`（人声 + 伴奏两轨）：每首歌免费分离一个版本，会员不限。`split_stem`（12 轨）：Pro 会员权益。都不扣生成次数。返回 202，结果在 clips[].stems（用 GET 刷新）。\n\n`separate_vocal` (vocals + instrumental) is free once per song for non-members, unlimited for members. `split_stem` (12 stems) is Pro only. Neither costs generation credits. Poll GET /v1/tracks/{id}/stems until clips[].stems.status is finished.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "generation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StemsRequest" } } } }, "responses": { "202": { "description": "已受理 / Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "PRO_REQUIRED 或 STEMS_ONE_PER_SONG", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "原作品未完成 / NOT_FINISHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端错误 / Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "供应商不支持 / UNSUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "separate_stems" }, "get": { "operationId": "get_stems", "tags": [ "Edit" ], "summary": "刷新分轨状态（免费）/ Refresh stem status (free)", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "generation id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "不存在 / GENERATION_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0 } }, "/v1/tracks": { "get": { "operationId": "list_tracks", "tags": [ "Library" ], "summary": "我的作品（免费）/ My tracks (free)", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracksResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "list_tracks" } }, "/v1/me/credits": { "get": { "operationId": "get_credit_balance", "tags": [ "Account" ], "summary": "可用额度（免费）/ Credit balance (free)", "description": "API / MCP 生成只消耗 `extraCredits`（预付额度）。购买：https://www.musicsforyou.com/developers\n\nAPI and MCP generations draw from `extraCredits` only. Buy more at https://www.musicsforyou.com/developers.", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] }, {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "get_credit_balance" } }, "/v1/me/usage": { "get": { "operationId": "get_usage", "tags": [ "Account" ], "summary": "近 30 天用量（免费）/ Last 30 days usage (free)", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0 } }, "/v1/api-keys": { "get": { "operationId": "list_api_keys", "tags": [ "Keys" ], "summary": "列出 API Key（需网站登录，Key 不能管理 Key）/ List keys (website session only)", "security": [ { "OAuth2": [ "music" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API Key 不能管理 API Key / Keys cannot manage keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0 }, "post": { "operationId": "create_api_key", "tags": [ "Keys" ], "summary": "创建 API Key（明文只显示一次；新 Key 附带 3 次免费额度）/ Create a key (shown once; new keys come with 3 free credits)", "security": [ { "OAuth2": [ "music" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "已创建 / Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API Key 不能管理 API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0 } }, "/v1/api-keys/{id}": { "delete": { "operationId": "revoke_api_key", "tags": [ "Keys" ], "summary": "吊销 API Key / Revoke a key", "security": [ { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "key id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "不存在 / Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "x-credit-cost": 0 } }, "/api/billing/api-pack/checkout": { "post": { "operationId": "get_purchase_link", "tags": [ "Billing" ], "summary": "获取 API 额度包付款链接 / Get a checkout link for an API credit pack", "description": "余额不足时调用：返回一个 Stripe 付款页链接，用户在浏览器付款后额度自动到账（通常 1 分钟内）。packId：api-10-usd（US$9.9 / 10 次）、api-50-usd（US$39 / 50 次）、api-100（¥300 / 100 次）。\n\nCall when credits run out. Returns a Stripe Checkout URL; after the user pays in a browser the credits are added automatically (usually within a minute).", "security": [ { "ApiKeyBearer": [] }, { "OAuth2": [ "music" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "packId" ], "properties": { "packId": { "type": "string", "enum": [ "api-10-usd", "api-50-usd", "api-100" ] } } } } } }, "responses": { "200": { "description": "付款链接 / Checkout link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "orderId": { "type": "string" }, "packId": { "type": "string" }, "credits": { "type": "integer" }, "amount": { "type": "integer", "description": "最小货币单位（分 / 美分）" }, "currency": { "type": "string", "enum": [ "cny", "usd" ] } } } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-credit-cost": 0, "x-mcp-tool": "get_purchase_link" } }, "/v1/api-keys/{id}/webhook": { "put": { "operationId": "set_api_key_webhook", "tags": [ "Keys" ], "summary": "设置该 Key 的完成回调 / Set the key's completion webhook", "description": "作品到达终态（finished / failed）时向 `url` POST JSON `{ event: \"generation.finished\", generation }`，请求头 `X-Taoyuan-Signature: sha256=`。传 `null` 关闭。\n\nWhen a generation started with this key reaches a terminal state, we POST `{ event: \"generation.finished\", generation }` to `url` with header `X-Taoyuan-Signature: sha256=`. Send `null` to turn it off.", "security": [ { "OAuth2": [ "music" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "key id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "不存在 / Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "callbacks": { "generationFinished": { "{$request.body#/url}": { "post": { "summary": "作品完成回调 / Completion webhook", "parameters": [ { "name": "X-Taoyuan-Signature", "in": "header", "required": true, "schema": { "type": "string", "examples": [ "sha256=9f2c…" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "收到即可，返回任意 2xx / Any 2xx acknowledges" } } } } } }, "x-credit-cost": 0 } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "ty_live_…", "description": "开发者 API Key，以 `ty_live_` 开头，在 https://www.musicsforyou.com/developers 创建。请求头 `Authorization: Bearer ty_live_…`。\n\nAPI keys start with `ty_live_`; create one at https://www.musicsforyou.com/developers. Send as `Authorization: Bearer ty_live_…`." }, "OAuth2": { "type": "oauth2", "description": "给 ChatGPT / claude.ai 等连接器用的授权码流程 / Authorization-code flow for connector platforms.", "flows": { "authorizationCode": { "authorizationUrl": "https://www.musicsforyou.com/oauth/authorize", "tokenUrl": "https://api.musicsforyou.com/oauth/token", "scopes": { "music": "编译、生成、查询作品与额度 / Compile, generate, read tracks and credits" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "code": { "type": "string", "description": "稳定的错误码，按它分支 / Stable machine-readable code", "examples": [ "LOGIN_REQUIRED", "NEED_TOPUP", "SPEC_INVALID", "COMPILE_LIMIT", "GENERATION_NOT_FOUND", "FORBIDDEN", "PROVIDER_REJECTED", "PROVIDER_TIMEOUT", "PROVIDER_UNAVAILABLE", "IDEMPOTENCY_CONFLICT", "PRO_REQUIRED", "STEMS_ONE_PER_SONG", "NOT_FINISHED", "UNSUPPORTED", "RATE_LIMIT_EXCEEDED", "INVALID_PARAMS", "INTERNAL_ERROR" ] }, "error": { "type": "string", "description": "给人看的说明（中文为主）/ Human-readable message" }, "details": { "description": "可选的附加信息，SPEC_INVALID 时是 diagnostics 数组 / Optional extra data" } }, "required": [ "success", "code", "error" ], "description": "统一错误信封 / Error envelope. All failures use this shape." }, "UiLanguage": { "type": "string", "enum": [ "zh", "en", "ja" ], "description": "界面/解释文字语言 / Language of explanations" }, "LyricLanguage": { "type": "string", "enum": [ "zh", "yue", "en", "ja" ], "description": "歌词语言 / Lyric language (yue = Cantonese)" }, "VocalPreference": { "type": "string", "enum": [ "m", "f", "duet", "choir" ], "description": "人声偏好 / Vocal preference" }, "GenerationStatus": { "type": "string", "enum": [ "queued", "submitted", "generating", "finished", "failed" ], "description": "queued → submitted → generating → finished | failed" }, "GenerationSource": { "type": "string", "enum": [ "web", "api", "revise", "replace", "agent", "legacy" ] }, "UserLyrics": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 10000, "description": "用户自带歌词 / User-supplied lyrics" }, "action": { "type": "string", "enum": [ "preserve", "edit" ], "description": "preserve 一字不改；edit 允许润色 / preserve = keep verbatim, edit = may polish" } }, "required": [ "text", "action" ] }, "CompileRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "一句话需求，任何语言 / What the song is for, in any language", "examples": [ "给妈妈 60 岁生日写一首温暖的歌，她最爱在厨房唱歌" ] }, "uiLanguage": { "$ref": "#/components/schemas/UiLanguage", "default": "zh" }, "sceneId": { "type": [ "string", "null" ], "description": "场景 id，见 GET /v1/presets / Scene id from list_presets" }, "lyricLanguage": { "oneOf": [ { "$ref": "#/components/schemas/LyricLanguage" }, { "type": "null" } ] }, "vocalPreference": { "oneOf": [ { "$ref": "#/components/schemas/VocalPreference" }, { "type": "null" } ] }, "instrumental": { "type": [ "boolean", "null" ], "description": "纯音乐 / Instrumental only" }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 360, "description": "目标时长（秒）/ Target length in seconds" }, "userLyrics": { "oneOf": [ { "$ref": "#/components/schemas/UserLyrics" }, { "type": "null" } ] }, "clarificationAnswer": { "type": [ "string", "null" ], "maxLength": 500, "description": "对上一次 status=needs_input 的 question 的回答 / Answer to a previous needs_input question" } }, "required": [ "text" ] }, "Rendered": { "type": "object", "properties": { "model": { "type": "string", "description": "供应商模型 id / Provider model id" }, "instrumental": { "type": "boolean" }, "title": { "type": "string" }, "style": { "type": "string", "description": "英文风格标签，逗号分隔 / English style tags, comma separated" }, "lyrics": { "type": [ "string", "null" ], "description": "带 [Verse]/[Chorus] 段落标记的歌词 / Lyrics with section markers" }, "negativeTags": { "type": [ "string", "null" ] }, "vocalGender": { "type": [ "string", "null" ], "enum": [ "m", "f" ] }, "duration": { "type": [ "number", "null" ], "description": "秒 / seconds" } }, "required": [ "model", "instrumental", "title", "style", "lyrics", "negativeTags", "vocalGender", "duration" ], "description": "可直接提交生成的字段 / Fields ready to submit to generate_music" }, "Diagnostic": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "path": { "type": "string" }, "message": { "type": "string" }, "autoFixable": { "type": "boolean" } }, "required": [ "code", "severity", "path", "message", "autoFixable" ] }, "PersonalFact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "relationship", "date", "place", "memory", "phrase", "trait" ] }, "value": { "type": "string" }, "sourceQuote": { "type": "string" }, "inclusion": { "type": "string", "enum": [ "required", "optional" ] }, "preservation": { "type": "string", "enum": [ "exact", "semantic" ] }, "preferredSection": { "type": "string", "enum": [ "chorus", "verse", "bridge", "any" ] } }, "required": [ "id", "kind", "value", "sourceQuote", "inclusion", "preservation", "preferredSection" ] }, "IntentSpec": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "song", "instrumental" ] }, "sceneId": { "type": [ "string", "null" ] }, "genreRefs": { "type": "array", "items": { "type": "string" } }, "lyricLanguage": { "oneOf": [ { "$ref": "#/components/schemas/LyricLanguage" }, { "type": "null" } ] }, "vocalPreference": { "oneOf": [ { "$ref": "#/components/schemas/VocalPreference" }, { "type": "null" } ] }, "moods": { "type": "array", "items": { "type": "string" } }, "tempoFeel": { "type": [ "string", "null" ] }, "artistRefs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "requestedTraits": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "requestedTraits" ] } }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFact" } }, "exclusions": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "sourceQuote": { "type": "string" } }, "required": [ "term", "sourceQuote" ] } }, "durationSeconds": { "type": [ "number", "null" ] }, "assumptions": { "type": "array", "items": { "type": "string" } }, "clarification": { "type": [ "object", "null" ], "properties": { "question": { "type": "string" }, "field": { "type": "string" } }, "required": [ "question", "field" ] } }, "required": [ "kind", "sceneId", "genreRefs", "lyricLanguage", "vocalPreference", "moods", "tempoFeel", "artistRefs", "facts", "exclusions", "durationSeconds", "assumptions", "clarification" ], "description": "解析出的意图 / Parsed intent" }, "Section": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "intro", "verse", "pre_chorus", "chorus", "post_chorus", "bridge", "instrumental", "outro" ] }, "label": { "type": "string", "examples": [ "Verse 1", "Chorus" ] }, "cues": { "type": "array", "items": { "type": "string" }, "description": "段落级表演提示 / Performance cues" }, "lines": { "type": "array", "items": { "type": "string" }, "description": "歌词行；器乐段为空 / Lyric lines, empty for instrumental sections" }, "usedFactIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "label", "cues", "lines", "usedFactIds" ] }, "CompositionPlan": { "type": "object", "properties": { "title": { "type": "string" }, "titleAlternatives": { "type": "array", "items": { "type": "string" } }, "centralIdea": { "type": "string" }, "hook": { "type": [ "string", "null" ] }, "genre": { "type": "object", "properties": { "primary": { "type": "string" }, "accents": { "type": "array", "items": { "type": "string" } } }, "required": [ "primary", "accents" ] }, "tempo": { "type": "object", "properties": { "feel": { "type": "string" }, "bpmHint": { "type": [ "number", "null" ] } }, "required": [ "feel", "bpmHint" ] }, "instruments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "enum": [ "lead", "rhythm", "harmony", "accent" ] } }, "required": [ "name", "role" ] } }, "vocal": { "type": [ "object", "null" ], "properties": { "gender": { "type": [ "string", "null" ], "enum": [ "m", "f" ] }, "texture": { "type": "string" } }, "required": [ "gender", "texture" ] }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "styleDraft": { "type": "object", "properties": { "identity": { "type": "string" }, "mood": { "type": "string" }, "rhythm": { "type": "string" }, "instrumentation": { "type": "string" }, "production": { "type": "string" } }, "required": [ "identity", "mood", "rhythm", "instrumentation", "production" ] }, "exclusions": { "type": "array", "items": { "type": "string" } }, "explanation": { "type": "string" } }, "required": [ "title", "titleAlternatives", "centralIdea", "hook", "genre", "tempo", "instruments", "vocal", "sections", "styleDraft", "exclusions", "explanation" ], "description": "作曲方案 / Composition plan" }, "CompileRequestEcho": { "type": "object", "properties": { "userText": { "type": "string" }, "uiLanguage": { "$ref": "#/components/schemas/UiLanguage" }, "sceneId": { "type": [ "string", "null" ] }, "lyricLanguage": { "oneOf": [ { "$ref": "#/components/schemas/LyricLanguage" }, { "type": "null" } ] }, "vocalPreference": { "oneOf": [ { "$ref": "#/components/schemas/VocalPreference" }, { "type": "null" } ] }, "instrumental": { "type": [ "boolean", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "userLyrics": { "oneOf": [ { "$ref": "#/components/schemas/UserLyrics" }, { "type": "null" } ] }, "clarificationAnswer": { "type": [ "string", "null" ] } }, "required": [ "userText", "uiLanguage" ] }, "Provenance": { "type": "object", "properties": { "compilerVersion": { "type": "string" }, "parserModel": { "type": [ "string", "null" ] }, "composerModel": { "type": [ "string", "null" ] }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "llmCalls": { "type": "number" }, "cached": { "type": "boolean" } }, "required": [ "compilerVersion", "parserModel", "composerModel", "knowledgeIds", "llmCalls", "cached" ] }, "GenerationSpec": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "3.0" }, "id": { "type": "string" }, "revision": { "type": "integer" }, "parentSpecId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "needs_input", "needs_revision" ], "description": "ready 可提交；needs_input 看 question 追问；needs_revision 看 error 级 diagnostics / ready = submit; needs_input = ask `question`; needs_revision = fix error diagnostics" }, "profileId": { "type": "string" }, "request": { "$ref": "#/components/schemas/CompileRequestEcho" }, "intent": { "oneOf": [ { "$ref": "#/components/schemas/IntentSpec" }, { "type": "null" } ] }, "composition": { "oneOf": [ { "$ref": "#/components/schemas/CompositionPlan" }, { "type": "null" } ] }, "rendered": { "oneOf": [ { "$ref": "#/components/schemas/Rendered" }, { "type": "null" } ] }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } }, "question": { "type": [ "object", "null" ], "properties": { "question": { "type": "string" }, "field": { "type": "string" } }, "required": [ "question", "field" ] }, "explanation": { "type": "string", "description": "给用户看的解释 / Explanation for the end user" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "schemaVersion", "id", "revision", "parentSpecId", "status", "profileId", "request", "intent", "composition", "rendered", "diagnostics", "question", "explanation", "provenance" ], "description": "编译结果（GenerationSpec v3）。原样回传给 POST /v1/generations 即可生成 / Compiled spec; pass it back unchanged to generate." }, "ReviseRequest": { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/GenerationSpec" }, "instruction": { "type": "string", "minLength": 1, "maxLength": 500, "description": "一句修改指令 / One-sentence change request", "examples": [ "副歌更有力", "换成女声" ] }, "locks": { "type": "object", "properties": { "lyrics": { "type": "boolean" }, "title": { "type": "boolean" }, "sectionIds": { "type": "array", "items": { "type": "string" } } }, "description": "锁定不改的部分 / Parts to keep unchanged" } }, "required": [ "spec", "instruction" ] }, "RenderedInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "style": { "type": "string", "maxLength": 2000 }, "lyrics": { "type": [ "string", "null" ], "maxLength": 10000 }, "negativeTags": { "type": [ "string", "null" ], "maxLength": 500 }, "vocalGender": { "type": [ "string", "null" ], "enum": [ "m", "f" ] }, "styleWeight": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "weirdnessConstraint": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "audioWeight": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "duration": { "type": [ "integer", "null" ] } }, "required": [ "title", "style" ], "description": "高级模式：直接给渲染字段 / Advanced: submit rendered fields directly" }, "GenerateRequest": { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/GenerationSpec", "description": "推荐：compile 返回的 spec，服务端会重新校验 / Recommended: the spec from compile (re-linted server side)" }, "rendered": { "$ref": "#/components/schemas/RenderedInput" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 3000, "description": "不经编译的一句描述，由供应商自己写词 / Plain prompt, provider writes lyrics itself" }, "instrumental": { "type": "boolean", "default": false }, "model": { "type": "string", "description": "可选模型 id / Optional model id (see GET /v1/capabilities)" }, "parentId": { "type": "string", "description": "作为哪首作品的修改版 / Parent generation id" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128, "description": "幂等键：同键重复提交返回同一条 generation / Idempotency key" } }, "description": "spec、rendered、prompt 三选一 / Provide exactly one of spec, rendered or prompt", "anyOf": [ { "required": [ "spec" ] }, { "required": [ "rendered" ] }, { "required": [ "prompt" ] } ] }, "ClipStems": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "separate_vocal", "split_stem" ] }, "status": { "type": "string", "enum": [ "pending", "finished", "failed" ] }, "taskId": { "type": "string" }, "files": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" }, "description": "轨名 → 音频地址（vocals, instrumental, drums, bass…）/ stem name → audio URL" }, "error": { "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "mode", "status", "taskId", "files", "requestedAt" ] }, "Clip": { "type": "object", "properties": { "id": { "type": "string" }, "audioUrl": { "type": "string", "format": "uri", "description": "完整音频（finished 后可用）/ Full audio URL once finished" }, "streamAudioUrl": { "type": [ "string", "null" ], "format": "uri" }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "sourceImageUrl": { "type": [ "string", "null" ], "format": "uri" }, "title": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ], "description": "秒 / seconds" }, "tags": { "type": [ "string", "null" ] }, "lyrics": { "type": [ "string", "null" ] }, "modelName": { "type": [ "string", "null" ] }, "stems": { "oneOf": [ { "$ref": "#/components/schemas/ClipStems" }, { "type": "null" } ] } }, "required": [ "id", "audioUrl" ], "description": "一首候选 / One candidate track. Each generation returns two." }, "Cover": { "type": "object", "properties": { "status": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "artworkUrl": { "type": [ "string", "null" ], "format": "uri" }, "styleId": { "type": [ "string", "null" ] }, "conceptId": { "type": [ "string", "null" ] }, "titleSafeZone": { "type": [ "string", "null" ] }, "latencyMs": { "type": [ "number", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "status", "url", "artworkUrl" ] }, "Generation": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/GenerationStatus" }, "source": { "$ref": "#/components/schemas/GenerationSource" }, "parentId": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "inputPrompt": { "type": "string" }, "spec": { "oneOf": [ { "$ref": "#/components/schemas/GenerationSpec" }, { "type": "null" } ] }, "clips": { "type": "array", "items": { "$ref": "#/components/schemas/Clip" }, "description": "finished 时通常 2 首 / Usually 2 candidates when finished" }, "coverUrl": { "type": [ "string", "null" ], "format": "uri", "description": "正式封面 / Cover image" }, "cover": { "oneOf": [ { "$ref": "#/components/schemas/Cover" }, { "type": "null" } ] }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "creditSource": { "type": [ "string", "null" ], "enum": [ "monthly", "credit", "unlimited" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "status", "source", "parentId", "model", "title", "inputPrompt", "spec", "clips", "coverUrl", "cover", "errorCode", "errorMessage", "creditSource", "createdAt", "finishedAt" ], "description": "一次生成任务 / A generation job. Poll until status is finished or failed." }, "GenerationDetail": { "allOf": [ { "$ref": "#/components/schemas/Generation" }, { "type": "object", "properties": { "author": { "type": [ "object", "null" ], "properties": { "displayName": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "displayName", "avatarUrl" ] }, "isOwner": { "type": "boolean" }, "stats": { "type": "object", "properties": { "plays": { "type": "integer" }, "likes": { "type": "integer" }, "liked": { "type": "boolean" } }, "required": [ "plays", "likes", "liked" ] } } } ] }, "GenerationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "generation": { "$ref": "#/components/schemas/Generation" } }, "required": [ "success", "generation" ] }, "GenerationDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "generation": { "$ref": "#/components/schemas/GenerationDetail" } }, "required": [ "success", "generation" ] }, "SpecResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "spec": { "$ref": "#/components/schemas/GenerationSpec" } }, "required": [ "success", "spec" ] }, "SongRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "一句话需求 / What the song is for", "examples": [ "A warm birthday song for my mom who loves singing in the kitchen" ] }, "uiLanguage": { "$ref": "#/components/schemas/UiLanguage", "default": "zh" }, "lyricLanguage": { "oneOf": [ { "$ref": "#/components/schemas/LyricLanguage" }, { "type": "null" } ] }, "vocalPreference": { "oneOf": [ { "$ref": "#/components/schemas/VocalPreference" }, { "type": "null" } ] }, "instrumental": { "type": [ "boolean", "null" ] }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 360 }, "waitSeconds": { "type": "integer", "minimum": 0, "maximum": 180, "default": 120, "description": "最多等待多少秒再返回；0 表示立即返回 / How long to wait for the song before returning; 0 returns immediately" } }, "required": [ "text" ] }, "ReplaceSectionRequest": { "type": "object", "properties": { "clipId": { "type": "string", "description": "要改的候选 / Which clip to edit" }, "startS": { "type": "number", "minimum": 0, "description": "起点（秒）/ Start, seconds" }, "endS": { "type": "number", "minimum": 0, "description": "终点（秒）。区间 ≥10 秒且 ≤ 原曲一半 / End, seconds. Range must be ≥10 s and ≤ half the song" }, "sectionLyrics": { "type": "string", "maxLength": 3000, "default": "", "description": "这一段的新歌词；纯音乐留空 / New lyrics for the section; empty for instrumental" }, "fullLyrics": { "type": [ "string", "null" ], "maxLength": 10000, "description": "替换后的完整歌词 / Full lyrics after the change" }, "style": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "clipId", "startS", "endS" ] }, "StemsRequest": { "type": "object", "properties": { "clipId": { "type": "string" }, "mode": { "type": "string", "enum": [ "separate_vocal", "split_stem" ], "default": "separate_vocal", "description": "separate_vocal = 人声/伴奏两轨；split_stem = 12 轨（Pro）/ separate_vocal = vocals + instrumental; split_stem = 12 stems (Pro only)" } }, "required": [ "clipId" ] }, "Preset": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "defaultKind": { "type": [ "string", "null" ], "enum": [ "song", "instrumental" ] }, "defaultDuration": { "type": [ "number", "null" ] } }, "required": [ "id", "title", "aliases" ] }, "PresetsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } }, "genres": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } } }, "required": [ "success", "scenes", "genres" ] }, "CapabilityProfile": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "mode": { "type": "string" }, "enabledForProduction": { "type": "boolean" }, "limits": { "type": "object", "properties": { "style": { "type": "integer" }, "prompt": { "type": "integer" }, "title": { "type": "integer" } } }, "duration": { "type": "object", "properties": { "supported": { "type": "boolean" }, "min": { "type": "integer" }, "max": { "type": "integer" } } }, "supports": { "type": "object", "additionalProperties": { "type": "boolean" } }, "verifiedAt": { "type": "string" }, "verification": { "type": "string" } }, "required": [ "id", "provider", "model" ] }, "CapabilitiesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "defaultProfile": { "type": "string" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityProfile" } } }, "required": [ "success", "defaultProfile", "profiles" ] }, "CreditsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "plan": { "type": "string", "enum": [ "guest", "free", "pro", "vip", "admin" ] }, "remaining": { "type": "integer", "description": "当前可用生成次数（API 只能用 extraCredits）/ Generations available; API calls draw from extraCredits only" }, "monthlyCount": { "type": "integer" }, "monthlyLimit": { "type": [ "integer", "null" ] }, "extraCredits": { "type": "integer", "description": "预付额度 / Prepaid credits usable by API and MCP" }, "planExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "todayCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "trial": { "type": [ "object", "null" ], "properties": { "credits": { "type": "integer" }, "grantedAt": { "type": "string", "format": "date-time" } } }, "requiresLogin": { "type": "boolean" } }, "required": [ "success", "plan", "remaining", "extraCredits", "requiresLogin" ] }, "UsageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "since": { "type": "string", "format": "date-time" }, "bySource": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "近 30 天按来源计数：web / api / agent / revise / replace" }, "apiCount30d": { "type": "integer" }, "totalCount30d": { "type": "integer" }, "extraCredits": { "type": "integer" }, "plan": { "type": "string" } }, "required": [ "success", "since", "bySource", "apiCount30d", "totalCount30d", "extraCredits", "plan" ] }, "TracksResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "success", "items", "total", "page", "pageSize", "totalPages" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "例如 ty_live_ab12cd… / Masked prefix" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "webhookUrl": { "type": [ "string", "null" ], "format": "uri", "description": "完成回调地址 / Completion webhook URL" } }, "required": [ "id", "name", "prefix", "lastUsedAt", "createdAt" ] }, "ApiKeysResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "success", "keys" ] }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64, "default": "default" } } }, "CreateApiKeyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "key": { "type": "string", "description": "完整 Key，只返回这一次 / Full key, shown only once" }, "apiKey": { "$ref": "#/components/schemas/ApiKey" }, "note": { "type": "string" } }, "required": [ "success", "key", "apiKey" ] }, "WebhookRequest": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "HTTPS 地址；null 表示关闭 / HTTPS URL, or null to turn off" } }, "required": [ "url" ] }, "WebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "webhookUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "success", "webhookUrl" ] }, "WebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "const": "generation.finished" }, "generation": { "$ref": "#/components/schemas/Generation" } }, "required": [ "event", "generation" ], "description": "作品完成（或失败）时 POST 到 webhook 的 JSON / Body POSTed to your webhook when a generation reaches a terminal state" }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } }, "x-taoyuan": { "mcp": { "url": "https://api.musicsforyou.com/mcp", "transport": "streamable-http", "auth": "Authorization: Bearer ty_live_…" }, "llmsTxt": "https://www.musicsforyou.com/llms.txt", "developers": "https://www.musicsforyou.com/developers", "openapi": { "v31": "https://api.musicsforyou.com/openapi.json", "v30": "https://api.musicsforyou.com/openapi-coze.json" }, "credits": { "generate_music": 1, "create_song": 1, "replace_section": 1, "compile_music_prompt": 0, "revise_generation_prompt": 0, "get_generation": 0, "list_tracks": 0, "list_presets": 0, "get_credit_balance": 0, "separate_stems": "2-track free once per song for non-members, unlimited for members; 12-stem Pro only; no credits" }, "rateLimits": { "generate": "5 / minute / IP", "compile": "30 / hour / account; guests 5 / day / IP" }, "packs": [ { "id": "api-100", "currency": "CNY", "price": 300, "credits": 100 }, { "id": "api-10-usd", "currency": "USD", "price": 9.9, "credits": 10 }, { "id": "api-50-usd", "currency": "USD", "price": 39, "credits": 50 } ], "agentNotes": [ "Show the user the compiled title, lyrics and style before spending a credit.", "Poll get_generation every 5–10 s; a song usually takes 1–3 minutes. Or use POST /v1/songs with waitSeconds.", "Always pass idempotencyKey when retrying generate_music.", "Songs made through the API may be used commercially by the key owner." ] } }