> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mountsea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 生成音乐
> 从文本提示或作曲计划创建音乐
使用 ElevenLabs 音乐模型（`music_v1` / `music_v2`）生成音乐。对应官方 `POST /v1/music/detailed` — 结果包含歌词时间戳、作曲计划等元数据。
支持两种互斥的输入模式：
* **提示模式**：提供简单文本 `prompt` — 快速便捷
* **作曲计划模式**：提供结构化的 `compositionPlan`，按段落精细控制风格、时长和歌词
这是一个异步任务。响应中包含 `taskId` — 使用[获取任务状态](/zh/api-reference/eleven/task)轮询生成的音频。
## 模式说明
### 简单提示
设置 `prompt` 描述所需音乐。可选设置 `forceInstrumental: true` 生成纯器乐。此模式建议填写 `musicLengthMs`。
### 作曲计划
设置 `compositionPlan`，包含 `positive_global_styles`、`negative_global_styles` 和 `sections` 数组。每个段落可有独立的 `section_name`、`positive_local_styles`、`negative_local_styles`、`duration_ms` 和 `lines`（歌词）。曲目长度由段落时长决定。
先使用[创建作曲计划](/zh/api-reference/eleven/plan)从文本提示生成计划（免费，不消耗积分），查看后再传入此处。
## 常用选项
| 参数 | 说明 |
| -------------------------- | ----------------------------- |
| `model` | 必填。使用 `music_v1` 或 `music_v2` |
| `respectSectionsDurations` | 仅作曲计划模式；默认 `true` |
| `storeForInpainting` | 企业 Inpainting；保存结果供后续编辑 |
| `signWithC2pa` | 嵌入 C2PA AI 来源证明（仅 MP3） |
## OpenAPI
````yaml POST /eleven/music
openapi: 3.0.0
info:
title: Eleven AI
description: API documentation for Eleven AI
version: 1.0.0
contact: {}
servers:
- url: https://api.mountsea.ai
description: API Gateway
security: []
tags:
- name: eleven
description: ''
paths:
/eleven/music:
post:
tags:
- eleven
summary: 音乐生成
description: |-
对应 POST /v1/music/detailed，返回包含歌词时间戳、作曲计划等元数据的详细结果。
支持两种互斥的输入方式：prompt（简单描述）或 compositionPlan（结构化作曲计划）。
返回 taskId，使用 GET /eleven/tasks 轮询获取结果
operationId: ApiPublicController_composeMusic
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ComposeMusicDto'
responses:
'200':
description: 任务创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/TaskIdDto'
security:
- bearerAuth: []
components:
schemas:
ComposeMusicDto:
type: object
properties:
prompt:
type: string
description: 简单文字提示（与 compositionPlan 互斥）
example: A melancholic indie folk song with acoustic guitar and soft vocals
compositionPlan:
description: 详细作曲计划（与 prompt 互斥，通过 /eleven/plan 生成）
allOf:
- $ref: '#/components/schemas/CompositionPlanDto'
musicLengthMs:
type: number
minimum: 3000
maximum: 600000
description: 歌曲长度（毫秒），范围 3000-600000ms。prompt 模式建议填写；compositionPlan 模式由段落时长决定
example: 180000
model:
enum:
- music_v1
- music_v2
- eleven_multilingual_v2
- eleven_turbo_v2_5
- eleven_flash_v2_5
- eleven_v3
type: string
description: 模型 ID
example: music_v1
seed:
type: number
description: 随机种子
example: 877369
forceInstrumental:
type: boolean
description: 强制纯器乐，仅 prompt 模式
default: false
respectSectionsDurations:
type: boolean
description: 是否严格遵守段落时长，仅 compositionPlan 模式
default: true
outputFormat:
enum:
- mp3_22050_32
- mp3_24000_48
- mp3_44100_32
- mp3_44100_64
- mp3_44100_96
- mp3_44100_128
- mp3_44100_192
- pcm_8000
- pcm_16000
- pcm_22050
- pcm_24000
- pcm_32000
- pcm_44100
- pcm_48000
- ulaw_8000
- alaw_8000
- opus_48000_32
- opus_48000_64
- opus_48000_96
- opus_48000_128
- opus_48000_192
type: string
description: >-
输出格式，格式为 codec_sampleRate_bitrate。MP3 192kbps 需要 Creator 及以上，PCM
44.1kHz 需要 Pro 及以上
default: mp3_44100_128
storeForInpainting:
type: boolean
description: 是否保存生成结果用于后续 Inpainting 编辑。仅限具备 Inpainting 权限的企业客户使用
default: false
signWithC2pa:
type: boolean
description: 是否使用 C2PA 签名标记 AI 生成内容。仅适用于 MP3 输出格式，会在文件中嵌入加密的 AI 生成来源证明
default: false
required:
- model
TaskIdDto:
type: object
properties:
taskId:
type: string
description: 任务 ID，用于后续查询结果
required:
- taskId
CompositionPlanDto:
type: object
properties:
positive_global_styles:
description: 全局正面风格
example:
- epic orchestral
- cinematic
type: array
items:
type: string
negative_global_styles:
description: 全局负面风格（排除的风格）
example:
- lo-fi
- acoustic
type: array
items:
type: string
sections:
description: 歌曲段落列表
type: array
items:
$ref: '#/components/schemas/SongSectionDto'
SongSectionDto:
type: object
properties:
section_name:
type: string
maxLength: 100
description: 段落名称，1-100 字符 (如 Intro, Verse, Chorus)
example: Verse
positive_local_styles:
description: 正面风格描述——该段落期望呈现的音乐风格/乐器/氛围，建议使用英语
example:
- soft piano
- building tension
type: array
items:
type: string
negative_local_styles:
description: 负面风格描述——该段落需排除的音乐风格，建议使用英语
example:
- heavy drums
type: array
items:
type: string
duration_ms:
type: number
minimum: 3000
maximum: 120000
description: 段落时长（毫秒），范围 3000-120000
example: 15000
lines:
maxItems: 30
description: 歌词行（仅限可演唱内容，每行最多 200 字符，最多 30 行）
example:
- First line of lyrics
- Second line
type: array
items:
type: string
source_from:
description: Inpainting 段落来源——从已有歌曲中提取片段作为该段落素材。仅限具备 Inpainting 权限的企业客户使用
allOf:
- $ref: '#/components/schemas/SectionSourceDto'
required:
- section_name
SectionSourceDto:
type: object
properties:
song_id:
type: string
description: 源歌曲 ID（从 compose 响应 header 或 upload 返回值获取）
example: abc123-song-id
range:
description: 要提取的源歌曲时间区间
allOf:
- $ref: '#/components/schemas/TimeRangeDto'
negative_ranges:
description: 在 range 内需要排除的子区间列表
type: array
items:
$ref: '#/components/schemas/TimeRangeDto'
required:
- song_id
- range
TimeRangeDto:
type: object
properties:
start_ms:
type: number
minimum: 0
description: 起始位置（毫秒）
example: 0
end_ms:
type: number
minimum: 0
description: 结束位置（毫秒）
example: 30000
required:
- start_ms
- end_ms
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````