---
title: "编译：一句需求 → 歌词与风格（免费）/ Compile a request into a spec (free)"
method: POST
path: "/v1/prompts/compile"
tags: ["Compose"]
---

# 编译：一句需求 → 歌词与风格（免费）/ Compile a request into a spec (free)

`POST /v1/prompts/compile`

## Request

- Base URL: `https://api.musicsforyou.com`
- URL: `https://api.musicsforyou.com/v1/prompts/compile`
- 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`)
  - none

把一句自然语言需求编译成可直接生成的 GenerationSpec：标题、英文风格标签、带段落标记的歌词、负面标签、时长。不扣额度。

Turns 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.

## Request body

- CompileRequest
  - `text` string, required: 一句话需求，任何语言 / What the song is for, in any language
  - `uiLanguage` 'zh' | 'en' | 'ja': 界面/解释文字语言 / Language of explanations
  - `sceneId` string, nullable: 场景 id，见 GET /v1/presets / Scene id from list_presets
  - `lyricLanguage` 'zh' | 'yue' | 'en' | 'ja': 歌词语言 / Lyric language (yue = Cantonese)
  - `vocalPreference` 'm' | 'f' | 'duet' | 'choir': 人声偏好 / Vocal preference
  - `instrumental` boolean, nullable: 纯音乐 / Instrumental only
  - `durationSeconds` integer, nullable: 目标时长（秒）/ Target length in seconds
  - `userLyrics` UserLyrics
    - `text` string, required: 用户自带歌词 / User-supplied lyrics
    - `action` 'preserve' | 'edit', required: preserve 一字不改；edit 允许润色 / preserve = keep verbatim, edit = may polish
  - `clarificationAnswer` string, nullable: 对上一次 status=needs_input 的 question 的回答 / Answer to a previous needs_input question

## Response `200`

编译结果 / Compiled spec

- SpecResponse
  - `success` true, 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

## Other responses

- `400`: 参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）
- `401`: 未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）
- `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)