> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ElevenLabs Music
> 根据文字简述或逐段编排方案创作歌曲或纯音乐，可控制音乐风格、歌词和编排。
> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。
根据文字简述或逐段编排方案创作歌曲或纯音乐，可控制音乐风格、歌词和编排。
## 模型
* **elevenlabs/music** - 根据文本或结构化编排方案生成音乐。
## 功能
* 根据文本或结构化编排方案生成音乐。
* 规划音乐段落，每段可设置自己的风格、歌词和时长。
* 使用 `output_format` 选择输出编码。
## 时长选项
* **文本输入** - 可选的 `duration` 为 **3 到 600 秒**之间的数值，仅与 `text` 一起使用。
* **编排方案** - 每个段落为 **3-120 秒**。
## 输出选项
### 输出格式
* `output_format`：可选。字符串。默认：`mp3_44100_128`。
> [accordion] 支持的输出格式
>
> * `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`
## 高级参数
在请求根级设置 `model` 和可选的 `callback_url`。所有工作流程参数（包括输出选项）都放在 `input` 中。
选择一种创作方式：文字简述或结构化编排方案。
* `text` 和 `composition_plan` 必须且只能提供一个。
* `duration` 和 `is_instrumental` 仅适用于 `text`。`respect_sections_durations` 仅与 `composition_plan` 一起使用。
### 文本
* `text`：使用文本方式时必填。描述要生成的音乐。长度：**1-4,100 个字符**。
* 在音乐描述中写明期望的流派、情绪和乐器。
### 编排方案
* `composition_plan`：使用编排方案方式时必填。描述全局风格和按顺序排列的音乐段落。传入包含以下字段的对象。
* `composition_plan.positive_global_styles`：必填。数组，每项必须是字符串。
* `composition_plan.negative_global_styles`：必填。数组，每项必须是字符串。
* `composition_plan.sections`：必填。至少 1 项，每项为一个对象。
* `composition_plan.sections[].section_name`：必填。长度：**1-100 个字符**。
* `composition_plan.sections[].positive_local_styles`：必填。数组，每项必须是字符串。
* `composition_plan.sections[].negative_local_styles`：必填。数组，每项必须是字符串。
* `composition_plan.sections[].duration`：必填。时长（秒）。数值 `3` 到 `120`。
* `composition_plan.sections[].lines`：必填。数组，每项必须是字符串，每个字符串最多 **200 个字符**。
* 段落时长以秒为单位。
### 纯音乐模式
* `is_instrumental`：可选。设为 `true` 生成纯音乐。文本方式下默认：`false`。
* 仅与 `text` 一起使用。
### 段落时长
* `respect_sections_durations`：可选。仅与编排方案一起使用，控制是否严格遵循段落时长。使用 `true` 或 `false`。编排方案方式下默认：`true`。
## 输出文件
* 读取返回的 `files` 数组中的每一项。
* 生成的音频 `file_type` 为 `"audio"`。
* 时间戳和对齐文件可能使用 `file_type: "other"`。如有可选的文件元数据，请一并保留。
## 示例
每个示例都包含请求、对应的已完成任务响应和生成的音频。将请求提交到 `POST https://api.vidgo.ai/api/generate/submit`，然后使用提交返回的任务 ID 查询 `GET https://api.vidgo.ai/api/generate/status/{task_id}`。
> [accordion] 屋顶上的春天
>
> ```json Request theme={null}
> {
> "model": "elevenlabs/music",
> "input": {
> "composition_plan": {
> "positive_global_styles": [
> "indie folk with subtle organic electronica",
> "96 BPM, 4/4",
> "warm clear female lead vocal",
> "acoustic guitar, rounded bass, delicate electronic percussion",
> "hopeful intimate song about planting a rooftop garden",
> "clean spacious studio mix, clear Mandarin and English diction"
> ],
> "negative_global_styles": [
> "harsh distortion",
> "crowded arrangement",
> "spoken narration",
> "abrupt cut off"
> ],
> "sections": [
> {
> "section_name": "Acoustic introduction",
> "duration": 8,
> "positive_local_styles": [
> "instrumental only",
> "fingerpicked acoustic guitar introduces a memorable gentle motif",
> "soft airy pad, no drums"
> ],
> "negative_local_styles": [],
> "lines": []
> },
> {
> "section_name": "Mandarin verse",
> "duration": 16,
> "positive_local_styles": [
> "sing the supplied Mandarin lyrics clearly",
> "intimate gentle lead vocal",
> "fingerpicked guitar and soft bass, restrained percussion"
> ],
> "negative_local_styles": [],
> "lines": [
> "把春天种在屋顶上",
> "等风翻过旧砖墙"
> ]
> },
> {
> "section_name": "English chorus",
> "duration": 16,
> "positive_local_styles": [
> "sing the supplied English lyrics clearly",
> "open uplifting melody",
> "full warm drums and bass enter",
> "layered backing vocal harmonies, retain the acoustic motif"
> ],
> "negative_local_styles": [],
> "lines": [
> "Little seeds above the street",
> "Find the sunlight, find the beat"
> ]
> },
> {
> "section_name": "Instrumental resolution",
> "duration": 8,
> "positive_local_styles": [
> "instrumental only, no vocals",
> "return to fingerpicked guitar motif",
> "drums fall away, warm sustained final chord with natural decay"
> ],
> "negative_local_styles": [],
> "lines": []
> }
> ]
> },
> "respect_sections_durations": true,
> "output_format": "mp3_44100_128"
> }
> }
> ```
>
> ```json Completed task response theme={null}
> {
> "code": 200,
> "data": {
> "task_id": "W6KDNIQQOUAE1K8V",
> "status": "finished",
> "created_time": "2026-09-27T10:48:12",
> "progress": 100,
> "error_message": null,
> "files": [
> {
> "file_type": "audio",
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/01/output.mp3"
> }
> ]
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/01/output.mp3)
> [accordion] 钟表匠的线索
>
> ```json Request theme={null}
> {
> "model": "elevenlabs/music",
> "input": {
> "text": "Create a 30-second instrumental jazz cue for a puzzle scene in a clockmaker's workshop. 104 BPM, lightly swinging 4/4, playful curiosity with a hint of mystery. Use plucked upright bass, brushed drums, muted trumpet and vibraphone, each clearly separated in a warm intimate acoustic mix. Begin with a distinctive four-note vibraphone motif over bass; let muted trumpet answer and develop that motif in the middle, while brush accents subtly increase the momentum. Resolve with a short, clean ensemble cadence and allow the last note to decay naturally. No vocals, choir, spoken words, ticking sound effects or abrupt cutoff.",
> "duration": 30,
> "is_instrumental": true,
> "output_format": "mp3_44100_128"
> }
> }
> ```
>
> ```json Completed task response theme={null}
> {
> "code": 200,
> "data": {
> "task_id": "EBXJLNFGE8WD7114",
> "status": "finished",
> "created_time": "2026-09-27T10:48:48",
> "progress": 100,
> "error_message": null,
> "files": [
> {
> "file_type": "audio",
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/02/output.mp3"
> }
> ]
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/02/output.mp3)
> [accordion] 穿过海带森林的光
>
> ```json Request theme={null}
> {
> "model": "elevenlabs/music",
> "input": {
> "text": "Compose a 40-second instrumental score for a nature documentary gliding through a sunlit underwater kelp forest. 72 BPM, gently flowing 4/4. Felt piano, delicate harp harmonics, soft sustained strings and a subtle low ambient texture; luminous, patient, full of quiet wonder. Start sparsely with isolated felt-piano notes and wide space. Gradually introduce harp and strings into an expansive rising harmony through the middle third, suggesting shafts of light moving through long fronds. Gently thin the arrangement and finish on a peaceful resolved chord with natural reverb decay. Detailed soft dynamics, wide stereo depth, no heavy percussion, no vocals or choir, no narration, no water sound effects, no abrupt cutoff.",
> "duration": 40,
> "is_instrumental": true,
> "output_format": "mp3_44100_128"
> }
> }
> ```
>
> ```json Completed task response theme={null}
> {
> "code": 200,
> "data": {
> "task_id": "VAK9IGFH57XPEUGP",
> "status": "finished",
> "created_time": "2026-09-27T10:49:30",
> "progress": 100,
> "error_message": null,
> "files": [
> {
> "file_type": "audio",
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/03/output.mp3"
> }
> ]
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/03/output.mp3)
## OpenAPI
````yaml zh/api-manual/music-series/elevenlabs-music.json POST /api/generate/submit
openapi: 3.0.0
info:
title: Vidgo API - ElevenLabs Music
description: 根据文字简述或逐段编排方案创作歌曲或纯音乐，可控制音乐风格、歌词和编排。
version: 1.0.0
servers:
- url: https://api.vidgo.ai
security:
- BearerAuth: []
paths:
/api/generate/submit:
post:
tags:
- Audio Series
summary: ElevenLabs Music
description: >-
选择一种创作方式作曲：text 或 composition_plan。使用 text 时设置 duration 和
is_instrumental；使用 composition_plan 时设置
respect_sections_durations。各段时长以秒为单位。从 files 中 file_type=audio
的条目读取生成的音频，并保留随附的文件元数据。
operationId: submit_elevenlabs_music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
additionalProperties: true
properties:
model:
type: string
example: elevenlabs/music
enum:
- elevenlabs/music
input:
type: object
additionalProperties: false
properties:
text:
type: string
maxLength: 4100
minLength: 1
description: 音乐描述，1-4100 个字符。使用 text 方式时必填。
composition_plan:
type: object
required:
- positive_global_styles
- negative_global_styles
- sections
additionalProperties: false
properties:
positive_global_styles:
type: array
items:
type: string
description: 全局正向风格。
description: 整首曲目中要包含的音乐风格。未指定全局风格时使用空数组。
negative_global_styles:
type: array
items:
type: string
description: 全局负向风格。
description: 整首曲目中要排除的音乐风格，可以为空数组。
sections:
type: array
minItems: 1
items:
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: 该音乐段落的名称，例如 Intro、Verse 或 Chorus；1-100 个字符。
positive_local_styles:
type: array
items:
type: string
description: 局部正向风格。
description: 该段落中要包含的音乐风格和乐器，可以为空数组。
negative_local_styles:
type: array
items:
type: string
description: 局部负向风格。
description: 该段落中要排除的音乐风格，可以为空数组。
duration:
type: number
minimum: 3
maximum: 120
description: 该段落的时长（秒），3 到 120，可带小数。
lines:
type: array
items:
type: string
maxLength: 200
description: 一行歌词，最多 200 个字符。
description: 该段落的歌词，每行一个字符串，每行最多 200 个字符。纯音乐段落使用空数组。
description: 段落。
description: 至少一个音乐段落，按其在曲目中的位置排序。
description: 结构化的全局风格和音乐段落。使用 composition_plan 方式时必填。
duration:
type: number
minimum: 3
maximum: 600
description: 歌曲时长（秒），3 到 600，可带小数。适用于 text 输入。
is_instrumental:
type: boolean
description: 设为 true 生成纯音乐。适用于 text 输入；该方式下默认 false。
default: false
respect_sections_durations:
type: boolean
description: 遵循指定的段落时长。适用于 composition_plan；该方式下默认 true。
default: true
output_format:
type: string
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
description: 音频编码、采样率和比特率。默认：mp3_44100_128。
description: >-
`text` 和 `composition_plan` 必须且只能提供一个。使用 `text` 时省略
`respect_sections_durations`；使用 `composition_plan` 时省略
`duration` 和 `is_instrumental`。
callback_url:
type: string
nullable: true
description: 可选的公开 HTTP(S) 接口，用于接收任务完成通知，建议使用 HTTPS。省略、设为 null 或空字符串即不回调。
description: 在根级设置 model 和可选的 callback_url，创作方式及其控制参数放在 input 中。
examples:
basic:
summary: 屋顶上的春天
value:
model: elevenlabs/music
input:
composition_plan:
positive_global_styles:
- indie folk with subtle organic electronica
- 96 BPM, 4/4
- warm clear female lead vocal
- >-
acoustic guitar, rounded bass, delicate electronic
percussion
- hopeful intimate song about planting a rooftop garden
- >-
clean spacious studio mix, clear Mandarin and English
diction
negative_global_styles:
- harsh distortion
- crowded arrangement
- spoken narration
- abrupt cut off
sections:
- section_name: Acoustic introduction
duration: 8
positive_local_styles:
- instrumental only
- >-
fingerpicked acoustic guitar introduces a
memorable gentle motif
- soft airy pad, no drums
negative_local_styles: []
lines: []
- section_name: Mandarin verse
duration: 16
positive_local_styles:
- sing the supplied Mandarin lyrics clearly
- intimate gentle lead vocal
- >-
fingerpicked guitar and soft bass, restrained
percussion
negative_local_styles: []
lines:
- 把春天种在屋顶上
- 等风翻过旧砖墙
- section_name: English chorus
duration: 16
positive_local_styles:
- sing the supplied English lyrics clearly
- open uplifting melody
- full warm drums and bass enter
- >-
layered backing vocal harmonies, retain the
acoustic motif
negative_local_styles: []
lines:
- Little seeds above the street
- Find the sunlight, find the beat
- section_name: Instrumental resolution
duration: 8
positive_local_styles:
- instrumental only, no vocals
- return to fingerpicked guitar motif
- >-
drums fall away, warm sustained final chord with
natural decay
negative_local_styles: []
lines: []
respect_sections_durations: true
output_format: mp3_44100_128
clockmaker-clues:
summary: 钟表匠的线索
value:
model: elevenlabs/music
input:
text: >-
Create a 30-second instrumental jazz cue for a puzzle
scene in a clockmaker's workshop. 104 BPM, lightly
swinging 4/4, playful curiosity with a hint of mystery.
Use plucked upright bass, brushed drums, muted trumpet and
vibraphone, each clearly separated in a warm intimate
acoustic mix. Begin with a distinctive four-note
vibraphone motif over bass; let muted trumpet answer and
develop that motif in the middle, while brush accents
subtly increase the momentum. Resolve with a short, clean
ensemble cadence and allow the last note to decay
naturally. No vocals, choir, spoken words, ticking sound
effects or abrupt cutoff.
duration: 30
is_instrumental: true
output_format: mp3_44100_128
kelp-forest-light:
summary: 穿过海带森林的光
value:
model: elevenlabs/music
input:
text: >-
Compose a 40-second instrumental score for a nature
documentary gliding through a sunlit underwater kelp
forest. 72 BPM, gently flowing 4/4. Felt piano, delicate
harp harmonics, soft sustained strings and a subtle low
ambient texture; luminous, patient, full of quiet wonder.
Start sparsely with isolated felt-piano notes and wide
space. Gradually introduce harp and strings into an
expansive rising harmony through the middle third,
suggesting shafts of light moving through long fronds.
Gently thin the arrangement and finish on a peaceful
resolved chord with natural reverb decay. Detailed soft
dynamics, wide stereo depth, no heavy percussion, no
vocals or choir, no narration, no water sound effects, no
abrupt cutoff.
duration: 40
is_instrumental: true
output_format: mp3_44100_128
callback:
summary: 接收完成回调
value:
model: elevenlabs/music
input:
composition_plan:
positive_global_styles:
- indie folk with subtle organic electronica
- 96 BPM, 4/4
- warm clear female lead vocal
- >-
acoustic guitar, rounded bass, delicate electronic
percussion
- hopeful intimate song about planting a rooftop garden
- >-
clean spacious studio mix, clear Mandarin and English
diction
negative_global_styles:
- harsh distortion
- crowded arrangement
- spoken narration
- abrupt cut off
sections:
- section_name: Acoustic introduction
duration: 8
positive_local_styles:
- instrumental only
- >-
fingerpicked acoustic guitar introduces a
memorable gentle motif
- soft airy pad, no drums
negative_local_styles: []
lines: []
- section_name: Mandarin verse
duration: 16
positive_local_styles:
- sing the supplied Mandarin lyrics clearly
- intimate gentle lead vocal
- >-
fingerpicked guitar and soft bass, restrained
percussion
negative_local_styles: []
lines:
- 把春天种在屋顶上
- 等风翻过旧砖墙
- section_name: English chorus
duration: 16
positive_local_styles:
- sing the supplied English lyrics clearly
- open uplifting melody
- full warm drums and bass enter
- >-
layered backing vocal harmonies, retain the
acoustic motif
negative_local_styles: []
lines:
- Little seeds above the street
- Find the sunlight, find the beat
- section_name: Instrumental resolution
duration: 8
positive_local_styles:
- instrumental only, no vocals
- return to fingerpicked guitar motif
- >-
drums fall away, warm sustained final chord with
natural decay
negative_local_styles: []
lines: []
respect_sections_durations: true
output_format: mp3_44100_128
callback_url: https://your-domain.com/callback
responses:
'200':
description: 任务已提交
content:
application/json:
schema:
type: object
required:
- code
- data
properties:
code:
type: integer
enum:
- 200
data:
type: object
required:
- task_id
- status
- created_time
properties:
task_id:
type: string
status:
type: string
enum:
- not_started
- running
- finished
- failed
created_time:
type: string
format: date-time
example:
code: 200
data:
task_id: W6KDNIQQOUAE1K8V
status: running
created_time: '2026-09-27T10:48:12'
'400':
description: 输入校验失败或账户余额不足
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'401':
description: 凭证无效
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'403':
description: 拒绝访问
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'404':
description: 模型不存在或已停用
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'408':
description: 请求超时
content:
text/plain:
schema:
type: string
example: Request timeout
'422':
description: JSON 无效或请求体不是对象
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'429':
description: 超出速率限制或 API Key 积分限额
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'500':
description: 内部错误
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'502':
description: 无法创建上游生成任务
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'503':
description: 请求的模型暂时不可用
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 使用 VIDGO_API_KEY。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.