如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

文件输入

了解如何在 OpenAI API 中将文件用作输入。

文件输入的支持范围取决于 API 端点。Responses API 接受下列类型的文件作为 input_file 输入项。Chat Completions 仅接受 PDF 文件作为 file 类型的内容项。

输入方式 Responses API Chat Completions
Base64 编码的文件数据(file_data) 支持下文列出的文件类型 仅支持 PDF
已上传文件的 ID(file_id) 支持下文列出的文件类型 仅支持 PDF
外部文件 URL(file_url) 支持下文列出的文件类型 不支持

对于非 PDF 文件输入,请使用 Responses API。如果您需要在 Chat Completions 中使用文件里的文本,请先在应用中读取文件,再将其内容作为 text 类型的内容项发送。

工作原理

Responses API 根据文件类型处理 input_file 输入项:

  • PDF 文件:API 会提取文本和页面图像,并将两者一并发送给支持图像输入的模型。
  • 非 PDF 格式的文档和文本文件(例如 .docx、.pptx、.txt 和代码文件):API 只提取文本。
  • 电子表格文件(例如 .xlsx、.csv、.tsv):API 使用专门针对电子表格的增强流程,详见下文。

根据任务需要,您也可以选择以下工具:

  • 要从大文件中检索内容,请使用文件搜索,无需将整个文件直接作为 input_file 传入。
  • 如果任务主要涉及电子表格,并且需要进行聚合、联接、绘图或自定义计算等详细分析,请使用托管式 Shell。

非 PDF 文件中的图像和图表限制

对于非 PDF 文件,Responses API 不会将其中嵌入的图像或图表提取到模型上下文中。

要保留图表和示意图的细节,请先将文件转换为 PDF,再将 PDF 作为 input_file 发送。

电子表格增强流程

对于 .xlsx、.xls、.csv、.tsv 和 .iif 等表格类文件,Responses API 会采用专门针对电子表格的增强流程。

API 不会将整张工作表传给模型,而是从每张工作表的开头最多解析 1,000 行,并添加模型生成的摘要和表头元数据,让模型可以基于更精简的结构化数据进行处理。

PDF 细节级别

在 Responses API 中使用 PDF 输入时,如果需要控制 API 处理页面图像的方式,请将可选字段 detail(位于 input_file 输入项中)设为 auto、low 或 high。如果省略该字段,detail 默认为 auto。对于 GPT-5.6 及后续模型,auto 使用 high。对于更早的模型,则使用 low。要减少输入 Token 用量,请使用 low。如果需要保留更多视觉细节,例如看清信息密集的图表、小号文字或示意图,请使用 high。

detail 设置仅影响 PDF 页面图像的处理方式。从 PDF 中提取的文本仍会包含在模型上下文中。Chat Completions 的文件输入不支持 detail。

以下 Responses API 请求将 detail 设为 high。

{
  "model": "gpt-6.2-astra",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_file",
          "filename": "document.pdf",
          "file_data": "data:application/pdf;base64,...",
          "detail": "high"
        },
        {
          "type": "input_text",
          "text": "Summarize this document."
        }
      ]
    }
  ]
}

支持的文件类型

下表列出了 Responses API 接受的常见文件类型,您可以将这些文件作为 input_file 输入项传入。本页后面列出了完整的扩展名和 MIME 类型。Chat Completions 仅支持 .pdf(application/pdf),这一限制同时适用于 file_data 和 file_id。

类别 常见扩展名
PDF 文件 .pdf
文本和代码 .txt、.md、.json、.html、.xml、代码文件
富文本文档 .doc、.docx、.rtf、.odt
演示文稿 .ppt、.pptx
电子表格 .csv、.xls、.xlsx

文件 URL

您可以通过外部 URL 提供文件输入。

使用外部文件 URL
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6.2-astra",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Analyze the letter and provide a summary of the key points."
                    },
                    {
                        "type": "input_file",
                        "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf"
                    }
                ]
            }
        ]
    }'

上传文件

以下示例先通过 Files API 上传文件,再在发给模型的请求中引用该文件的 ID。

上传文件
curl https://api.openai.com/v1/files \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F purpose="user_data" \
    -F file="@draconomicon.pdf"

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6.2-astra",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"
                    },
                    {
                        "type": "input_text",
                        "text": "What is the first dragon in the book?"
                    }
                ]
            }
        ]
    }'

Base64 编码的文件

您也可以将文件作为 Base64 编码的文件数据发送。

发送 Base64 编码的文件
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6.2-astra",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "filename": "draconomicon.pdf",
                        "file_data": "...base64 encoded PDF bytes here..."
                    },
                    {
                        "type": "input_text",
                        "text": "What is the first dragon in the book?"
                    }
                ]
            }
        ]
    }'

