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.
ElevenLabs Music Text to Audio API
elevenlabs/musicElevenLabs Music Text to Audio 将文字描述转化为歌曲或纯音乐,支持歌词输入与分段编曲。你可以分别设置整曲和各段的风格与时长,安排前奏、主歌和副歌的音乐变化。
Input
继续制作配音
Examples
音乐生成接口
开始调用音乐生成接口
提交音乐描述或编曲计划,取得任务标识,再查询状态并读取音频文件。示例使用已验证的分段歌曲请求。
配置身份验证
使用 Vidgo API Key 作为 Bearer 凭证,并以 JSON 提交请求。
- 提交地址
- POST
https://api.vidgo.ai/api/generate/submit - 身份验证
- Authorization: Bearer <VIDGO_API_KEY>
提交编曲计划
以下示例按前奏、主歌、副歌和尾奏组织歌曲;可替换风格与歌词后提交。
REQUEST_BODY=$(cat <<'JSON'
{
"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
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"查询任务状态
将提交响应中的 task_id 填入状态查询地址,查询同一任务的进度。
状态查询地址
GET https://api.vidgo.ai/api/generate/status/{task_id}使用相同的 Bearer 凭证查询任务;finished 后读取 files,failed 时读取 error_message。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "W6KDNIQQOUAE1K8V",
"status": "not_started"
}
}{
"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"
}
]
}
}获取音频文件
状态为 finished 后,读取 files 中 file_type 为 audio 的文件地址进行播放或下载。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"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
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
请求对象包含 model 和 input。model 使用 elevenlabs/music,input 选择 text 或 composition_plan。可在请求顶层填写 callback_url,值为 HTTP 或 HTTPS 地址。
| 字段 | 类型 | 填写要求 | 默认值 | 说明 |
|---|---|---|---|---|
| input.text | string | 文字方式必填 | — | 音乐描述,1–4100 字符。与 composition_plan 二选一。 |
| input.composition_plan | object | 编曲方式必填 | — | 按段编排音乐,包含全局风格与 sections。与 text 二选一。 |
| input.duration | number | 文字方式可选 | — | 文字方式的目标时长,3–600 秒,可含小数;省略时由模型决定。 |
| input.is_instrumental | boolean | 文字方式可选 | false | 设为 true 生成纯音乐;使用 text 时填写。 |
| input.respect_sections_durations | boolean | 编曲方式可选 | true | 控制模型遵循各段目标时长的严格程度;使用 composition_plan 时填写。 |
| input.output_format | string | 可选 | mp3_44100_128 | 选择音频编码、采样率与比特率,合法取值见下方列表。 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 |
| input.composition_plan.positive_global_styles | string[] | 编曲方式必填 | — | 整首音乐的风格方向,如曲风、乐器和节奏;允许空数组。 |
| input.composition_plan.negative_global_styles | string[] | 编曲方式必填 | — | 整首音乐应避开的风格元素;允许空数组。 |
| input.composition_plan.sections | object[] | 编曲方式必填 | — | 至少一个段落,按数组顺序组织音乐。 |
| input.composition_plan.sections[].section_name | string | 每段必填 | — | 段落名称,1–100 字符,用于标记前奏、主歌或副歌等结构。 |
| input.composition_plan.sections[].positive_local_styles | string[] | 每段必填 | — | 本段的乐器、人声与情绪方向;允许空数组。 |
| input.composition_plan.sections[].negative_local_styles | string[] | 每段必填 | — | 本段应避开的风格元素;允许空数组。 |
| input.composition_plan.sections[].duration | number | 每段必填 | — | 本段目标时长,3–120 秒,可含小数。 |
| input.composition_plan.sections[].lines | string[] | 每段必填 | — | 每项是一行歌词,每行最多 200 字符;纯音乐段落可用空数组并指定器乐风格。 |
响应字段
成功响应的 code 为 0 或 200,任务对象位于 data;完成后从 data.files 读取音频文件。
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务标识,用于后续状态查询。 |
| status | string | 当前任务状态,取值见任务状态说明。 |
| files | object[] | 生成完成后的文件列表。 |
| files[].file_url | string | 音频文件地址,可用于播放或下载。 |
| files[].file_type | string | 音乐结果的文件类型为 audio。 |
| progress | number | 响应提供时显示任务进度。 |
| error_message | string | null | 任务失败时的错误说明。 |
任务状态
保存提交后返回的 task_id,并使用同一标识查询生成进度。
not_started任务已进入队列,等待开始生成。
running正在创作音乐,继续查询同一任务。
finished生成完成,从 files 中读取音频文件地址。
failed任务失败,读取 error_message 后检查输入。
查询与异常处理
- 校验创作方式按文字或编曲方式填写字段,检查数值时长、布尔开关和字符串数组。
- 继续查询现有任务任务处于 not_started 或 running 时继续查询状态;体验区自动查询暂停后,可点击“继续查询任务”。
- 根据响应处理异常请求异常时检查 HTTP 状态和响应信息;任务状态为 failed 时,读取 error_message 并检查输入后重试。
接口规格
| 项目 | 取值 | 说明 |
|---|---|---|
| 模型标识 | elevenlabs/music | 提交请求时将 model 设置为此值。 |
| 输入方式 | text / composition_plan | 每次选择一种创作方式。 |
| 文字时长 | 3–600 s | 可选,省略时由模型决定时长。 |
| 单段时长 | 3–120 s | 编曲计划中每段分别填写。 |
| 输出类型 | audio | 完成后通过 files 读取文件地址。 |
ElevenLabs Music Text to Audio API 常见问题
ElevenLabs Music Text to Audio API 是什么?
ElevenLabs Music Text to Audio 是 ElevenLabs 用于将文字描述转化为音乐的模型。它可生成歌曲或纯音乐,并通过编曲计划设置各段歌词、风格与时长。全局和局部风格控制将整曲基调与段落变化结合,帮助组织前奏、主歌和副歌。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
ElevenLabs Music 如何生成纯音乐?
使用文字创作时开启 Is Instrumental,并描述需要的乐器、情绪和节奏。使用编曲计划时,为器乐段落保留空的 Lines,并在该段风格中写明 instrumental 和乐器安排。
ElevenLabs Music 怎样使用自己的歌词?
在 Composition Plan 的各个段落中填写 Lines,每项对应一行歌词,每行最多 200 字符。再用局部风格描述演唱语言、人声特点和伴奏,并为该段设置时长。
ElevenLabs Music 如何安排主歌和副歌?
使用 Composition Plan,按演奏顺序添加前奏、主歌、副歌和尾奏等段落。每段独立设置名称、风格、歌词和时长;开启 Respect Sections Durations,让模型按指定段落时长编排。
ElevenLabs Music 的全局风格如何影响编曲?
全局风格设定整首音乐共同的曲风、乐器和情绪方向,局部风格描述某一段的具体表现。正向列表填写希望采用的元素,负向列表填写希望避开的元素,例如把整曲设为原声民谣,再让副歌加入鼓组与和声。
ElevenLabs Music 可以生成多长的音乐?
文字方式可指定 3–600 秒,留空时由模型决定时长。编曲方式为每段设置 3–120 秒,并用多个段落组织音乐;各段时长可填写小数。
ElevenLabs Music 提示词应该怎么写?
先写曲风和情绪,再补充主要乐器、节奏以及人声方向,例如“轻快爵士,温暖钢琴与刷鼓,纯音乐”。需要明显的结构变化时,用编曲计划为不同段落设置局部风格,文字描述最多 4100 字符。
ElevenLabs Music 提供哪些音频格式?
Output Format 提供 MP3、Opus、PCM、μ-law 和 A-law,共 19 个编码与采样配置。默认 mp3_44100_128 对应 44.1 kHz、128 kbps 的 MP3,完整取值见本页参数说明。
ElevenLabs Music 如何按分钟计费?
每开始一分钟收取 128 credits,即 $0.64。文字方式按指定时长向上取整,编曲方式先合计段落时长再向上取整;60 秒为 128 credits,60.1 秒为 256 credits。文字时长留空时,提交前费用按一分钟估算,生成时长由模型决定。

