创建作曲计划

POST 
https://api.knoxstudio.ai/v1/music/plan

将文本提示转为结构化作曲计划（风格、段落、歌词、时长）。不计费，但受速率限制。将结果作为 composition_plan 传给 作曲。

请求

请求头

名称	类型	必填	描述
Authorization	String	是	Bearer <token> Knox API key。也接受 xi-api-key。
Content-Type	String	是	application/json。

请求体

名称	类型	必填	描述
prompt	String	是	用于规划的提示词。
music_length_ms	Integer	否	计划时长（毫秒），3000–300000。
model_id	String	否	music_v1（默认）、music_v2 或 music_v2_5。控制计划格式。
source_composition_plan	Object	否	用于迭代的已有计划。

后续按计划作曲时的段落约束：名称 1–100 字符，时长 3000–120000ms，每段最多 30 行，每行 200 字符。风格标签建议使用英文。

cURL 示例

curl -X POST https://api.knoxstudio.ai/v1/music/plan \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "prompt": "一首两分钟的关于秋叶的民谣",
  "music_length_ms": 120000,
  "model_id": "music_v2_5"
}'

响应

成功响应 (200)

MusicPrompt 或 CompositionPlan 对象。MusicPrompt 包含 positive_global_styles、negative_global_styles 和 sections[]（section_name、局部风格、duration_ms、lines）。CompositionPlan 使用 chunks[]，含 text、duration_ms、positive_styles、可选 negative_styles、context_adherence（low / medium / high）以及可选 conditioning_ref。

错误响应

校验失败返回 HTTP 422：

{
  "detail": [
    {
      "loc": ["body", "field"],
      "msg": "…",
      "type": "value_error"
    }
  ]
}

其他错误使用 { "detail": "message" }。

状态	何时
400	未携带 Upgrade: websocket 访问 WebSocket 路径。
401	缺少或无效的 API key。
402	余额不足。
403	Token 无权使用该模型。
404	资源不存在。
422	校验错误。
429	超出速率限制。
500	服务器内部错误。