语音与音频

应用可以通过音频转录或翻译录制的语音、生成语音输出、在一次模型轮次中加入音频，或维持实时对话。这些工作流需要不同的请求和交付模型。

AISIX 为每种工作流提供独立接口。对于所有这些接口，网关都会认证调用方、解析模型别名、应用该接口所支持的访问限制和限流，并记录请求遥测。

选择音频接口

请根据应用交互方式选择接口：

需求	使用的接口
转录或翻译已录制的音频文件	`POST /v1/audio/transcriptions` 或 `POST /v1/audio/translations`
从文本生成独立语音文件或音频流	`POST /v1/audio/speech`
在一条聊天消息中发送录音，或在完整聊天响应中接收生成的音频	`POST /v1/chat/completions`
建立交互式双向 WebSocket 音频会话	`GET /v1/realtime`

本页其余部分介绍用于转录、翻译和语音生成的独立 /v1/audio/* 路由。

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

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

准备工作

请先准备以下内容：

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

导出示例使用的网关连接和调用方 API Key：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

发送转录请求

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

curl -sS -X POST "${AISIX_PROXY}/v1/audio/transcriptions" \
  -H "Authorization: Bearer ${AISIX_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 ${AISIX_API_KEY}" \
  -F "file=@meeting.wav" \
  -F "model=transcribe-prod" \
  -F "response_format=srt"

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

转录流式传输

部分转录模型接受 stream=true 并返回服务器发送事件。AISIX 会在上游产生这些事件的同时转发它们，因此客户端可以逐步收到转录文本，而不必等待整个请求结束。转发的事件与上游原样一致，AISIX 在事件流经时从最终事件中读取用量。

例外情况是能够阻断或脱敏转录文本的输出安全护栏。这类护栏必须在任何内容到达调用方之前检查完整的转录文本，因此 AISIX 会先缓冲响应、完成检查，然后放行或阻断——与非流式请求获得的保护完全相同。监控模式下的护栏永远不会阻断，因此也不会缓冲响应，它会在流结束后再观察转录文本。

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

发送语音请求

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

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

请求成功时，输出文件应包含上游服务提供方返回的音频字节。请将响应作为二进制文件处理，而不是聊天风格 JSON 响应。AISIX 会在服务提供方生成音频的同时转发，因此播放该响应的客户端可以从最初的字节开始播放，而不必等待整个文件。

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

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 字段和预期的音频文件字段。

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

如果请求的转录格式失败，请确认解析出的服务提供方和模型支持该格式。如果流式转录事件只在请求完成后到达，请检查该模型是否挂载了会阻断或脱敏转录文本的输出安全护栏——这类护栏按设计会缓冲响应；同时还应确认上游模型支持 stream=true。

下一步

你已经了解 AISIX 如何转发独立的 OpenAI 风格音频请求，以及音频响应处理与 JSON 代理路由的差异。

如需在聊天轮次中发送或接收音频，请参阅使用 Chat Completions 输入和输出音频。如需交互式语音会话，请参阅 Realtime API。当需要访问 AISIX 尚未直接建模的服务提供方原生路由时，请继续阅读透传路由。

选择音频接口​

准备工作​

发送转录请求​

选择响应格式​

转录流式传输​

发送语音请求​

音频端点行为​

服务提供方支持​

用量与安全护栏行为​

排查音频请求​

下一步​