SFX v3 API 指南：认证、请求与音频结果

先选择要使用的 API

存在两条不同路径：ElevenLabs 提供官方 SFX v3 接口，本站则有自己的模型目录、用户密钥、积分与异步任务。两者的密钥、模型标识、请求字段和响应格式不能互换。

通过本站接入时，从当前音频目录选择适合任务的模型，并使用目录返回的标识与参数。下方平台示例介绍本站接口约定；直接接入 ElevenLabs 则使用其独立账号。

路径 A：直接调用 ElevenLabs

将 ElevenLabs 密钥通过服务端环境变量 ELEVENLABS_API_KEY 提供。下列请求使用官方模型 ID，并将成功返回的音频保存到文件：

curl --fail --silent --show-error \
  --request POST \
  'https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128' \
  --header "xi-api-key: ${ELEVENLABS_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "A small wooden drawer closes once with a soft tap.",
    "model_id": "eleven_text_to_sound_v3",
    "duration_seconds": 4,
    "prompt_influence": 0.3
  }' \
  --output sfx-v3.mp3

使用文件前检查命令退出状态，不要把失败响应当成可播放音频。

官方接口文档定义 text、model_id、duration_seconds、prompt_influence 和查询参数 output_format。指定时长范围为 0.5–30 秒，提示词影响程度范围为 0–1；部分格式权限取决于 ElevenLabs 方案。这些是直接接口规则，不代表本站提供完全相同的控件。

当前模型文档列出 SFX v3 可通过 loop: true 请求循环。使用前核对当前约定，并试听接点。上游信息核查日期：2026 年 11 月 9 日。

路径 B：先查看本站模型目录

将 SFX_BASE_URL 设置为你的部署源站，例如 https://your-site.example。公开目录可以作为只读起点：

curl --fail --silent --show-error \
  "${SFX_BASE_URL}/api/ai/router01/models?type=audio"

先判断 JSON code。成功时，data 包含 slug、name、type、params 和目录报价信息。使用返回的模型 slug 与字段定义，不要假设它等于 ElevenLabs 模型 ID。

也可以在音频工作台中选择模型、填写提示词并查看参数和积分预估。音乐、语音与音效模型的用途不同，请根据任务选择。

本站生成与任务请求如何认证

登录后，在设置 → API 密钥创建用户密钥，通过服务端环境变量 SFX_API_KEY 提供。生成和任务查询使用 Authorization: Bearer …，ElevenLabs 密钥不能认证本站请求。

两项服务的密钥均不要放进浏览器代码或公开仓库。用户 API 密钥与管理凭证不同；显式提供无效密钥时，本站不会回退到浏览器登录态。

准备受支持输入并获取报价

从目录中选择适合任务的模型，将下面占位符替换为其 slug，并将 JSON 保存为 request.json：

{
  "mediaType": "music",
  "model": "REPLACE_WITH_AVAILABLE_SFX_SLUG",
  "prompt": "A small wooden drawer closes once with a soft tap.",
  "options": {
    "params": {}
  }
}

本站当前生成约定使用 mediaType: "music" 表示音频请求，包括兼容音效模型；公开目录的分类则是 audio。当前生成解析器不接受 mediaType: "audio"。

提示词使用顶层 prompt。模型专属选项放在 options.params 中，字段名、类型和值必须与所选模型声明一致。不要直接复制官方 API 字段。本站不使用顶层 duration_seconds，且音频请求的 options.duration 会被移除；受支持的时长字段需要通过模型声明的动态参数传入。

用同一个请求体获取报价：

curl --fail --silent --show-error \
  --request POST \
  "${SFX_BASE_URL}/api/ai/router01/quote" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

报价成功时查看 data.credits。报价本身不创建生成；提交前应让使用者确认消耗。生成服务端会重新计算价格，不信任客户端传来的金额。

提交本站生成任务

下面请求会创建任务，并可能消耗账号积分：

curl --fail --silent --show-error \
  --request POST \
  "${SFX_BASE_URL}/api/ai/generate" \
  --header "Authorization: Bearer ${SFX_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

成功 JSON 包含 data.id、data.taskId、data.taskStatus、data.costCredits 和 data.remainingBalance。保存本站 data.id，用于持续查询同一个任务。初始状态为 queued，响应并非音频，不要将其保存成 MP3。

本文没有提供生成幂等键。如果 POST 超时，先查看已有任务或作品，再决定是否重提。重复提交可能创建另一个单独计费的任务。

查询任务并取得结果

将 SFX_TASK_ID 设置为成功提交后返回的本站任务 ID：

curl --fail --silent --show-error \
  "${SFX_BASE_URL}/api/ai/task?taskId=${SFX_TASK_ID}" \
  --header "Authorization: Bearer ${SFX_API_KEY}"

data.taskStatus 为 queued、pending、processing 时，采用有上限、逐步增加间隔的等待，继续查询同一 ID；遇到 success、failed、canceled 后停止。

成功音频任务的标准化响应在 data.taskInfo.songs[].audioUrl 中提供音频地址。songs 是本站现有音频容器名称，不代表内容必须是音乐。再单独下载返回文件，并检查实际格式。失败或取消时，查看 data.taskInfo.userErrorCode，不要假设一定存在输出地址。

错误与预算处理

本站使用 JSON 包装响应：code: 0 表示成功，code: -1 表示带 message 的应用错误。即使 HTTP 为 200 也要判断此字段；HTTP 请求失败同样需要处理。

模型或参数不支持时应修正输入，而不是盲目重试；认证失败应核对账号、密钥与域名；服务繁忙则增加等待，避免紧密重提。成功但不采用的输出，与失败任务不同，详见价格、条款和故障排查。

延伸阅读与支持

创作输入可参考提示词指南、游戏流程和视频流程。发布素材前阅读商用说明。

已经审核的一组官方请求可配合 Python 批量教程与下载文件。需要把脚本整理为有限计划并加入试听步骤时，参考 AI 音效工作流；切换版本前阅读 v3 与 v2 对比指南。

本站问题可提交支持工单，或联系 support@sfxv3.com，附接口、大致请求时间、任务 ID 和去除敏感信息的错误。不要附密钥或认证请求头。直接调用 ElevenLabs 则使用其支持与协议。