语音与音频

音频路由支持语音转文本、语音翻译和文本转语音请求。它们使用与其它 OpenAI 兼容代理 API 相同的网关认证、模型别名和流量控制。

AISIX 会解析面向调用方的模型别名，执行访问检查和受支持的文本安全护栏，再将请求转发到支持相同音频路由的上游。它会保留端点专属的请求和响应结构，而不会将其转换为聊天风格格式。

本指南将通过 AISIX 发送语音转文本和文本转语音请求，然后说明不同音频端点的行为差异。

准备工作

请先准备以下内容：

一个可以处理代理请求的 AISIX 网关。
一个可以访问该模型别名的调用方 API Key。
一个由支持目标音频路由的服务提供方和模型支撑的模型别名。

示例使用本地快速入门网关的源站地址。需要时，请替换为自己的网关源站地址，末尾不要带斜杠：

export AISIX_PROXY="http://127.0.0.1:3000"

发送转录请求

转录请求使用 multipart/form-data 上传，而不是 JSON 请求体。请在 file 字段中发送音频文件，并在 model 字段中发送 AISIX 模型别名：

curl -sS -X POST "$AISIX_PROXY/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -F "file=@meeting.wav" \
  -F "model=transcribe-prod"

请求成功时，上游会返回转录文本：

{
  "text": "The quick brown fox jumps over the lazy dog."
}

AISIX 会使用上游模型 ID 重建 multipart form，并保留其余字段。配置的输入安全护栏可以在 AISIX 将表单发送到上游前，阻断或屏蔽携带文本的 prompt 字段。

如果要把非英语语音翻译为英语文本，请将同一表单发送到 /v1/audio/translations。

选择响应格式

可选的 response_format 字段用于选择转录文本的表示形式。对于成功请求，除非配置的输出安全护栏阻断或屏蔽了转录文本，否则 AISIX 会保留上游响应体及其内容类型。因此在安全护栏未更改响应时，请求的表示形式会保持不变：

`response_format`	响应内容类型	响应体
`json`（默认）	`application/json`	`{"text": "..."}`
`verbose_json`	`application/json`	转录文本以及 `duration`、`language` 和各分段时间信息
`text`	`text/plain`	仅包含转录文本
`srt`	`text/plain`	包含提示时间的 SubRip 字幕
`vtt`	`text/plain`	包含提示时间的 WebVTT 字幕

请根据内容类型处理转录响应，不要假定响应一定是 JSON。只有 json 和 verbose_json 会生成 JSON 响应体：

curl -sS -X POST "$AISIX_PROXY/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -F "file=@meeting.wav" \
  -F "model=transcribe-prod" \
  -F "response_format=srt"

格式支持取决于上游模型，而不是 AISIX。如果模型拒绝某种格式，请检查 AISIX 返回的错误以及服务提供方的模型文档。不要依赖错误响应体与上游响应逐字节完全一致。

缓冲式转录流

部分转录模型接受 stream=true 并返回服务器发送事件。AISIX 当前会在响应前完整读取上游音频响应，因此事件会在上游请求完成后一起交付，而不是在实时转录过程中逐步交付。除非输出安全护栏更改或阻断转录文本，否则这些事件会在响应中返回，AISIX 也可以从最终事件中提取用量。

流式支持取决于具体模型。例如，OpenAI 的文件转录指南使用 gpt-transcribe 模型进行流式传输，而官方 SDK 规范指出 whisper-1 会忽略 stream。依赖流式转录事件前，请先检查上游模型文档。

发送语音请求

通过网关代理发送语音生成请求，并在请求体中使用 AISIX 模型别名：

curl -sS -X POST "$AISIX_PROXY/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-prod",
    "input": "Hello from AISIX.",
    "voice": "alloy"
  }' \
  --output aisix-speech.mp3

请求成功时，输出文件应包含上游服务提供方返回的音频字节。请将响应作为二进制文件处理，而不是聊天风格 JSON 响应。

检查文件是否已写入为音频输出：

file aisix-speech.mp3

你应看到表明该文件为音频的输出。具体文字取决于操作系统和上游响应格式：

aisix-speech.mp3: MPEG ADTS, layer III, v2, 160 kbps, 24 kHz, Monaural

音频端点行为

不同音频端点不一定使用相同请求或响应形态：

端点	请求体	响应体
转录	包含音频文件和模型别名的 multipart form	采用请求的 `response_format` 的上游转录结果
翻译	包含音频文件和模型别名的 multipart form	采用请求的 `response_format` 的上游翻译结果
语音	包含模型别名、文本输入和 voice 的 JSON body	二进制音频字节

对于转录和翻译请求，AISIX 会在转发前使用上游模型 ID 重建 multipart form。其它表单字段会被保留，包括上传文件名和内容类型（如果存在）。

对于语音请求，AISIX 会改写 JSON body 中的 model 字段，并将其余请求字段转发给上游服务提供方。

对于成功请求，除非转录文本安全护栏更改或阻断了输出，否则网关会保留上游响应体和内容类型。客户端应根据请求的 response_format 处理转录和翻译响应，并将语音响应作为二进制音频输出处理。

服务提供方支持

音频支持取决于解析出的服务提供方和模型。AISIX 不会在不同服务提供方族之间转换音频格式。

请将这些路由用于暴露匹配 OpenAI 风格音频端点的上游。如果上游不支持请求的音频路由，该失败通常是服务提供方能力或 base URL 问题，而不是调用方认证问题。

用量与安全护栏行为

成功的音频请求会归因到网关用量事件中。只有当上游响应包含可识别的 Token 用量时，才会填充 Token 计数。

转录和翻译请求还可以上报音频时长。AISIX 会从受支持的上游响应中读取时长，必要时则测量上传文件。这样，AISIX Cloud 可以为按时长而不是按 Token 计费的模型定价，包括使用非 JSON response_format 的请求。请在模型定价中设置费率。语音请求不会上报音频时长，因此 AISIX 时长定价不适用于这类请求。

输入安全护栏可以在 AISIX 调用服务提供方前检查、阻断或屏蔽语音请求的 input 文本，以及转录和翻译请求中可选的 prompt 字段。输出安全护栏可以检查、阻断或屏蔽转录文本。如果输出安全护栏阻断了转录文本，AISIX 仍会记录已计费用量，因为上游已经处理了音频。

上传的音频字节和生成的语音字节不会作为文本扫描。

排查音频请求

如果语音请求成功但客户端期望 JSON，请调整响应处理逻辑。语音端点返回的是音频字节。

如果转录或翻译请求从 AISIX 或上游返回 400，请检查 multipart form 构造。请求必须包含 model 字段和预期的音频文件字段。

如果语音安全护栏没有阻断请求，请检查请求文本。语音安全护栏检查的是输入文本，而不是生成后的音频字节。

如果请求的转录格式失败，请确认解析出的服务提供方和模型支持该格式。如果流式转录事件只在请求完成后到达，这是 AISIX 当前的缓冲行为；同时还应确认上游模型支持 stream=true。

下一步

你已经了解 AISIX 如何转发 OpenAI 风格音频请求，以及音频响应处理与 JSON 代理路由的差异。当需要访问 AISIX 尚未直接建模的服务提供方原生路由时，请继续阅读服务提供方透传。

准备工作​

发送转录请求​

选择响应格式​

缓冲式转录流​

发送语音请求​

音频端点行为​

服务提供方支持​

用量与安全护栏行为​

排查音频请求​

下一步​