如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 檔案:使用具備視覺能力的模型(例如 gpt-4o 及後續模型)時,API 會擷取文字和頁面影像,並將兩者一併傳給模型。
  • 非 PDF 文件和文字檔(例如 .docx、.pptx、.txt 和程式碼檔案):API 只會擷取文字。
  • 試算表檔案(例如 .xlsx、.csv、.tsv):API 會執行試算表專用的資料擴充流程(詳見下文)。

視任務需求,也可以使用下列工具:

  • 如要從大型檔案中檢索資料,請使用檔案搜尋,無須直接將整個檔案當作 input_file 傳送。
  • 如果任務主要涉及試算表,且需要進行彙總、資料表聯結、繪製圖表或自訂計算等深入分析,請使用託管 Shell 環境。

非 PDF 檔案的影像與圖表限制

Responses API 不會擷取非 PDF 檔案中的內嵌影像或圖表,因此模型的上下文不會包含這些內容。

如要保留圖表和示意圖的細節,請先將檔案轉換為 PDF,再將 PDF 當作 input_file 傳送。

試算表資料擴充的運作方式

對於試算表類型的檔案(例如 .xlsx、.xls、.csv、.tsv 和 .iif),Responses API 會使用試算表專用的資料擴充流程。

API 不會將整張工作表傳給模型,而是從每張工作表的第一列開始解析,最多解析 1,000 列,再加入由模型產生的摘要和欄位標題中繼資料。這樣一來,模型就能使用精簡且結構化的資料進行分析。

PDF 的細節層級

在 Responses API 中使用 PDF 作為輸入時,可以設定選用欄位 detail。在 input_file 項目中將此欄位設為 auto、low 或 high,即可控制 API 處理頁面影像的方式。若省略 detail,預設值為 auto。對於 GPT-5.6 及後續模型,auto 會使用 high;對於較早的模型,則會使用 low。如要減少輸入 Token 用量,請使用 low。如需辨識資訊密集的圖表、細小文字或示意圖等視覺細節,請使用 high。

detail 設定只會影響 PDF 頁面影像的處理方式。從 PDF 擷取的文字仍會納入模型的上下文。Chat Completions 的檔案輸入不支援 detail。

以下是明確指定高細節層級的 Responses API 請求主體最簡範例:

{
  "model": "gpt-4.1",
  "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-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-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-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 時同時處理文字和頁面影像,必須使用具備視覺能力的模型,例如 gpt-4o 及後續模型。
  • 檔案上傳用途: 上傳檔案時,可以指定任何支援的用途。如果打算將檔案作為模型輸入,請使用 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

後續步驟

接下來,可以依需求探索下列資源: