如何将FastAPI接收的m4a文件传给OpenAI transcribe接口

核心原因 #

OpenAI的Audio.transcribe接口要求传入带文件名的二进制类文件对象，需通过文件名后缀识别音频格式（如.m4a）。你的所有错误均因未满足该要求：

• 直接传UploadFile：对象缺少接口所需的name属性
• 传bytes/StringIO：bytes无name属性，StringIO是文本流，无法处理二进制音频
• 用file.filename打开：服务器本地不存在该文件，filename仅为客户端传来的标识名

正确解决方案 #

读取UploadFile的二进制内容，用io.BytesIO包装成类文件对象，手动添加name属性（保留原文件名后缀）：

import io
from fastapi import FastAPI, File, UploadFile
import openai

app = FastAPI()

@app.post("/transcribe")
async def transcribe_audio_file(file: UploadFile = File(...)):
    # 读取二进制音频内容
    audio_bytes = await file.read()
    # 用BytesIO包装成类文件对象
    audio_file_like = io.BytesIO(audio_bytes)
    # 手动添加name属性，让OpenAI识别音频格式
    audio_file_like.name = file.filename
    
    # 调用OpenAI转录接口
    transcript_response = openai.Audio.transcribe("whisper-1", audio_file_like)
    return transcript_response

调试思路（针对TypeScript背景） #

• 类比TS：Python的io.BytesIO类似TS中的Blob/File对象，都是二进制数据的容器；UploadFile更像TS中File的网络传输封装，但缺少OpenAI需要的文件标识属性
• 关键验证点：
  • 必须以二进制方式读取音频，禁止用utf-8解码（音频不是文本数据）
  • 类文件对象必须包含name属性，且后缀需匹配音频格式（如.m4a）
  • 无需将文件保存到服务器本地，直接在内存中处理即可

错误细节解释 #

• AttributeError: 'UploadFile' object has no attribute 'name'：OpenAI通过name属性识别格式，但UploadFile的文件名存在filename字段，而非name
• UnicodeDecodeError：音频是二进制文件，强制用utf-8解码会破坏数据，必须用二进制流处理
• FileNotFoundError：file.filename仅为客户端发送的文件名，服务器未生成对应本地文件，直接打开会失败

内容的提问来源于stack exchange，提问作者Brady Dowling