OpenAI 提供的音频接口主要分为两类：Whisper 负责把语音转成文本，TTS 负责把文本合成语音。两者都通过标准 HTTPS 请求完成调用，不需要额外的 SDK 或者复杂的流式协议。本文将围绕 Python 和 curl 两种调用方式，拆解请求头、参数、返回值和常见错误处理，帮助你把这两个能力快速接入自己的应用。
一、调用前的准备：密钥、模型与文件格式
调用 OpenAI API 前需要准备一个有效的 API Key。登录 platform.openai.com 后，在 API Keys 页面创建密钥，并设置环境变量 OPENAI_API_KEY，避免把密钥硬编码到代码里。Python 代码中可以通过 os.environ 读取。请求头统一使用 Authorization: Bearer 加上密钥，并且 Content-Type 根据接口不同有所区别。Whisper 使用 multipart/form-data 上传文件，TTS 使用 application/json 提交参数。
音频格式方面，Whisper 支持常见的音频和视频文件格式，包括 mp3、mp4、mpeg、mpga、m4a、wav、webm 等，单文件大小限制为 25MB。超出限制时，需要先对音频进行切片或压缩。TTS 接口输出音频流，支持的格式有 mp3、opus、aac、flac，默认是 mp3。模型名称方面，语音识别统一使用 whisper-1，语音合成可以选择 tts-1 或 tts-1-hd，前者延迟更低，后者音质更细。
如果不想在命令行中暴露密钥，可以把密钥写入 .env 文件，通过 python-dotenv 加载。curl 调用时可以直接引用环境变量，例如 $OPENAI_API_KEY。接下来分别说明两个接口的具体用法。
二、Whisper 语音识别接口实战
Whisper 的转录端点是 https://api.openai.com/v1/audio/transcriptions，方法为 POST。与普通 JSON 请求不同，这里需要以 multipart/form-data 格式提交文件。必填字段只有 file 和 model，可选字段有 language、prompt、response_format、temperature。language 建议显式传入，例如中文传入 zh，否则模型会自动检测，但可能受背景噪音影响。prompt 可以补充专有名词、人名或行业术语，帮助模型提升识别准确率。
用 Python 的 requests 库调用时，代码很直接。下面是一个完整示例，读取本地文件并返回纯文本结果：
import requests
import os
url = "https://api.openai.com/v1/audio/transcriptions"
headers = {
"Authorization": f"Bearer {os.environ.get('OPENAI_API_KEY')}"
}
files = {
"file": open("meeting.mp3", "rb")
}
data = {
"model": "whisper-1",
"language": "zh",
"response_format": "text"
}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)
如果希望获得更丰富的元数据，可以把 response_format 改为 verbose_json，返回的结果会包含语言、分段、置信度、时间戳等信息。需要注意，verbose_json 的响应不是纯文本，而是一个 JSON 对象，需要按 JSON 解析。如果上传文件超过 25MB，接口会返回 413 错误，这时可以先用 ffmpeg 把音频切片，例如每 10 分钟一段，再逐段调用，最后按顺序拼接文本。对于长会议录音，还可以设置 prompt 把上一段的人名术语带入下一段，减少专有名词识别偏差。
另外，Whisper 接口对音频采样率没有硬性要求，但建议 16kHz 以上的单声道文件，识别效果更稳定。如果原始文件是视频，可以直接把 mp4 文件作为 file 参数上传，Whisper 会自动提取音轨。错误处理上，401 表示密钥无效，429 表示触发了速率限制，官方对免费账户的请求频率有严格限制，实际生产环境需要做重试和退避。
三、TTS 文本转语音接口详解
TTS 接口的端点是 https://api.openai.com/v1/audio/speech，方法是 POST，请求体是标准的 JSON。必填字段为 model、input、voice，其中 input 是要合成的文本，最大长度 4096 字符。voice 有六种内置音色：alloy、echo、fable、onyx、nova、shimmer。alloy 偏中性，nova 偏明亮，onyx 偏低沉有力，可以根据应用场景选择。可选参数 response_format 控制输出格式，speed 控制语速，范围是 0.25 到 4.0，默认 1.0。
与 Whisper 不同的是，TTS 接口返回的不是 JSON，而是音频文件的二进制流。因此在请求时需要设置 Accept 头为期望的音频格式，或者直接使用 response_format 参数，然后以二进制方式写入文件。下面的 Python 示例将一段中文文本合成为 mp3 文件：
import requests
import os
url = "https://api.openai.com/v1/audio/speech"
headers = {
"Authorization": f"Bearer {os.environ.get('OPENAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "tts-1",
"input": "你好，这是通过OpenAI接口生成的语音。",
"voice": "nova",
"response_format": "mp3",
"speed": 1.0
}
response = requests.post(url, headers=headers, json=payload)
with open("output.mp3", "wb") as f:
f.write(response.content)
如果希望减少延迟，可以选择 tts-1 模型，它的生成速度较快，但偶尔在高频细节上不如 tts-1-hd 自然。对于实时性要求不高的场景，比如有声书或者演示配音，tts-1-hd 会更合适。输出格式中，opus 体积更小，适合网络传输，但部分老旧播放器兼容性差；mp3 兼容性最好；flac 是无损压缩，文件较大。语速参数 speed 在 0.25 到 4.0 之间调整，例如 0.5 会让语音变慢，适合语言学习场景。
TTS 接口的限流与 Whisper 类似，频繁调用可能收到 429 状态码。可以在代码中加入指数退避逻辑，比如第一次失败等待 2 秒，第二次等待 4 秒。还需要注意 input 文本中如果包含特殊字符，接口会自动转义，但建议避免直接拼接用户输入，防止产生意外费用或生成不合适的内容。
四、组合调用与工程化建议
实际的音视频处理流程往往不是单一的识别或合成，而是两者的组合。比如在智能客服中，用户发送语音，先调用 Whisper 转成文字，经过业务逻辑处理后，再把回复文本交给 TTS 合成语音返回。这种链路的延迟主要来自两次 HTTP 请求，如果对实时性要求很高，可以用异步任务拆分：识别完成后先返回文本，合成语音在后台队列中生成，减少客户端等待时间。
在工程化部署时，建议把 API Key 放在服务端环境变量中，不要暴露到前端或移动端。所有音频文件的上传和下载都应通过服务端中转，避免跨域和密钥泄露。对于大文件，可以先做预处理，比如用 ffmpeg 转成 16kHz 单声道 wav，再切分成小于 25MB 的片段。识别结果的拼接要注意标点符号，Whisper 通常会自动添加句读，直接按顺序拼接即可。如果识别结果需要进一步分析，可以选择 verbose_json 格式，拿到每个分段的时间戳，方便做字幕对齐。
常见错误中，401 一般是密钥未设置或已失效，检查环境变量是否被正确读取。413 表示文件体过大，需要压缩或切片。429 说明请求太频繁，建议降低并发并加入重试。还有一个容易被忽略的点：multipart/form-data 请求中不要手动设置 Content-Type，requests 库会自动生成 boundary，手动设置反而会导致服务端解析失败。Whisper 和 TTS 接口都支持官方 Python SDK，但直接使用 requests 能更清楚地理解请求细节，便于排查问题。
总之，OpenAI 的 Whisper 和 TTS 接口为音视频处理提供了低门槛的接入方案，只需几十行代码就能实现语音转文字和文字转语音。理解它们的请求格式、参数含义和错误码，可以避免大部分集成过程中的坑。后续如果需要更精细的控制，还可以结合 prompt 优化、分段策略和服务端缓存，把识别准确率和合成效率进一步提升。
OpenAI APIWhisperTTS修改时间：2026-10-07 05:49:49