博客

使用指南

ElevenLabs Sound Effects v3 API:30 秒音效、无缝循环与 v2 迁移

价格、参数、请求示例和提示词写法,一篇讲清

2026年11月11日 6 分钟阅读
深墨绿色背景上的多面低多边形矿物横截面,带有青绿色和孔雀石色调
模型
elevenlabs-sound-effects
本页内容

Sound Effects v3 能做什么

ElevenLabs Sound Effects v3 是 HiAPI 上的文字生成音效模型,模型 ID 是 elevenlabs/sound-effects-v3。用一段文字描述想要的声音,比如动作、场景、氛围和表现方式,模型就会生成一段对应的音效。时长可以设为 0.5–30 秒,也可以要求生成首尾能无缝衔接的循环音效。

每次调用生成 1 段 MP3 音频。本文介绍价格、参数、请求示例、和 v2 的区别,以及写提示词的方法。文中的数字按写作时的接口定义给出。

Sound Effects v3 API 价格

按请求的时长(duration_seconds)计费,每秒 $0.0029。

  • 2 秒(默认时长):$0.0058
  • 5 秒:$0.0145
  • 10 秒:$0.029
  • 30 秒(最长):$0.087

打开循环(loop)或调整 prompt_influence 都不额外收费。任务失败全额退款。v2 的单价也是 $0.0029/秒,两代价格相同。

参数

必填参数只有 prompt 和 duration_seconds,其余都可以不传。

  • prompt:必填,1–450 个字符,描述要生成的声音。
  • duration_seconds:必填,0.5–30 秒,没有「自动时长」。
  • loop:是否生成可以无缝循环播放的音效,默认 false。
  • prompt_influence:0–1,默认 0.3。数值越高越贴近提示词的字面描述,越低结果变化越多。

发起请求

HiAPI 的音效生成是异步任务:先创建任务,再查询结果。model 放在顶层,其余参数放在 input 里。

生成一段 5 秒的开门声:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/sound-effects-v3",
    "input": {
      "prompt": "Heavy wooden door creaking open slowly in a quiet stone hallway, then a soft thud as it stops",
      "duration_seconds": 5
    }
  }'

生成一段 10 秒、可循环播放的雨声:

{
  "model": "elevenlabs/sound-effects-v3",
  "input": {
    "prompt": "Gentle rain on a tin roof with distant rolling thunder, calm night ambience, no music",
    "duration_seconds": 10,
    "loop": true
  }
}

第二个请求的费用是 10 × $0.0029 = $0.029。创建任务后,轮询 GET https://api.hiapi.ai/v1/tasks/{taskId},状态变为成功后,从输出里下载音频地址。

v3 和 v2 有什么不同

两代的参数名和价格都一样,在 HiAPI 上的区别主要有三点:

  • 时长上限:v3 最长 30 秒,v2 最长 22 秒。需要 22–30 秒的环境声或铺底声,只能用 v3。
  • 效果:ElevenLabs 官方文档说,和 v2 相比,v3 能更准确地遵循包含多条指令的提示词,处理带音乐或人声的提示词更好,听感更自然,生成风铃、口哨这类高频声音时更不容易削波。官方也说明结果因提示词而异,建议用自己的提示词把两代都试一下。
  • 后续维护:ElevenLabs 官方已把 v2(eleven_text_to_sound_v2)标为弃用,计划在 2027 年 3 月 1 日下线。新项目建议直接用 v3。

从 v2 迁移到 v3,只需把 model 改成 elevenlabs/sound-effects-v3,其余参数不用改。上线前,建议用业务里常用的几条提示词对比一下两代的结果。

提示词怎么写

  • 写具体的动作、场景、氛围和表现方式,不要只写一个笼统的类别。比如「脚踩在湿砾石上、步速缓慢」比「脚步声」效果更稳定。
  • 可以描述先后顺序,比如「Footsteps on gravel, then a metallic door opens」(先是踩砾石的脚步声,接着一扇金属门打开)。
  • 可以用音效行业术语,比如 impact(撞击)、whoosh(呼啸掠过)、ambience(环境声)、one-shot(单次音效)、drone(持续铺底音)。
  • 不要指望模型严格按次数重复。官方说明,「敲三角铁 4 下」这类精确次数的要求不一定会被执行。需要精确节奏时,生成一次之后再自己剪辑拼接。
  • 按需调整 prompt_influence:UI 音效、提示音这类需要稳定一致的声音,可以调到 0.6 以上;想多要几个不同风格的方案时,用默认的 0.3 或更低。

当前限制

  • 每次调用只生成 1 段音频。要多个候选,就并行发多个任务。
  • 时长范围是 0.5–30 秒,必须显式传入,没有自动时长。
  • 提示词最多 450 个字符。
  • 只支持异步任务,没有同步返回。
  • 输出为 MP3,目前不能选其他格式。

适合哪些场景

v3 适合需要大量、快速产出短音效的场景,比如游戏和应用的界面提示音、短视频和广告的转场音效、影视或预告片前期的拟音样稿,以及有声书和直播间的循环环境声。一段 5 秒的音效 $0.0145,可以先批量生成几个版本,挑一个满意的再进入后期,成本比一次次找素材、改素材低。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档