使用注意事项

使用文件输入时,请注意以下限制:

  • Token 用量: 解析 PDF 时,提取的文本和页面图像都会纳入上下文,这可能会增加 Token 用量。在 Responses API 中,您可以将 detail 设为 auto(默认值)、low 或 high,以控制 PDF 页面图像的视觉细节级别。在大规模部署前,请查看定价并评估对 Token 用量的影响。了解定价详情。
  • 文件大小限制: 单个请求可以包含多个文件,但每个文件都必须小于 50 MB,且请求中所有文件的总大小不得超过 50 MB。
  • 要同时解析 PDF 中的文本和页面图像,必须使用支持图像输入的模型。
  • 文件上传用途: 上传文件时,您可以指定任何受支持的用途。对于要作为模型输入传入的文件,请使用 user_data。

支持的文件类型完整列表

此列表适用于 Responses API。Chat Completions 仅支持 .pdf(application/pdf),这一限制同时适用于 file_data 和 file_id。

类别 扩展名 MIME 类型
PDF 文件 PDF 文件(.pdf) application/pdf
电子表格 Excel 工作表(.xla、.xlb、.xlc、.xlm、.xls、.xlsx、.xlt、.xlw) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.ms-excel
电子表格 CSV、TSV、IIF(.csv、.tsv、.iif)、Google 表格 text/csv、application/csv、text/tsv、text/x-iif、application/x-iif、application/vnd.google-apps.spreadsheet
富文本文档 Word、ODT、RTF 文档(.doc、.docx、.dot、.odt、.rtf)、Pages、Google 文档 application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/msword、application/rtf、text/rtf、application/vnd.oasis.opendocument.text、application/vnd.apple.pages、application/vnd.google-apps.document、application/vnd.apple.iwork
演示文稿 PowerPoint 幻灯片(.pot、.ppa、.pps、.ppt、.pptx、.pwz、.wiz)、Keynote、Google 幻灯片 application/vnd.openxmlformats-officedocument.presentationml.presentation、application/vnd.ms-powerpoint、application/vnd.apple.keynote、application/vnd.google-apps.presentation、application/vnd.apple.iwork
文本和代码 文本和代码格式(.asm、.bat、.c、.cc、.conf、.cpp、.css、.cxx、.def、.dic、.eml、.h、.hh、.htm、.html、.ics、.ifb、.in、.js、.json、.ksh、.list、.log、.markdown、.md、.mht、.mhtml、.mime、.mjs、.nws、.pl、.py、.rst、.s、.sql、.srt、.text、.txt、.vcf、.vtt、.xml) application/javascript、application/typescript、text/xml、text/x-shellscript、text/x-rst、text/x-makefile、text/x-lisp、text/x-asm、text/vbscript、text/css、message/rfc822、application/x-sql、application/x-scala、application/x-rust、application/x-powershell、text/x-diff、text/x-patch、application/x-patch、text/plain、text/markdown、text/x-java、text/x-script.python、text/x-python、text/x-c、text/x-c++、text/x-golang、text/html、text/x-php、application/x-php、application/x-httpd-php、application/x-httpd-php-source、text/x-ruby、text/x-sh、text/x-bash、application/x-bash、text/x-zsh、text/x-tex、text/x-csharp、application/json、text/x-typescript、text/javascript、text/x-go、text/x-rust、text/x-scala、text/x-kotlin、text/x-swift、text/x-lua、text/x-r、text/x-R、text/x-julia、text/x-perl、text/x-objectivec、text/x-objectivec++、text/x-erlang、text/x-elixir、text/x-haskell、text/x-clojure、text/x-groovy、text/x-dart、text/x-awk、application/x-awk、text/jsx、text/tsx、text/x-handlebars、text/x-mustache、text/x-ejs、text/x-jinja2、text/x-liquid、text/x-erb、text/x-twig、text/x-pug、text/x-jade、text/x-tmpl、text/x-cmake、text/x-dockerfile、text/x-gradle、text/x-ini、text/x-properties、text/x-protobuf、application/x-protobuf、text/x-sql、text/x-sass、text/x-scss、text/x-less、text/x-hcl、text/x-terraform、application/x-terraform、text/x-toml、application/x-toml、application/graphql、application/x-graphql、text/x-graphql、application/x-ndjson、application/json5、application/x-json5、text/x-yaml、application/toml、application/x-yaml、application/yaml、text/x-astro、text/srt、application/x-subrip、text/x-subrip、text/vtt、text/x-vcard、text/calendar

后续步骤

您可以继续探索以下资源: