音频接口：转录、翻译与语音生成

音频转录是把录音变为文字；音频翻译接口通常把录音内容翻译成英文；文本转语音则把文字变为音频。它们的输入与结果格式不同，不应共用同一个请求体。

归壹地址与接入前提#

这些地址说明标准路由；执行前必须确认音频模型的当前归壹接入方式、分组与参数支持。OpenAI 音频路径使用归壹 API 密钥的 Authorization: Bearer 鉴权；Gemini 原生入口参照 Gemini 接口 的 x-goog-api-key 请求头。不要把密钥放到可公开分享的音频地址中。

1. 上传录音，转成文字#

POST /v1/audio/transcriptions
Authorization: Bearer <你的归壹 API 密钥>
Content-Type: multipart/form-data（由客户端生成 boundary）

file = <本地音频文件，例如 recording.wav>
model = <支持转录的模型 ID>
response_format = json

JSON 结果通常读取 text；text 响应是纯文本，srt 与 vtt 则是字幕文本。解析方式需要与 response_format 一致。文件大小、音频长度、编码和语言能力由目标模型决定，不用其他服务的限制替代当前说明。

2. 上传录音，翻译成英文#

使用 /v1/audio/translations，必需字段仍是 file 和 model，可按型号选择 prompt、response_format 与 temperature。这个合同的目标是英文，不是任意选择中文、日文等目标语言。若需要其他目标语言，可先完成转录，再将得到的文字交给支持的文本模型翻译。

POST /v1/audio/translations
Authorization: Bearer <你的归壹 API 密钥>
Content-Type: multipart/form-data（由客户端生成 boundary）

file = <本地音频文件，例如 recording.wav>
model = <支持此翻译接口的模型 ID>
response_format = json

按所选返回格式读取英文译文。转录模型、翻译模型和聊天模型的名称不能因为看起来相似就互相替换；若目标线路不支持此接口，需另行选择处理流程。

3. 输入文字，生成音频#

{
  "model": "tts-1",
  "input": "欢迎使用归壹。",
  "voice": "alloy",
  "response_format": "mp3"
}

成功结果是音频二进制，而不是含 data 数组的图片 JSON。程序应先检查 HTTP 状态和 Content-Type，再保存音频文件。错误时通常仍需解析错误响应，不能把任意返回内容都存成 .mp3 并认为生成成功。

4. Gemini 原生音频生成#

Gemini 路径为 /v1beta/models/{model}:generateContent，模型由路径指定。请求必需 contents 和 generationConfig；输出模态设为 AUDIO，speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName 指定声音。示例中的 Kore 是协议示意，实际声音和模型配对需确认。

{
  "contents": [
    {"parts": [{"text": "请用轻快自然的语气说：欢迎使用归壹。"}]}
  ],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": {"voiceName": "Kore"}
      }
    }
  }
}

遍历 candidates[].content.parts，从实际返回的 inlineData 读取 mimeType 和 Base64 data。输出可能是原始 PCM 等音频数据，不能仅改文件后缀就当成 MP3 或 WAV；应按响应的实际格式、采样率和声道信息进行封装或解码。不要凭本页示例固定假定某个采样率。

上线前核对#

1. 1

   先确认模型和接口

   在归壹模型广场与线路说明中确认音频能力、分组和当前请求格式；没有确认时先咨询支持。

2. 2

   使用已获授权的短素材

   先用不含客户隐私的小段文字或录音，不要把语音复制、克隆或他人声纹授权当作默认能力。

3. 3

   核对真实结果和计费

   检查文本是否正确或音频是否能解码播放，再对照使用记录；仅连接成功或 HTTP 200 不算完整验收。