OpenAI API 支持的文件类型:按接口对照(2026)
「OpenAI API supported file types」到底取决于哪个接口
搜 openai api supported file types,或「OpenAI API 支持的文件类型」,看起来像在找一张总表。其实没有这样一张通吃的表。你能传什么格式,取决于正在调用的是哪一个 API,而且常常还取决于上传时填的 purpose。
一份在 Responses API 里可以作为 input_file 的 .docx 或 .xlsx,如果挂到 Chat Completions 的 file 内容块上,会被拒绝——这条路径只接受 PDF。一份能作为 input_file 送进去的 .csv,并不能交给 File Search 做检索。用 input_image 分析的图片,和文档用的 input_file 不是同一种对象。/v1/audio/transcriptions 的音频还有自己的格式清单,并且限制 25 MB。
本文只写官方 OpenAI API 的格式边界。它不是 ChatGPT 网页上传说明,也不讨论如何把客户端指到兼容 base_url。兼容服务器可以露出类似的 /v1 路径,却拒绝或忽略官方 API 接受的类型;端点形态和切换方法见什么是 OpenAI 兼容 API。如果 base_url 走的是代理,文件上传要在那条链路上单独验证,见 OpenAI API 代理。
文档输入的官方依据是 File inputs 指南。下面的清单按该页,以及 Files、File Search、视觉和转写相关文档整理。格式会变;请求失败时,以当时的报错和官方最新文档为准,而不是以本文为准。
Responses API:较完整的 input_file 清单
在 Responses API 里,文档以 input_file 项传入,可以是:
- Base64 编码的文件数据(
file_data) - 先通过 Files API 上传得到的文件 ID(
file_id) - 外部文件 URL(
file_url)
官方列出的常见 input_file 类别包括:
- PDF:
.pdf - 文本和代码:
.txt、.md、.json、.html、.xml,以及一长串源码和日志扩展名 - 富文档:
.doc、.docx、.rtf、.odt(完整表里还有相关的 Word、Pages、Google Docs 类型) - 演示文稿:
.ppt、.pptx(完整表里还有相关的 PowerPoint、Keynote、Google Slides 类型) - 表格:
.csv、.xls、.xlsx(完整表里还有.tsv、.iif及其他 Excel 扩展名)
扩展名和 MIME 的完整表就在同一页。不要因为「同类格式」能用,就假设一个未出现在表里的扩展名也能用。
每一类文件实际怎么被处理
不同类型的处理方式并不一样:
- PDF:在具备视觉能力的模型(例如
gpt-4o及之后的型号)上,API 会抽取文本,并把页面图像一并送给模型。你可以在input_file上设置detail为auto、low或high,用来控制页面图像的处理方式。省略时默认auto。官方文档写明:GPT-5.6 及更新的模型上,auto等同high;更早的模型上等同low。detail只影响页面图像,PDF 里抽到的文本仍会保留。 - 非 PDF 的文档和文本(例如
.docx、.pptx、.txt和代码文件):只抽取文本。内嵌的图片和图表不会进入模型上下文。如果这些图很重要,先把文件转成 PDF,再把 PDF 作为input_file发送。 - 表格类文件(
.xlsx、.xls、.csv、.tsv、.iif)走单独的增强流程。API 每个工作表最多解析前 1,000 行,并补上模型生成的摘要和表头元数据,而不是把整张表塞进上下文。如果要做复杂汇总或关联,官方文档会建议改用 Hosted Shell 一类工具,或对大规模语料使用 File Search。
Chat Completions:只接受 PDF
Chat Completions 的 file 内容块只接受 .pdf(application/pdf),无论你传的是 file_data 还是 file_id。这条 API 不支持外部 file_url,也不支持 PDF 的 detail 字段。
如果要在 Chat Completions 请求里使用 .docx、.pptx、.xlsx 或文本/代码文件,不要把它当作 file 内容块来传。官方建议是:非 PDF 文件输入改走 Responses API;或者在你自己的程序里读出文本,再作为 text 内容块发送。
「这个格式到底支不支持」测不通,最常见的原因就是:它在 Responses 上合法,在 Chat Completions 上不合法。
Files API 上传:purpose 决定你能传什么
用 Files API 上传,和把文件交给模型,是两步。 创建文件 的 purpose 会限制格式:
user_data:准备作为模型输入的灵活用途。官方文件输入指南写明,上传时可以使用任何受支持的 purpose,但走模型输入这条路径时,应使用user_data。assistants:Assistants API 使用的文件。它们有单独的类型清单,且单文件有 200 万 token 上限,详见 Assistants 工具文档。fine-tune:只接受.jsonl,且必须符合微调要求的 schema。batch:只接受.jsonl,最大 200 MB,且必须符合 Batch 请求格式。默认情况下,Batch 文件会在 30 天后过期;其他 purpose 会一直保留,直到你删除,或自己设置了expires_after。vision:用于视觉微调的图片。evals:评测数据集。
这个端点的存储限制:单个文件最大 512 MB,每个项目最多可存储 2.5 TB 文件。
文件可能上传成功,却在下一步不能用——往往是 purpose 和实际用法对不上。先核对 purpose,再去查格式清单。
示例:用 user_data 上传一份 PDF,再把它的 file_id 传给 Responses 的 input_file。
from openai import OpenAI
client = OpenAI() # 官方 API,不要把这个示例指到兼容 base_url
uploaded = client.files.create(
file=open("briefing.pdf", "rb"),
purpose="user_data",
)
response = client.responses.create(
model="gpt-4.1", # 请换成你项目里实际可用、且具备视觉能力的模型,以便处理 PDF 页面图像
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "总结这份文档,并列出其中的表格。"},
{"type": "input_file", "file_id": uploaded.id},
],
}
],
)
print(response.output_text)示例里的模型 ID 只是占位。请换成你项目里真正能调用的模型;当 PDF 的页面图像有信息量时,优先用具备视觉能力的模型。
File Search 用的不是同一张清单
如果文件很大,或者你希望做检索而不是把整份文档塞进一次请求,应使用向量库上的 File Search。先上传文件,附加到向量库,等到索引状态为 completed,再启用 file_search 工具。
检索格式清单比 Responses 的 input_file 更窄。官方已列出的格式包括 PDF、Word(.doc、.docx)、PowerPoint(.pptx)、纯文本、Markdown、HTML、JSON,以及常见源码文件,如 .py、.js、.ts、.java、.go、.cpp、.c、.cs、.css、.php、.rb、.sh、.tex。对 text/ 类型的 MIME,编码必须是 utf-8、utf-16 或 ascii。
.csv、.jsonl 这类结构化格式不能用于 File Search 检索。这是文档写明的限制,不是你上传写错了。一份能作为 Responses input_file 的 CSV,并不会因此变成可检索的 File Search 文档。
File Search 也不会解析文档里的图片。如果图表重要,请先转成 PDF,再用 input_file 发送(在具备视觉能力的模型上,PDF 页面图像可以被纳入),或用别的方式抽出图表。
图片和音频不是 input_file 文档
图片。 视觉分析走 input_image,不是 input_file。支持的图片格式是 PNG(.png)、JPEG(.jpeg 或 .jpg)、WEBP(.webp)以及非动画 GIF(.gif)。你可以传完整的图片 URL、Base64 data URL,或 Files API 创建的文件 ID。官方限制包括:单次请求负载总计最大 512 MB、最多 1,500 张图片;图片会按 token 计费,还需要能放进模型的上下文窗口。详见图像与视觉指南。
音频。 文件转写走 /v1/audio/transcriptions,这是另一个端点。官方支持的输入格式包括 flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav、webm,文件大小上限 25 MB。当前官方建议,录制完成的原语言转写从 gpt-transcribe 起步。麦克风或流式音频应走 Realtime 转写,不在这份文件上传清单里。详见文件转写指南。
不要指望 WAV 或 PNG 出现在 Responses 的 input_file 文档表里,也不要指望 DOCX 能通过转写端点的校验。
大小限制和常见失败原因
遇到 HTTP 400 或上传被拒时,按这个顺序排查:
- 接口用错。 非 PDF 文档应走 Responses 的
input_file,不要挂在 Chat Completions 的file内容块上。 - purpose 用错。 微调和 Batch 只接受
.jsonl。作为模型输入的文件,上传时应使用user_data。 - 检索格式不匹配。 CSV 和 JSONL 不是 File Search 的类型。
- 超过大小限制。 Files API 单个对象 512 MB、每项目 2.5 TB;Batch 的 JSONL 最大 200 MB;转写文件最大 25 MB;Assistants 文件还有 200 万 token 上限。
- 图丢了。
.pptx或.xlsx里的图表不会被抽取,除非你先转成 PDF,再把 PDF 作为input_file发送。 - 表格被截断。 表格增强流程每个工作表只解析前 1,000 行。
- 兼容或代理 base URL。 第三方
/v1可能只实现了对话,没有实现文件输入,或使用另一套类型清单。先在官方 API 上复现,再怀疑文件本身。
常见问题
Chat Completions API 支持把 DOCX、PPTX 或 CSV 当作 file 内容块吗?
不支持。Chat Completions 的 file 内容块只接受 PDF。这些文档类型请改用 Responses API 的 input_file,或在应用里抽出文本再作为 text 发送。
作为模型输入时,Files API 的 purpose 应该填什么?
应使用 user_data,这也是官方文件输入指南的建议。fine-tune 和 batch 是 .jsonl 流水线,不是通用文档输入。
File Search 能为 CSV 或 JSONL 建索引吗?
不能。官方 File Search 文档和 Assistants 的 File Search FAQ 都写明,.csv、.jsonl 这类结构化格式不支持检索。如果只是想让模型看到表格的一部分,把 CSV 作为 Responses 的 input_file 发送,并记住每个工作表只处理前 1,000 行。
为什么我的 PowerPoint 或表格里的图表不见了?
对非 PDF 文件,Responses API 只抽文本,不会把内嵌图片或图表放进上下文。先转成 PDF,再在具备视觉能力的模型上把 PDF 作为 input_file 发送,图表才有机会被看到。
图片和音频格式,和「支持的文件类型」是同一张表吗?
不是。图片走 input_image(PNG、JPEG、WEBP、非动画 GIF)。音频转写走 /v1/audio/transcriptions,有自己的格式清单和 25 MB 上限。文档 input_file 是第三张清单。
上传前先选定路径
先定接口,再定格式:
- 需要模型在一次请求里阅读文档或表格?用 Responses 的
input_file,对照上文的文档/表格清单。 - 只能用 Chat Completions?附上 PDF,或发送已抽出的文本。不要把 DOCX 或 CSV 当作 file 内容块。
- 要在大规模语料上检索?用 File Search 和它更窄的格式清单,不要用 CSV 或 JSONL。
- 需要页面图像、图表或示意图?优先在具备视觉能力的模型上发送 PDF
input_file。 - 需要转写?走音频转写端点和它 25 MB 的格式清单。
接口选定之后,OpenAI API supported file types 这个问题就会变成一份短清单,而不是一张无处可查的总表。