Python 标准库调用 Audio Transcriptions API 的超时与异常处理
内容提要
本文介绍用Python标准库调用语音转写API：先校验文件非空、格式与大小，再以multipart上传并设45秒超时，失败返回码2便于重试。强调密钥安全、编码规范、超时拆分，适用于会议纪要等授权场景，不适用于法律医疗结论。
延伸解读
输入校验：第一道防线
代码在发起网络请求前检查文件是否存在、是否为空、是否超过20MB，并依据扩展名推断MIME类型，仅允许mp3、wav、m4a、mp4。这能拦截明显错误，避免无谓的上传与等待。但mimetypes只是初筛，恶意文件仍可能伪装扩展名，生产环境应补充文件头检测与恶意文件扫描。
超时与失败状态设计
请求设置45秒超时，失败时进程返回码2并输出以TRANSCRIBE_FAILED开头的错误信息，便于任务队列识别与重试。45秒并非最佳值：短音频可缩短，长音频应拆分或转为异步任务，并设置最大重试次数，避免无限等待。
密钥安全与编码规范
密钥通过环境变量OPENAI_API_KEY读取，不硬编码在代码中，也不应记录到日志。音频编码需与扩展名一致，否则可能被接口拒绝。遇到网络代理导致超时，应将任务标记为可重试，而非直接判定失败。
适用边界与工程化方向
该方案适合会议纪要初稿、客服质检、用户明确授权的访谈检索，但不应将未审阅文本直接作为法律、医疗或人事结论。后续可增加说话人分离、术语表、敏感信息打码、临时链接与删除策略，并考虑用--dry-run参数避免CI误传测试音频。
Q&A
如何用 Python 标准库调用 Audio Transcriptions API 上传音频文件？
使用 urllib.request 构造 multipart/form-data 请求，将模型名和音频文件作为表单字段，设置 Authorization 头为 Bearer 密钥，并指定 Content-Type 包含 boundary。示例中模型为 gpt-4o-transcribe，请求发送到 https://api.openai.com/v1/audio/transcriptions。
调用语音转写 API 时应该设置多长的超时时间？
示例中将总请求超时设为 45 秒。但 45 秒并非最佳值：短音频可以设置更短，长音频应采用拆分、异步任务与可取消状态，而不是无止境等待。
语音转写 API 调用失败时如何让任务队列识别并处理？
失败时进程返回码为 2，并以 TRANSCRIBE_FAILED 开头输出错误信息，便于任务队列识别。常见失败包括密钥权限或余额不足、音频编码与扩展名不符、网络代理导致超时，应分别处理为不记录密钥、用音频工具规范化编码、将超时任务标为可重试并设置最大次数。
上传音频前需要做哪些校验？
需要校验文件非空、格式与大小。示例中限制文件不超过 20MB，并只允许 mp3、wav、m4a 或 mp4 格式。mimetypes 只是初筛，生产环境还应检测文件头、扫描恶意文件。
语音转写适合用在哪些场景？不适合哪些场景？
适合会议纪要初稿、客服质检、用户明确授权的访谈检索。不适合把未审阅文本当法律、医疗或人事结论。
如何工程化地使用语音转写 API？
可增加说话人分离、术语表、敏感信息打码、对象存储临时链接和删除策略。五分钟实践：给代码加一个 --dry-run 参数，只打印文件大小与 MIME 类型，确保 CI 不会意外把测试音频传上云。
