OpenAI Audio API 怎么用？

官方资料（2026-10-31 核对）：Audio and voice · Transcription overview · File transcription · Realtime transcription · Text to speech · Deprecations · API Pricing

先选工作流：文件、实时字幕还是语音助手？

需要低延迟双向语音、VAD 与打断状态机，请阅读 OpenAI Realtime API 指南；本页聚焦任务选择、转录输入输出和 Audio 迁移边界。

文件转录：用 gpt-transcribe 处理完整录音

把已经录完的音频发送到 /v1/audio/transcriptions。当前支持 mp3、mp4、mpeg、mpga、m4a、wav 和 webm，单文件最高 25 MB。返回 JSON 包含文本和可靠检测到的语言；无法可靠判断时 languages 可能为空数组。

import fs from "node:fs";
import OpenAI from "openai";

const openai = new OpenAI();
const transcript = await openai.audio.transcriptions.create({
  file: fs.createReadStream("meeting.m4a"),
  model: "gpt-transcribe",
  languages: ["zh-cn", "en"],
  prompt: "产品发布复盘会议",
  keywords: ["GPT Pro AI", "WebRTC"]
});

console.log(transcript.text, transcript.languages);

prompt 提供录音主题等自由上下文，keywords 提供可能出现的字面术语，languages 提供预期语言列表。它们只是提示，不应强迫模型输出音频里没有的词；上线前要比较不加提示与加提示的专名准确率和幻觉率。

超过 25 MB 怎么办？

1. 先选择合适的压缩格式，避免为了体积牺牲到无法识别。
2. 仍超限时在停顿或句子边界附近切分，每片不超过 25 MB。
3. 保存原始录音 ID、片段序号、起止时间、哈希与处理状态，重试时保持幂等。
4. 可把上一片尾部的少量真实转录作为下一片上下文，但不要重复拼接造成重词。
5. 合并后对时间顺序、专名、数字和断句做业务评测，不要只看 HTTP 200。

Files API 的通用 512 MB 单文件限制不适用于这里；不同端点限制不能相互替代。文件对象的用途与生命周期另见 OpenAI Files API 指南。

完整文件也能流式返回，但它仍不是实时麦克风

文件已完整存在时，可设置 stream=true，先接收多次 transcript.text.delta，最后接收 transcript.text.done。最终事件包含完整文本，并可包含检测到的语言。客户端应在 done 前把内容标为“处理中”，连接中断时按文件哈希和作业状态重试，避免把半段转录写成最终结果。

普通文本的 SSE 事件处理可参考 OpenAI API Streaming 指南，但音频转录要按专用 transcript 事件判断完成。

实时字幕：用专用 Transcription Session

服务端 WebSocket 连接当前使用 wss://api.openai.com/v1/realtime?intent=transcription，不要在 URL 里加对话模型参数。连接后发送 session.update，将 session type 设为 transcription，并在 audio.input.transcription 中选择 gpt-live-transcribe。浏览器音频优先按官方 WebRTC 流程建连，标准 API Key 仍只放后端。

{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "transcription": { "model": "gpt-live-transcribe" },
        "turn_detection": null
      }
    }
  }
}

当前 gpt-live-transcribe 的 transcription session 不支持 server_vad 或 semantic_vad，应省略 turn_detection 或设为 null，并由应用提交音频轮次。若需要会话式助手自动判断轮次、说话并响应，应使用对话式 GPT-Live/Realtime 工作流，而不是纯字幕 session。

说话人、时间戳与字幕格式：先看弃用风险

旧集成目前仍可用 gpt-4o-transcribe-diarize 获取说话人片段，用 whisper-1 获取 word/segment timestamps 或 SRT/VTT；但这些模型与旧 translations 端点计划于 2027-02-26 停用。它们适合迁移期兼容，不适合今天新建长期依赖。

迁移时不能只改 model 字段：输入协议、事件、语言字段、说话人/时间戳能力和输出格式都可能变化。先双跑代表性音频，再切换生产流量。

文字转语音：旧 Speech API 正在退出

tts-1、tts-1-hd 与 gpt-4o-mini-tts 已弃用，计划于 2027-01-06 从 API 移除。官方推荐迁移到 Realtime API 的 gpt-realtime-2.1-mini；该模型不支持直接填进 /v1/audio/speech，必须改为 Realtime 连接和事件流程。现有集成可以在过渡期继续使用 Speech API，但应立即盘点调用量、格式、voice、instructions、缓存和客户端播放逻辑。

// 仅用于现有 Speech API 集成的迁移盘点；不要作为新长期架构
const audio = await openai.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: "这是一段 AI 生成语音。",
  instructions: "自然、清晰、语速适中",
  response_format: "mp3"
});

现有接口支持 MP3、Opus、AAC、FLAC、WAV 和 PCM；PCM 是 24 kHz、16-bit signed little-endian 原始采样。MP3 适合通用分发，Opus 适合网络传输，WAV/PCM 可减少实时解码开销但体积更大。选择格式时同时测试浏览器/移动端兼容、首帧延迟、带宽和存储成本。

AI 语音披露是上线条件

OpenAI 当前要求清楚告诉最终用户其听到的是 AI 生成声音，而不是人类声音。披露应在播放或通话开始前可见/可听，不能藏在难以找到的条款里。自定义声音还涉及授权、同意录音和来源标识，应单独完成法律与产品评审。

成本、安全与监控

截至 2026-10-31，官方 Pricing 按分钟列出 gpt-transcribe 约 0.0045 美元、gpt-live-transcribe 约 0.017 美元；价格会变化，生产前必须重新核对官方页面，且实际账单还可能包含存储、网络、重试、后处理模型或 Realtime 输出。不要把当前数字硬编码成长期报价。

• 密钥：API Key 只在受信任服务器使用，按 Project/Service Account 最小授权并定期轮换。
• 隐私：上传前取得录音与转录同意，定义原音频、转录、说话人标签和日志的保留/删除策略。
• 输入：验证 MIME、扩展名、真实媒体格式、大小和时长；对不受信任文件设置超时和隔离处理。
• 幂等：用录音哈希 + 工作流版本去重，避免超时重试产生重复转录和重复计费。
• 质量：记录语言、音频条件、提示版本、模型、延迟、错误类型与人工修订，但不要在普通日志保存秘密或完整敏感音频。

用量核算方法见 OpenAI API Usage 指南；密钥和后端代理见 API Key 安全指南。

评测：不要只看词错率

对高风险字段保留人工确认，不让转录文本直接触发不可逆操作。prompt、keywords 与 languages 的每次调整都要版本化并回归评测。

上线前检查清单

1. 已按“完整文件 / 实时输入 / 对话助手 / 语音生成”选择工作流，没有混用端点限制。
2. 新转录从 gpt-transcribe 或 gpt-live-transcribe 开始；旧模型有迁移负责人和截止日期。
3. 25 MB、格式、超时、分片、重试、顺序与幂等均有明确处理。
4. 文件 delta/done 与 Realtime 事件分别实现，半成品不会被标成最终转录。
5. API Key 不出现在浏览器；录音、转录、日志和删除策略完成隐私评审。
6. TTS 用户能够清楚获知声音由 AI 生成；旧 Speech API 的迁移已排期。
7. 代表性音频评测、延迟、失败率、人工修订率和每成功分钟成本已建立基线。

常见问题