音频

音频接口沿用 OpenAI 兼容格式。使用前先确认模型名称。

第一次联调音频接口时，最容易误判的是：
文件传不上去、格式不对、音频本身不清晰，看起来都像“接口坏了”。
所以音频任务更适合先用最短文本、最短音频文件做测试。

音频接口通常分成三类：

• 语音合成：把文本变成音频
• 语音识别：把音频转成文本
• 语音翻译：把音频内容转成另一种语言的文本

第一次联调时，建议先选最短文本或最短音频文件做测试。音频任务通常比普通文本请求更容易受到文件大小、编码格式和上传方式影响。

第一次先测哪一种更省事

如果你三类都要接，第一次通常建议按这个顺序来：

1. 语音合成
2. 语音识别
3. 语音翻译

原因很直接：

• 语音合成不需要先上传文件，最容易先证明地址、Key 和模型是通的
• 语音识别会多一层文件上传和音频质量问题
• 语音翻译除了上传，还会再多一层目标语言理解

先把最简单的一层跑通，后面遇到问题时，你就更容易知道自己卡在“模型链路”还是“文件处理”。

语音合成 POST

地址：POST https://xiaolan.ainb.plus/v1/audio/speech

常用请求参数

• model：语音模型
• input：要合成的文本
• voice：音色名称
• format：输出格式

示例请求

先把 MODEL 替换成模型广场里实际可用的语音模型名：

MODEL="替换成模型广场里的语音模型名"

curl https://xiaolan.ainb.plus/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的 API Key>" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "你好，这是一段测试语音",
    "voice": "alloy"
  }' --output speech.mp3

第一次测试时，文本尽量短一些。先确认文件能成功导出、能正常播放，再继续换更长内容或更多音色。

如果这一步已经成功，再继续换更长文本、更多音色或更复杂参数，排障会清楚很多。

如果你拿到的是一个空文件，或者文件大小明显不正常，先不要急着怀疑音色参数。
先看 curl 返回时有没有其实已经输出了 JSON 错误信息，只是你把它重定向到了文件里。

语音识别 POST

地址：POST https://xiaolan.ainb.plus/v1/audio/transcriptions

示例请求

先把 MODEL 替换成模型广场里实际可用的识别模型名：

MODEL="替换成模型广场里的识别模型名"

curl https://xiaolan.ainb.plus/v1/audio/transcriptions \
  -H "Authorization: Bearer <你的 API Key>" \
  -F file=@sample.mp3 \
  -F model="$MODEL"

第一次拿来测试的音频，尽量满足三点：

• 时长短
• 人声清晰
• 背景音少

这样做不是为了追求一次识别得多漂亮，而是为了先证明上传、格式和模型都没问题。

响应

不同模型返回字段可能略有差异，通常直接取文本结果即可。

第一次接通时，先不要急着追求完整业务流程。
先确认：

• 合成接口能输出文件
• 识别接口能返回可读文本
• 模型名确实是当前这类任务可用的音频模型

识别或翻译第一次成功时，也不一定要逐字完全一致。
只要主干内容已经能稳定识别出来，就说明链路是通的；后面再去优化音频质量、提示词和业务格式会更有效。

语音翻译 POST

地址：POST https://xiaolan.ainb.plus/v1/audio/translations

示例：

MODEL="替换成模型广场里的翻译模型名"

curl https://xiaolan.ainb.plus/v1/audio/translations \
  -H "Authorization: Bearer <你的 API Key>" \
  -F file=@sample.mp3 \
  -F model="$MODEL"

使用建议

• 文件名尽量不要带特殊符号
• 大文件先压缩或切片
• 语音合成先用短句测试音色
• 识别失败时先换清晰音频验证
• 模型名始终从模型广场复制，不要照抄别处示例

如果你准备做批量音频处理，再补一条很实用的顺序：

1. 先用单文件跑通
2. 再用 2 到 3 个小文件做批量脚本
3. 最后再放大到真正的业务规模

音频任务一旦批量化，上传失败、超时和单文件异常都会被放大。先把小样本跑通，后面排错会轻很多。

常见问题

上传文件失败

确认使用的是 multipart/form-data，curl 里用 -F，不要用 JSON 直接传文件路径。

如果你拿别的接口的 JSON 示例直接改，很容易就在这里出错。
音频上传类接口最常见的问题之一，就是请求头和传参方式沿用了文本接口的写法。

合成结果无法播放

确认保存了输出文件：

--output speech.mp3

再用本地播放器打开。

识别结果很差

优先先排这几件事：

• 音频本身是否清晰
• 是否夹杂过多背景音
• 文件是否过长，适合先切片
• 当前模型是否就是你想用的识别模型

返回 400 或 415

这类错误通常优先看上传层，而不是模型层：

• 文件字段是不是用 -F file=@xxx
• 文件格式是不是当前模型支持的音频格式
• 你是不是把识别接口当成了 JSON 请求去发