# ElevenLabs Music V2.5 元数据音乐生成

> 音频生成

生成音乐并返回 `multipart/mixed` 响应：一部分是 JSON 元数据（实际使用的 `composition_plan` 与 `song_metadata`），
另一部分是音频二进制数据。响应由网关原样透传上游，客户端需按 boundary 自行解析。

该端点是唯一支持 `with_timestamps`、`with_waveform_visual` 的端点。
`respect_sections_durations` 在 `music-v2.5` 下不生效（段时长恒为强制值），传了也会被网关丢弃。

## 请求地址

`POST https://api.modelverse.cn/v1/audio/music/detailed`

## 请求体

## 响应

- **200** — 包含 JSON 元数据与音频二进制数据的 multipart/mixed 响应。
- **400** — 
- **default** — 

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "elevenlabs-music-v2.5接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `elevenlabs-music-v2.5` 的音乐生成接口文档，说明如何提交音乐生成请求、读取结果以及处理错误。\n接口路径包括 `POST /v1/audio/music/generate`、`POST /v1/audio/music/stream`、`POST /v1/audio/music/detailed`、`POST /v1/audio/music/plan`。\n\n## 与 music-v1 的差异\n\n| 能力 | music-v1 | music-v2.5 |\n|------|----------|------------|\n| 曲谱结构 | `composition_plan.sections`（乐章） | `composition_plan.chunks`（片段） |\n| 段时长控制 | `respect_sections_durations` 可开关 | 恒为强制段时长，该参数被忽略 |\n| 音频条件参考 | 不支持 | `chunks[].conditioning_ref`（inpainting） |\n| 生成后保存歌曲 | 不支持 | `store_for_inpainting: true` + 响应头 `X-Song-Id` |\n| 波形可视化 | 不支持 | `/v1/audio/music/detailed` 的 `with_waveform_visual` |\n| 默认输出格式 | `mp3_44100_128` | `mp3_48000_192`（均可通过 `output_format` 覆盖） |\n\n> 官方已将 `music_v1` 标记为 deprecated，新业务建议直接使用 `music-v2.5`。\n\n## 两种生成模式\n\n- `input` 模式：用一句自然语言描述生成音乐，必须传 `music_length_ms`（3000-600000）。\n- `composition_plan` 模式：用结构化曲谱（`chunks`）精确控制每一段的歌词、时长与风格，禁止传 `music_length_ms`，总时长由各 chunk 的 `duration_ms` 加总得到。\n\n`input` 与 `composition_plan` 互斥，必须二选一。\n\n## 计费说明\n\n网关按实际生成时长计费，时长取 `music_length_ms` 或 `composition_plan.chunks[].duration_ms` 之和，向上取整到秒。\n`/v1/audio/music/plan` 只生成编曲计划、不生成音频，**不消耗额度**（仅记录调用审计）。\n\n## 参数兼容说明\n\n以下参数在网关层已做前置校验，命中时直接返回 400，不会请求上游：\n\n- `input` 与 `composition_plan` 同时传；\n- `composition_plan` 模式下传了 `music_length_ms`；\n- `input` 模式下 `music_length_ms` 缺失或不在 3000-600000 范围内；\n- `seed` 与 `input` 同时使用（`seed` 只能配合 `composition_plan`）；\n- `force_instrumental` 与 `composition_plan` 同时使用（只能配合 `input`）；\n- `composition_plan.chunks` 超过 30 个、单个 chunk 的 `duration_ms` 不在 3000-120000 范围内、缺少 `text`/`positive_styles`，或总时长超过 600000。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint shown in the source document."
    }
  ],
  "tags": [
    {
      "name": "ElevenLabs Music V2.5",
      "description": "ElevenLabs `music-v2.5` 音乐生成和编曲计划接口。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/music/generate": {
      "post": {
        "tags": [
          "ElevenLabs Music V2.5"
        ],
        "operationId": "createElevenLabsMusicV25Generation",
        "summary": "ElevenLabs Music V2.5 音乐生成",
        "description": "生成音乐并直接返回音频二进制流。\n\n- `input` 模式：传 `input` + `music_length_ms`；\n- `composition_plan` 模式：传 `composition_plan.chunks`，不要传 `music_length_ms`。\n\n响应头 `X-Song-Id` 为该次生成歌曲的唯一标识；若请求时传了 `store_for_inpainting: true`，\n后续可用该 ID 在 `chunks[].conditioning_ref.song_id` 中引用这段音频。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ElevenLabsMusicV25GenerationRequest"
              },
              "examples": {
                "promptMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePromptRequest"
                },
                "compositionPlanMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePlanRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "生成的音频二进制流。",
            "headers": {
              "X-Song-Id": {
                "description": "生成歌曲的唯一标识（网关将上游 `song-id` 响应头重命名为 `X-Song-Id`）。",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "audio/mpeg": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary"
                },
                "examples": {
                  "generatedMp3": {
                    "summary": "生成的 MP3 字节流",
                    "value": "<binary MP3 audio bytes>"
                  }
                }
              },
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary"
                },
                "examples": {
                  "generatedAudio": {
                    "summary": "生成的音频字节流",
                    "value": "<binary audio bytes>"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest"
          },
          "default": {
            "$ref": "#/components/responses/ElevenLabsMusicV25Error"
          }
        }
      }
    },
    "/v1/audio/music/stream": {
      "post": {
        "tags": [
          "ElevenLabs Music V2.5"
        ],
        "operationId": "streamElevenLabsMusicV25Generation",
        "summary": "ElevenLabs Music V2.5 流式音乐生成",
        "description": "流式生成音乐。接口直接返回音频字节流，适合边生成边播放。\n\n请求体与 `/v1/audio/music/generate` 完全一致；注意该端点不支持 `with_timestamps`、\n`with_waveform_visual`、`respect_sections_durations`，传入会被上游拒绝。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ElevenLabsMusicV25GenerationRequest"
              },
              "examples": {
                "promptMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25StreamRequest"
                },
                "compositionPlanMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePlanRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "流式音频二进制数据。",
            "headers": {
              "X-Song-Id": {
                "description": "生成歌曲的唯一标识（网关将上游 `song-id` 响应头重命名为 `X-Song-Id`）。",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "audio/mpeg": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary"
                },
                "examples": {
                  "streamedMp3": {
                    "summary": "流式 MP3 字节流",
                    "value": "<streamed binary MP3 audio bytes>"
                  }
                }
              },
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary"
                },
                "examples": {
                  "streamedAudio": {
                    "summary": "流式音频字节流",
                    "value": "<streamed binary audio bytes>"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest"
          },
          "default": {
            "$ref": "#/components/responses/ElevenLabsMusicV25Error"
          }
        }
      }
    },
    "/v1/audio/music/detailed": {
      "post": {
        "tags": [
          "ElevenLabs Music V2.5"
        ],
        "operationId": "createElevenLabsMusicV25DetailedGeneration",
        "summary": "ElevenLabs Music V2.5 元数据音乐生成",
        "description": "生成音乐并返回 `multipart/mixed` 响应：一部分是 JSON 元数据（实际使用的 `composition_plan` 与 `song_metadata`），\n另一部分是音频二进制数据。响应由网关原样透传上游，客户端需按 boundary 自行解析。\n\n该端点是唯一支持 `with_timestamps`、`with_waveform_visual` 的端点。\n`respect_sections_durations` 在 `music-v2.5` 下不生效（段时长恒为强制值），传了也会被网关丢弃。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedRequest"
              },
              "examples": {
                "promptMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25DetailedRequest"
                },
                "compositionPlanMusic": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25DetailedPlanRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "包含 JSON 元数据与音频二进制数据的 multipart/mixed 响应。",
            "headers": {
              "X-Song-Id": {
                "description": "生成歌曲的唯一标识（网关将上游 `song-id` 响应头重命名为 `X-Song-Id`）。",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "multipart/mixed": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedMultipartResponse"
                },
                "examples": {
                  "detailedMultipart": {
                    "$ref": "#/components/examples/ElevenLabsMusicV25DetailedMultipartResponse"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest"
          },
          "default": {
            "$ref": "#/components/responses/ElevenLabsMusicV25Error"
          }
        }
      }
    },
    "/v1/audio/music/plan": {
      "post": {
        "tags": [
          "ElevenLabs Music V2.5"
        ],
        "operationId": "createElevenLabsMusicV25CompositionPlan",
        "summary": "ElevenLabs Music V2.5 编曲计划创建",
        "description": "根据文字描述生成结构化编曲计划（`chunks`），可直接作为 `/v1/audio/music/generate`\n的 `composition_plan` 使用。该端点不消耗额度。\n\n请求体按原样转发上游（仅把对外的 `model` 改写为上游 `model_id`），\n因此可选的 `source_composition_plan` 必须是 v2 的 `chunks` 结构，传 v1 的 `sections` 结构会被上游拒绝。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ElevenLabsMusicV25PlanRequest"
              },
              "examples": {
                "popSongPlan": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25PlanRequest"
                },
                "basedOnExistingPlan": {
                  "$ref": "#/components/examples/ElevenLabsMusicV25PlanFromSourceRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "生成的编曲计划。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan"
                },
                "examples": {
                  "popSongPlan": {
                    "$ref": "#/components/examples/ElevenLabsMusicV25PlanResponse"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest"
          },
          "default": {
            "$ref": "#/components/responses/ElevenLabsMusicV25Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "使用 API Key 进行 Bearer 认证，格式 `Authorization: Bearer <YOUR_API_KEY>`。\n"
      }
    },
    "responses": {
      "ElevenLabsMusicV25InvalidRequest": {
        "description": "请求参数无效，例如 `input` 与 `composition_plan` 同时传、`composition_plan` 模式下传了 `music_length_ms`、\n`music_length_ms` 越界、`seed` 与 `input` 同用、`chunks` 结构不合法等。\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorResponse"
            },
            "examples": {
              "invalidMusicLength": {
                "$ref": "#/components/examples/ElevenLabsMusicV25InvalidRequestError"
              }
            }
          }
        }
      },
      "ElevenLabsMusicV25Error": {
        "description": "上游服务错误。音乐生成端点会尽量提取上游 `{\"detail\":[{\"msg\":\"...\",\"loc\":[...]}]}` 中的可读原因并透传，\n客户端可据此定位问题（例如 `composition_plan` 与 `model_id` 不匹配）。\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorResponse"
            },
            "examples": {
              "error": {
                "$ref": "#/components/examples/ElevenLabsMusicV25InvalidRequestError"
              }
            }
          }
        }
      }
    },
    "schemas": {
      "ElevenLabsMusicV25Model": {
        "type": "string",
        "const": "music-v2.5",
        "description": "模型名称，固定为 `music-v2.5`。"
      },
      "ElevenLabsMusicV25Input": {
        "type": "string",
        "maxLength": 4100,
        "description": "音乐描述提示词，最多 4100 字符。与 `composition_plan` 互斥，不可同时使用。",
        "examples": [
          "A warm pop song with layered harmonies and a steady groove"
        ]
      },
      "ElevenLabsMusicV25Prompt": {
        "type": "string",
        "maxLength": 4100,
        "description": "编曲计划描述提示词，最多 4100 字符。仅 `/v1/audio/music/plan` 端点使用。",
        "examples": [
          "A mid-tempo pop song with a catchy chorus and warm synths"
        ]
      },
      "ElevenLabsMusicV25LengthMs": {
        "type": "integer",
        "minimum": 3000,
        "maximum": 600000,
        "description": "音乐时长（毫秒），范围 3000-600000。\n仅 `input` 模式下必填；`composition_plan` 模式禁止传该参数，否则直接返回 400。\n",
        "examples": [
          30000
        ]
      },
      "ElevenLabsMusicV25PlanLengthMs": {
        "type": "integer",
        "minimum": 3000,
        "maximum": 600000,
        "description": "编曲计划总时长（毫秒），范围 3000-600000。不填则由模型自动决定。仅 `/v1/audio/music/plan` 端点使用。",
        "examples": [
          45000
        ]
      },
      "ElevenLabsMusicV25Seed": {
        "type": "integer",
        "minimum": 0,
        "maximum": 2147483647,
        "description": "随机种子，范围 0-2147483647，用于复现同一结果。\n仅能与 `composition_plan` 配合使用；与 `input` 同时传会直接返回 400。\n",
        "examples": [
          12345
        ]
      },
      "ElevenLabsMusicV25OutputFormat": {
        "type": "string",
        "default": "auto",
        "description": "输出音频格式，格式为 `codec_sample_rate_bitrate`，默认 `auto`。\n`auto` 会由上游为 `music-v2.5` 选择 `mp3_48000_192`。\n网关会把该字段从请求体转换为上游的 query 参数，无需自行拼 URL。\n\n可选值：`auto`、`mp3_48000_128`、`mp3_48000_192`、`mp3_48000_240`、`mp3_48000_320`、\n`mp3_22050_32`、`mp3_24000_48`、`mp3_44100_32`、`mp3_44100_64`、`mp3_44100_96`、`mp3_44100_128`、\n`mp3_44100_192`、`pcm_8000`、`pcm_16000`、`pcm_22050`、`pcm_24000`、`pcm_32000`、`pcm_44100`、\n`pcm_48000`、`ulaw_8000`、`alaw_8000`、`opus_48000_32`、`opus_48000_64`、`opus_48000_96`、\n`opus_48000_128`、`opus_48000_192`。\n",
        "examples": [
          "mp3_48000_192"
        ]
      },
      "ElevenLabsMusicV25StoreForInpainting": {
        "type": "boolean",
        "default": false,
        "description": "是否把本次生成的歌曲保存下来供后续 inpainting 引用，默认 `false`。\n设为 `true` 后，响应头 `X-Song-Id` 返回的歌曲 ID 可用于下一次生成的\n`composition_plan.chunks[].conditioning_ref.song_id`。\n`/v1/audio/music/generate`、`/v1/audio/music/stream`、`/v1/audio/music/detailed` 均支持。\n"
      },
      "ElevenLabsMusicV25WithTimestamps": {
        "type": "boolean",
        "default": false,
        "description": "是否返回歌词时间戳，默认 `false`。仅 `/v1/audio/music/detailed` 端点支持，其他端点传入会被上游拒绝。"
      },
      "ElevenLabsMusicV25WithWaveformVisual": {
        "type": "boolean",
        "default": false,
        "description": "是否返回波形可视化数据，默认 `false`。仅 `/v1/audio/music/detailed` 端点支持，其他端点传入会被上游拒绝。"
      },
      "ElevenLabsMusicV25RespectSectionsDurations": {
        "type": "boolean",
        "description": "是否严格遵循片段时长。**该参数仅对 `music-v1` 生效**：`music-v2.5` 的片段时长恒为强制值，\n网关会在转发前丢弃该字段，传了也不会改变结果。保留该字段仅为兼容从 `music-v1` 迁移的客户端。\n"
      },
      "ElevenLabsMusicV25GenerationRequest": {
        "description": "音乐生成请求体。`input` 与 `composition_plan` 二选一，互斥：\n- `input` 模式：必填 `music_length_ms`，时长由该参数决定；\n- `composition_plan` 模式：禁止传 `music_length_ms`，时长由各 chunk 的 `duration_ms` 加总决定。\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ElevenLabsMusicV25PromptGenerationRequest"
          },
          {
            "$ref": "#/components/schemas/ElevenLabsMusicV25PlanGenerationRequest"
          }
        ]
      },
      "ElevenLabsMusicV25PromptGenerationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "music_length_ms"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Model"
          },
          "input": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Input"
          },
          "music_length_ms": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25LengthMs"
          },
          "force_instrumental": {
            "type": "boolean",
            "default": false,
            "description": "是否强制生成纯音乐，默认 `false`。仅与 `input` 配合使用，与 `composition_plan` 同传会直接返回 400。"
          },
          "store_for_inpainting": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting"
          },
          "output_format": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat"
          }
        }
      },
      "ElevenLabsMusicV25PlanGenerationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "composition_plan"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Model"
          },
          "composition_plan": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan"
          },
          "seed": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Seed"
          },
          "store_for_inpainting": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting"
          },
          "output_format": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat"
          }
        },
        "description": "composition_plan 模式。注意：禁止传 `music_length_ms`，否则直接返回 400。\n计费时长为 `composition_plan.chunks[].duration_ms` 的加总。\n"
      },
      "ElevenLabsMusicV25DetailedRequest": {
        "description": "详细模式音乐生成请求体。`input` 与 `composition_plan` 二选一，互斥：\n- `input` 模式：必填 `music_length_ms`；\n- `composition_plan` 模式：禁止传 `music_length_ms`。\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ElevenLabsMusicV25PromptDetailedRequest"
          },
          {
            "$ref": "#/components/schemas/ElevenLabsMusicV25PlanDetailedRequest"
          }
        ]
      },
      "ElevenLabsMusicV25PromptDetailedRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "music_length_ms"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Model"
          },
          "input": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Input"
          },
          "music_length_ms": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25LengthMs"
          },
          "force_instrumental": {
            "type": "boolean",
            "default": false,
            "description": "是否强制生成纯音乐，默认 `false`。仅与 `input` 配合使用。"
          },
          "with_timestamps": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25WithTimestamps"
          },
          "with_waveform_visual": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25WithWaveformVisual"
          },
          "store_for_inpainting": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting"
          },
          "output_format": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat"
          }
        }
      },
      "ElevenLabsMusicV25PlanDetailedRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "composition_plan"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Model"
          },
          "composition_plan": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan"
          },
          "seed": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Seed"
          },
          "with_timestamps": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25WithTimestamps"
          },
          "with_waveform_visual": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25WithWaveformVisual"
          },
          "respect_sections_durations": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25RespectSectionsDurations"
          },
          "store_for_inpainting": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting"
          },
          "output_format": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat"
          }
        },
        "description": "composition_plan 模式。注意：禁止传 `music_length_ms`，否则直接返回 400。\n"
      },
      "ElevenLabsMusicV25PlanRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Model"
          },
          "prompt": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25Prompt"
          },
          "music_length_ms": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25PlanLengthMs"
          },
          "source_composition_plan": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan"
          }
        }
      },
      "ElevenLabsMusicV25CompositionPlan": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "chunks"
        ],
        "description": "`music-v2.5` 的曲谱结构，由 `chunks` 组成（最多 30 个），各 chunk 的 `duration_ms` 加总为总时长（不超过 600000）。\n\n该结构是 `music-v2` / `music-v2.5` 专属；`music-v1` 使用的是 `sections` 结构，混用会被上游拒绝。\n",
        "properties": {
          "chunks": {
            "type": "array",
            "maxItems": 30,
            "description": "曲谱片段列表（必填，最多 30 个）。",
            "items": {
              "$ref": "#/components/schemas/ElevenLabsMusicV25Chunk"
            }
          }
        }
      },
      "ElevenLabsMusicV25Chunk": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text",
          "duration_ms",
          "positive_styles"
        ],
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 6132,
            "description": "该片段的歌词与指令文本（必填）。可在开头用方括号标注段落名（如 `[Verse 1]`，段落名 1-100 字符），\n在花括号中写内联指令（如 `{very loud}`）。最多 30 行，每行最多 200 字符；\n纯音乐片段可写 `[Instrumental Outro]` 这类段落说明。\n",
            "examples": [
              "[Verse]\nCity lights are fading\nWe keep moving through the night\n"
            ]
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 120000,
            "description": "该片段时长（毫秒，必填），范围 3000-120000。所有 chunk 加总不能超过 600000。",
            "examples": [
              15000
            ]
          },
          "positive_styles": {
            "type": "array",
            "maxItems": 50,
            "description": "该片段应具备的风格与音乐方向（必填，最多 50 个）。建议使用英文以获得最佳效果；\n第一个 chunk 的风格最重要，它决定整体基调与流派，建议前几个 chunk 至少给 6-7 个风格。\n",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "pop",
                "warm synths",
                "steady groove",
                "layered harmonies"
              ]
            ]
          },
          "negative_styles": {
            "type": "array",
            "maxItems": 50,
            "description": "该片段应避免的风格与音乐方向（可选，最多 50 个）。默认留空即可。",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "heavy metal",
                "harsh distortion"
              ]
            ]
          },
          "context_adherence": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "default": "high",
            "description": "模型对上下文片段的贴合程度，默认 `high`。\n`low` 允许更自由地发挥，`high` 则与前后片段保持更一致的风格。\n"
          },
          "conditioning_ref": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25AudioRefChunk"
          },
          "condition_strength": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "xhigh"
            ],
            "description": "对 `conditioning_ref` 参考音频的贴合强度（可选）。`low` 更具创造性、偏离参考；\n`xhigh` 则最大限度还原参考音频。第一个 chunk 的参考影响整首歌，若要全曲参考，请从第一个 chunk 开始设置。\n"
          }
        },
        "description": "曲谱片段。第一个 chunk 决定整首歌的基调与流派，后续 chunk 可用于推进、强调或转调。\n如果需要把某段已生成的音频作为参考（inpainting），在 `conditioning_ref` 中填入该歌曲的 `song_id`\n（来自上一次生成响应头 `X-Song-Id`，且生成时需 `store_for_inpainting: true`）。\n"
      },
      "ElevenLabsMusicV25AudioRefChunk": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "song_id",
          "range"
        ],
        "description": "引用一首已保存歌曲中的时间片段作为条件参考。",
        "properties": {
          "song_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "被引用歌曲的 ID，取自生成该歌曲时响应头 `X-Song-Id`。",
            "examples": [
              "song_abc123"
            ]
          },
          "range": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25TimeRange"
          }
        }
      },
      "ElevenLabsMusicV25TimeRange": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "start_ms",
          "end_ms"
        ],
        "description": "参考音频的时间范围（毫秒）。",
        "properties": {
          "start_ms": {
            "type": "integer",
            "description": "起始时间（毫秒）。",
            "examples": [
              0
            ]
          },
          "end_ms": {
            "type": "integer",
            "description": "结束时间（毫秒）。",
            "examples": [
              10000
            ]
          }
        }
      },
      "ElevenLabsMusicV25DetailedMetadata": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "composition_plan",
          "song_metadata"
        ],
        "properties": {
          "composition_plan": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan"
          },
          "song_metadata": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25SongMetadata"
          }
        }
      },
      "ElevenLabsMusicV25SongMetadata": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string",
            "description": "歌曲标题。",
            "examples": [
              "City Lights"
            ]
          },
          "description": {
            "type": "string",
            "description": "歌曲描述。",
            "examples": [
              "A warm mid-tempo pop song with layered harmonies"
            ]
          },
          "genres": {
            "type": "array",
            "description": "音乐流派。",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "pop"
              ]
            ]
          },
          "languages": {
            "type": "array",
            "description": "歌词使用的语言。",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "en"
              ]
            ]
          },
          "is_explicit": {
            "type": "boolean",
            "description": "歌曲是否包含成人内容。"
          }
        }
      },
      "ElevenLabsMusicV25AudioBinary": {
        "type": "string",
        "format": "binary",
        "description": "生成的音频二进制流，格式由 `output_format` 决定，`auto` 时对 `music-v2.5` 为 `mp3_48000_192`。"
      },
      "ElevenLabsMusicV25DetailedMultipartResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "metadata",
          "audio"
        ],
        "properties": {
          "metadata": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedMetadata"
          },
          "audio": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary"
          }
        },
        "description": "`/v1/audio/music/detailed` 端点的 multipart/mixed 响应，包含两部分：JSON 元数据（实际使用的曲谱 + 歌曲元信息）\n和音频二进制数据。响应原样透传上游，与 ElevenLabs 官方 API 行为一致；开启 `with_timestamps` /\n`with_waveform_visual` 时，对应的附加字段也会出现在元数据部分中。\n"
      },
      "ElevenLabsMusicV25ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorObject"
          }
        }
      },
      "ElevenLabsMusicV25ErrorObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。上游校验失败时会带上出错位置，如 `composition_plan.chunks.0.duration_ms: Input should be ...`。",
            "examples": [
              "music_length_ms must be between 3000 and 600000"
            ]
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "机器可读的错误码。",
            "examples": [
              "param_error"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "与错误相关的请求参数。",
            "examples": [
              "music_length_ms"
            ]
          }
        }
      }
    },
    "examples": {
      "ElevenLabsMusicV25GeneratePromptRequest": {
        "summary": "根据文本提示词生成音乐（input 模式）",
        "value": {
          "model": "music-v2.5",
          "input": "A warm pop song with layered harmonies and a steady groove",
          "music_length_ms": 30000,
          "output_format": "mp3_48000_192",
          "store_for_inpainting": true
        }
      },
      "ElevenLabsMusicV25GeneratePlanRequest": {
        "summary": "根据 composition_plan 生成音乐（chunks 模式）",
        "description": "composition_plan 模式示例。注意：不能传 `music_length_ms`，总时长由各 chunk 的 `duration_ms` 加总决定（示例为 35 秒）。\n",
        "value": {
          "model": "music-v2.5",
          "composition_plan": {
            "chunks": [
              {
                "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "pop",
                  "warm synths",
                  "steady groove",
                  "layered harmonies"
                ]
              },
              {
                "text": "[Chorus]\nHold on to the feeling\n{very loud}Let it rise and come alive\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "uplifting",
                  "bigger drums",
                  "wide vocals"
                ]
              },
              {
                "text": "[Instrumental Outro]",
                "duration_ms": 5000,
                "positive_styles": [
                  "gentle ending",
                  "soft pads"
                ]
              }
            ]
          },
          "seed": 12345,
          "output_format": "mp3_48000_192"
        }
      },
      "ElevenLabsMusicV25StreamRequest": {
        "summary": "流式生成音乐（input 模式）",
        "value": {
          "model": "music-v2.5",
          "input": "A calm acoustic guitar piece with soft rain ambience",
          "music_length_ms": 30000,
          "output_format": "mp3_48000_192"
        }
      },
      "ElevenLabsMusicV25DetailedRequest": {
        "summary": "input 模式生成带元数据音乐",
        "value": {
          "model": "music-v2.5",
          "input": "An upbeat pop tune with a catchy chorus",
          "music_length_ms": 30000,
          "with_timestamps": true,
          "with_waveform_visual": true
        }
      },
      "ElevenLabsMusicV25DetailedPlanRequest": {
        "summary": "composition_plan 模式生成带元数据音乐",
        "description": "composition_plan 模式示例，禁止传 `music_length_ms`。",
        "value": {
          "model": "music-v2.5",
          "composition_plan": {
            "chunks": [
              {
                "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "pop",
                  "warm synths",
                  "steady groove"
                ]
              },
              {
                "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "uplifting",
                  "bigger drums",
                  "wide vocals"
                ]
              }
            ]
          },
          "seed": 12345,
          "with_timestamps": false,
          "with_waveform_visual": true
        }
      },
      "ElevenLabsMusicV25DetailedMultipartResponse": {
        "summary": "multipart 元数据和音频响应",
        "value": {
          "metadata": {
            "composition_plan": {
              "chunks": [
                {
                  "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n",
                  "duration_ms": 15000,
                  "positive_styles": [
                    "pop",
                    "warm synths",
                    "steady groove"
                  ]
                },
                {
                  "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n",
                  "duration_ms": 15000,
                  "positive_styles": [
                    "uplifting",
                    "bigger drums",
                    "wide vocals"
                  ]
                }
              ]
            },
            "song_metadata": {
              "title": "City Lights",
              "description": "A warm mid-tempo pop song with layered harmonies",
              "genres": [
                "pop"
              ],
              "languages": [
                "en"
              ],
              "is_explicit": false
            }
          },
          "audio": "<binary MP3 audio bytes>"
        }
      },
      "ElevenLabsMusicV25PlanRequest": {
        "summary": "根据文字描述创建编曲计划",
        "value": {
          "model": "music-v2.5",
          "prompt": "A mid-tempo pop song with a catchy chorus and warm synths",
          "music_length_ms": 45000
        }
      },
      "ElevenLabsMusicV25PlanFromSourceRequest": {
        "summary": "基于已有编曲计划创建新编曲计划",
        "description": "`source_composition_plan` 必须使用 v2 的 `chunks` 结构（v1 的 `sections` 结构会被上游拒绝）。\n",
        "value": {
          "model": "music-v2.5",
          "prompt": "A longer version with an extended outro and softer ending",
          "music_length_ms": 60000,
          "source_composition_plan": {
            "chunks": [
              {
                "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "pop",
                  "warm synths",
                  "steady groove"
                ]
              },
              {
                "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n",
                "duration_ms": 15000,
                "positive_styles": [
                  "uplifting",
                  "bigger drums",
                  "wide vocals"
                ]
              }
            ]
          }
        }
      },
      "ElevenLabsMusicV25PlanResponse": {
        "summary": "生成的编曲计划",
        "value": {
          "chunks": [
            {
              "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n",
              "duration_ms": 15000,
              "positive_styles": [
                "pop",
                "warm synths",
                "steady groove",
                "layered harmonies"
              ]
            },
            {
              "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n",
              "duration_ms": 15000,
              "positive_styles": [
                "uplifting",
                "bigger drums",
                "wide vocals"
              ]
            },
            {
              "text": "[Instrumental Outro]",
              "duration_ms": 5000,
              "positive_styles": [
                "gentle ending",
                "soft pads"
              ]
            }
          ]
        }
      },
      "ElevenLabsMusicV25InvalidRequestError": {
        "summary": "无效参数示例",
        "value": {
          "error": {
            "message": "music_length_ms must be between 3000 and 600000",
            "type": "invalid_request_error",
            "code": "param_error",
            "param": "music_length_ms"
          }
        }
      }
    }
  }
}
```