--- title: "一步到位：一句话 → 完整歌曲（扣 1 次）/ One-shot: text in, finished song out (1 credit)" method: POST path: "/v1/songs" tags: ["Generate"] --- # 一步到位：一句话 → 完整歌曲（扣 1 次）/ One-shot: text in, finished song out (1 credit) `POST /v1/songs` ## Request - Base URL: `https://api.musicsforyou.com` - URL: `https://api.musicsforyou.com/v1/songs` - Auth: one of: - HTTP bearer - OAuth 2 (authorization code, authorization URL `https://www.musicsforyou.com/oauth/authorize`, token URL `https://api.musicsforyou.com/oauth/token`, scopes: `music`) 服务端自动完成编译 → 生成 → 等待。最多等待 `waitSeconds`（默认 120 秒，上限 180）：完成返回 200，超时仍在生成返回 202，之后用 GET /v1/generations/{id} 继续查。扣 1 次额度，返回 2 首候选。 Compiles, 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. ## Request body - SongRequest - `text` string, required: 一句话需求 / What the song is for - `uiLanguage` 'zh' | 'en' | 'ja': 界面/解释文字语言 / Language of explanations - `lyricLanguage` 'zh' | 'yue' | 'en' | 'ja': 歌词语言 / Lyric language (yue = Cantonese) - `vocalPreference` 'm' | 'f' | 'duet' | 'choir': 人声偏好 / Vocal preference - `instrumental` boolean, nullable - `durationSeconds` integer, nullable - `waitSeconds` integer: 最多等待多少秒再返回；0 表示立即返回 / How long to wait for the song before returning; 0 returns immediately ## Response `200` 已完成 / Finished (generation.status = finished) - GenerationResponse - `success` true, required - `generation` Generation, required: 一次生成任务 / A generation job. Poll until status is finished or failed. - `id` string, required - `status` 'queued' | 'submitted' | 'generating' | 'finished' | 'failed', required: queued → submitted → generating → finished | failed - `source` 'web' | 'api' | 'revise' | 'replace' | 'agent' | 'legacy', required - `parentId` string, nullable, required - `model` string, nullable, required - `title` string, nullable, required - `inputPrompt` string, required - `spec` GenerationSpec, required: 编译结果（GenerationSpec v3）。原样回传给 POST /v1/generations 即可生成 / Compiled spec; pass it back unchanged to generate. - `schemaVersion` '3.0', required - `id` string, required - `revision` integer, required - `parentSpecId` string, nullable, required - `status` 'ready' | 'needs_input' | 'needs_revision', required: ready 可提交；needs_input 看 question 追问；needs_revision 看 error 级 diagnostics / ready = submit; needs_input = ask `question`; needs_revision = fix error diagnostics - `profileId` string, required - `request` CompileRequestEcho, required - `userText` string, required - `uiLanguage` 'zh' | 'en' | 'ja', required: 界面/解释文字语言 / Language of explanations - `sceneId` string, nullable - `lyricLanguage` 'zh' | 'yue' | 'en' | 'ja': 歌词语言 / Lyric language (yue = Cantonese) - `vocalPreference` 'm' | 'f' | 'duet' | 'choir': 人声偏好 / Vocal preference - `instrumental` boolean, nullable - `durationSeconds` number, nullable - `userLyrics` UserLyrics - `text` string, required: 用户自带歌词 / User-supplied lyrics - `action` 'preserve' | 'edit', required: preserve 一字不改；edit 允许润色 / preserve = keep verbatim, edit = may polish - `clarificationAnswer` string, nullable - `intent` IntentSpec, required: 解析出的意图 / Parsed intent - `kind` 'song' | 'instrumental', required - `sceneId` string, nullable, required - `genreRefs` string[], required - `lyricLanguage` 'zh' | 'yue' | 'en' | 'ja', required: 歌词语言 / Lyric language (yue = Cantonese) - `vocalPreference` 'm' | 'f' | 'duet' | 'choir', required: 人声偏好 / Vocal preference - `moods` string[], required - `tempoFeel` string, nullable, required - `artistRefs` object[], required - `name` string, required - `requestedTraits` string[], required - `facts` PersonalFact[], required - `id` string, required - `kind` 'person' | 'relationship' | 'date' | 'place' | 'memory' | 'phrase' | 'trait', required - `value` string, required - `sourceQuote` string, required - `inclusion` 'required' | 'optional', required - `preservation` 'exact' | 'semantic', required - `preferredSection` 'chorus' | 'verse' | 'bridge' | 'any', required - `exclusions` object[], required - `term` string, required - `sourceQuote` string, required - `durationSeconds` number, nullable, required - `assumptions` string[], required - `clarification` object, nullable, required - `question` string, required - `field` string, required - `composition` CompositionPlan, required: 作曲方案 / Composition plan - `title` string, required - `titleAlternatives` string[], required - `centralIdea` string, required - `hook` string, nullable, required - `genre` object, required - `primary` string, required - `accents` string[], required - `tempo` object, required - `feel` string, required - `bpmHint` number, nullable, required - `instruments` object[], required - `name` string, required - `role` 'lead' | 'rhythm' | 'harmony' | 'accent', required - `vocal` object, nullable, required - `gender` 'm' | 'f', nullable, required - `texture` string, required - `sections` Section[], required - `id` string, required - `kind` 'intro' | 'verse' | 'pre_chorus' | 'chorus' | 'post_chorus' | 'bridge' | 'instrumental' | 'outro', required - `label` string, required - `cues` string[], required: 段落级表演提示 / Performance cues - `lines` string[], required: 歌词行；器乐段为空 / Lyric lines, empty for instrumental sections - `usedFactIds` string[], required - `styleDraft` object, required - `identity` string, required - `mood` string, required - `rhythm` string, required - `instrumentation` string, required - `production` string, required - `exclusions` string[], required - `explanation` string, required - `rendered` Rendered, required: 可直接提交生成的字段 / Fields ready to submit to generate_music - `model` string, required: 供应商模型 id / Provider model id - `instrumental` boolean, required - `title` string, required - `style` string, required: 英文风格标签，逗号分隔 / English style tags, comma separated - `lyrics` string, nullable, required: 带 [Verse]/[Chorus] 段落标记的歌词 / Lyrics with section markers - `negativeTags` string, nullable, required - `vocalGender` 'm' | 'f', nullable, required - `duration` number, nullable, required: 秒 / seconds - `diagnostics` Diagnostic[], required - `code` string, required - `severity` 'error' | 'warning' | 'info', required - `path` string, required - `message` string, required - `autoFixable` boolean, required - `question` object, nullable, required - `question` string, required - `field` string, required - `explanation` string, required: 给用户看的解释 / Explanation for the end user - `provenance` Provenance, required - `compilerVersion` string, required - `parserModel` string, nullable, required - `composerModel` string, nullable, required - `knowledgeIds` string[], required - `llmCalls` number, required - `cached` boolean, required - `clips` Clip[], required: finished 时通常 2 首 / Usually 2 candidates when finished - `id` string, required - `audioUrl` string, uri, required: 完整音频（finished 后可用）/ Full audio URL once finished - `streamAudioUrl` string, uri, nullable - `imageUrl` string, uri, nullable - `sourceImageUrl` string, uri, nullable - `title` string, nullable - `duration` number, nullable: 秒 / seconds - `tags` string, nullable - `lyrics` string, nullable - `modelName` string, nullable - `stems` ClipStems - `mode` 'separate_vocal' | 'split_stem', required - `status` 'pending' | 'finished' | 'failed', required - `taskId` string, required - `files` object, required: 轨名 → 音频地址（vocals, instrumental, drums, bass…）/ stem name → audio URL - `error` string, nullable - `requestedAt` string, date-time, required - `finishedAt` string, date-time, nullable - `coverUrl` string, uri, nullable, required: 正式封面 / Cover image - `cover` Cover, required - `status` string, required - `url` string, uri, nullable, required - `artworkUrl` string, uri, nullable, required - `styleId` string, nullable - `conceptId` string, nullable - `titleSafeZone` string, nullable - `latencyMs` number, nullable - `errorCode` string, nullable - `updatedAt` string, nullable - `errorCode` string, nullable, required - `errorMessage` string, nullable, required - `creditSource` 'monthly' | 'credit' | 'unlimited', nullable, required - `createdAt` string, date-time, required - `finishedAt` string, date-time, nullable, required ## Other responses - `202`: 仍在生成，请轮询 / Still running; poll get_generation - `400`: 参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics） - `401`: 未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY） - `402`: 额度不足 / No credits（NEED_TOPUP、NEED_PURCHASE） - `429`: 请求过于频繁 / Rate limited（RATE_LIMIT_EXCEEDED、COMPILE_LIMIT） - `500`: 服务端错误 / Internal error --- [API](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api.md) · [All operations](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api/llms.txt) · [OpenAPI document](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api/revisions/65b8919a4d82?raw)