> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # ElevenLabs Music > ElevenLabs Music API 可根据文本描述或结构化编曲方案生成音乐。文本请求可设置 3 到 600 秒的时长，或要求输出纯伴奏；编曲方案中每个段落为 3 到 120 秒。 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)接口获取结果。 `elevenlabs-music` 根据文本或结构化编曲方案生成音乐音频。结果以任务 `files` 返回，与图像、视频、3D 和音频任务的标准响应结构一致。 ## 模型 * **elevenlabs-music** - ElevenLabs Music 生成，支持文本和编曲方案控制 ## 输入模式 只能提供一种创作控制方式： * 使用 **text** 提供单段文本描述。 * 使用 **composition\_plan** 进行段落级编排控制。 * 不要在同一请求中同时传入 `text` 和 `composition_plan`。 ## 可选参数 所有支持的 `input` 字段。根据输入模式，`text` 或 `composition_plan` 二者之一为必填： * **text**：描述要生成的音乐的文本。未提供 `composition_plan` 时必填。长度：`1-4100` 个字符。 * **composition\_plan**：结构化编曲方案。未提供 `text` 时必填。 * **positive\_global\_styles**：要包含的全局风格，字符串数组。 * **negative\_global\_styles**：要避免的全局风格，字符串数组。 * **sections**：非空的音乐段落数组。 * **section\_name**：段落名称，`1-100` 个字符。 * **positive\_local\_styles**：该段落要包含的风格，字符串数组。 * **negative\_local\_styles**：该段落要避免的风格，字符串数组。 * **duration**：段落时长（秒），`3-120`。PoYo 对外公开的这个字段以秒为单位。 * **lines**：歌词行。每行不超过 `200` 个字符。 * **duration**：可选的歌曲时长（秒）。提供时必须为 `3-600`。仅可与 `text` 一起使用。 * **is\_instrumental**：为 `true` 时请求仅输出伴奏。仅可与 `text` 一起使用。 * **respect\_sections\_durations**：控制对段落时长的遵循严格程度。仅可与 `composition_plan` 一起使用。 * **output\_format**：输出格式。默认为 `mp3_44100_128`。 ## 输出格式 支持的 `output_format` 值： `mp3_22050_32`、`mp3_44100_32`、`mp3_44100_64`、`mp3_44100_96`、`mp3_44100_128`、`mp3_44100_192`、`pcm_8000`、`pcm_16000`、`pcm_22050`、`pcm_24000`、`pcm_44100`、`pcm_48000`、`ulaw_8000`、`alaw_8000`、`opus_48000_32`、`opus_48000_64`、`opus_48000_96`、`opus_48000_128`、`opus_48000_192`。 ## 注意事项 * `text` 和 `composition_plan` 只能提供其中一个。 * `duration` 和 `is_instrumental` 只能与 `text` 一起使用。 * `respect_sections_durations` 只能与 `composition_plan` 一起使用。 * 通过标准任务状态 API 查询状态，而不是音乐详情接口。 * 成功响应返回 `files`，其中生成的音乐使用 `file_type: audio`。 ## OpenAPI ````yaml zh/api-manual/music-series/elevenlabs-music.json POST /api/generate/submit openapi: 3.0.0 info: title: PoYo AI - ElevenLabs Music API description: >- ElevenLabs Music API 根据文本描述或结构化作曲计划生成音乐。文本请求可设置 3 到 600 秒的时长，或请求纯音乐输出；作曲计划的每个段落为 3 到 120 秒。 version: 1.0.0 servers: - url: https://api.poyo.ai description: 生产环境 security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - ElevenLabs Music summary: 提交 ElevenLabs Music 任务 description: 根据文本或结构化作曲计划生成音乐。 operationId: submitElevenLabsMusicTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: text-instrumental-score: summary: 文本生成纯音乐配乐 value: model: elevenlabs-music callback_url: https://your-domain.com/callback input: text: >- A polished instrumental cinematic game menu loop for a neon sci-fi strategy game, elegant synth arpeggios, warm analog pads, restrained percussion, gradual heroic lift, no vocals, seamless background score. duration: 45 is_instrumental: true output_format: opus_48000_128 text-vocal-multilingual-song: summary: 文本生成多语言人声歌曲 value: model: elevenlabs-music callback_url: https://your-domain.com/callback input: text: >- A studio-grade upbeat pop song with a clear vocal hook for a travel campaign, bright drums, warm bass, polished lead vocal, and a short bilingual English and Spanish refrain: 'We chase the sunrise' and 'Vamos hacia la luz'. duration: 30 output_format: mp3_44100_128 composition-plan-structured-song: summary: 作曲计划生成结构化歌曲 value: model: elevenlabs-music callback_url: https://your-domain.com/callback input: composition_plan: positive_global_styles: - studio-grade pop production - clear multilingual vocal hook - cinematic electronic texture negative_global_styles: - muddy mix - harsh distortion - off-key vocals sections: - section_name: Intro positive_local_styles: - soft piano motif - wide atmospheric pads negative_local_styles: - heavy drums duration: 20 lines: - City lights awaken softly - section_name: Verse positive_local_styles: - gentle vocal lead - subtle electronic pulse negative_local_styles: - crowded arrangement duration: 25 lines: - We cross the night with open eyes - Cada paso brilla bajo el cielo - section_name: Chorus positive_local_styles: - anthemic hook - wide drums - bright layered vocals negative_local_styles: - thin bass duration: 30 lines: - Raise the signal, let it shine - We are the echo in the skyline respect_sections_durations: true output_format: mp3_44100_128 short-brand-sonic-logo-format: summary: 短品牌声音标识格式 value: model: elevenlabs-music callback_url: https://your-domain.com/callback input: text: >- A concise instrumental sonic logo for a premium productivity app, five-note memorable motif, clean mallet attack, soft synth shimmer, confident but friendly ending, no vocals. duration: 10 is_instrumental: true output_format: ulaw_8000 responses: '200': description: 任务提交成功 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: 请求参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 未授权 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object required: - model - input properties: model: type: string description: 模型标识符。 enum: - elevenlabs-music example: elevenlabs-music callback_url: type: string format: uri description: 接收结果通知的 Webhook 回调 URL example: https://your-domain.com/callback input: $ref: '#/components/schemas/Input' description: 输入参数。text 和 composition_plan 必须且只能提供其一。 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task_xxxxxxxxxxxxxxxx status: type: string enum: - not_started - running - finished - failed example: not_started description: >- 任务状态。提交后立即返回时始终为 `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或 `callback_url` 获取。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` created_time: type: string format: date-time example: '2026-06-26T10:30:00' ErrorResponse: type: object properties: code: type: integer enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 error: type: object properties: message: type: string type: type: string Input: type: object additionalProperties: false properties: text: type: string maxLength: 4100 description: 描述要生成的音乐的文本。未提供 composition_plan 时必填。不要同时发送 text 和 composition_plan。 example: >- A polished instrumental cinematic game menu loop for a neon sci-fi strategy game, elegant synth arpeggios, warm analog pads, restrained percussion, gradual heroic lift, no vocals, seamless background score. composition_plan: $ref: '#/components/schemas/CompositionPlan' description: 结构化作曲计划。未提供 text 时必填。不要同时发送 text 和 composition_plan。 duration: type: number minimum: 3 maximum: 600 description: 可选的歌曲时长（秒）。仅与 text 一起使用时有效。 example: 45 is_instrumental: type: boolean description: 为 true 时，请求纯音乐输出。仅与 text 一起使用时有效。 default: false example: true respect_sections_durations: type: boolean description: 控制段落时长的执行严格程度。仅与 composition_plan 一起使用时有效。 default: true example: true output_format: $ref: '#/components/schemas/OutputFormat' CompositionPlan: type: object required: - positive_global_styles - negative_global_styles - sections additionalProperties: false properties: positive_global_styles: type: array items: type: string description: 要包含的全局风格。 example: - studio-grade pop production - clear multilingual vocal hook - cinematic electronic texture negative_global_styles: type: array items: type: string description: 要避免的全局风格。 example: - muddy mix - harsh distortion - off-key vocals sections: type: array minItems: 1 items: $ref: '#/components/schemas/CompositionSection' OutputFormat: type: string description: 输出音频格式。格式为 codec_sample_rate_bitrate。 enum: - mp3_22050_32 - mp3_44100_32 - mp3_44100_64 - mp3_44100_96 - mp3_44100_128 - mp3_44100_192 - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 - alaw_8000 - opus_48000_32 - opus_48000_64 - opus_48000_96 - opus_48000_128 - opus_48000_192 default: mp3_44100_128 example: mp3_44100_128 CompositionSection: type: object required: - section_name - positive_local_styles - negative_local_styles - duration - lines additionalProperties: false properties: section_name: type: string minLength: 1 maxLength: 100 description: 段落名称。 example: Verse positive_local_styles: type: array items: type: string description: 该段落要包含的风格。 example: - gentle vocal lead - subtle electronic pulse negative_local_styles: type: array items: type: string description: 该段落要避免的风格。 example: - crowded arrangement duration: type: number minimum: 3 maximum: 120 description: 段落时长（秒）。 example: 25 lines: type: array items: type: string maxLength: 200 description: 该段落的歌词行。 example: - We cross the night with open eyes - Cada paso brilla bajo el cielo securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.