早鳥價(12 月 25 日截止),只要持續訂閱就一直鎖定:Go 每月 $10(原價 $20),Plus 用 Opus 5.5 每月只要 $30(原價 $50)立即訂閱 →

Gemini API Office 檔案:直接上傳 docx、xlsx、pptx,切片省成本

如果你每次呼叫 Gemini API 前,都得先把試算表轉成 CSV,這個步驟現在可以省下來了。自 2026 年 11 月 18 日起,Gemini API 能直接處理 Word、Excel 與 PowerPoint 檔案;Google 的說法是,系統可以「只處理並針對」你選定的內容切片付費(Google AI Studio 變更記錄)。

不過,想省成本就必須明確指定切片範圍;否則仍可能處理整個檔案,讀者 @zg0820 也特別提醒了這點。

為什麼舊版 Excel 流程很難用

舊版文件描述的行為,是只會把 XLSX 的第一個工作表讀成 CSV。這代表你得先調整工作表順序,或把活頁簿拆成多個檔案:

「文件現在仍寫著,XLSX 只會讀取第一個工作表,而且格式是 CSV。」— @aitrackerbot

11 月 18 日的更新,改以原生 Office 與 OpenDocument 輸入,搭配提示詞和函式回應中的內容切片,取代這套繞路做法(DocsWatch 分析)。

Gemini API changelog showing the November 18, 2026 Office files and content slicing entry

11 月 18 日更新到底帶來哪些變化

這次更新是在 11 月 5 日加入 PPT、ODP 與 ODS 支援的基礎上,再增加兩項能力:

  1. 直接讀取 Office 與 OpenDocument 檔案。 Word、PowerPoint 和 Excel 不必先轉成 PDF 或純文字,就能直接送入。
  2. 內容切片。 可以選擇頁面範圍、工作表分頁、A1 儲存格範圍、時間區間,或頁面影像、擷取文字、公式與逐字稿等內容層。

切片同時適用於提示詞與 FunctionResponse 部分,因此工具可以只回傳某個工作表範圍,而不是整本活頁簿(AI Index 摘要)。

現在能傳哪些檔案,以及支援哪些模型

Firebase 的輸入需求頁面在 2026 年 11 月 18 日(UTC)更新後,將 Office 支援列為 Gemini 4.x models 的功能(Firebase AI Logic 文件):

系列副檔名MIME 類型
Word.doc、.docx、.dotxapplication/msword、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.openxmlformats-officedocument.wordprocessingml.template
PowerPoint.ppt、.pptxapplication/vnd.ms-powerpoint、application/vnd.openxmlformats-officedocument.presentationml.presentation
Excel.xls、.xlsxapplication/vnd.ms-excel、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
OpenDocument.odt、.odp、.odsapplication/vnd.oasis.opendocument.text、application/vnd.oasis.opendocument.presentation、application/vnd.oasis.opendocument.spreadsheet
基礎支援.pdf、.txtapplication/pdf、text/plain

官方限制如下,使用切片並不會提高上限:

  • 每個檔案上限 50 MB、每個檔案 1,000 頁、每次請求最多 3,000 個文件檔案。
  • 內嵌 base64 資料的請求總大小上限為 20 MB;更大的檔案必須使用 Cloud Storage URL。

另有一項尚未驗證的社群說法,這裡特別分開列出:一名變更記錄讀者表示,Office 檔案可能有約 2,000 頁或投影片的專屬上限(@lawson_ste3476)。Google 尚未記錄這項限制,因此不要以它作為系統設計依據。

Word 與 PowerPoint:指定頁面範圍與內容層

公開的 v1beta/v1alpha Discovery 文件中可以看到 DocumentMetadata,但穩定版 v1 尚未提供(ORIENS schema 報告):

  • startPage:起始頁,從 1 開始計算,包含該頁。
  • endPage:結束頁,從 1 開始計算,包含該頁。
  • contentLayers:PAGE_IMAGE(轉換後的頁面影像;有 metadata 但未指定內容層時,據報告會是預設值)或 PAGE_TEXT(擷取出的文字)。

需要保留版面、投影片設計或處理掃描頁面時,選 PAGE_IMAGE;要搜尋合約等文字內容,則選 PAGE_TEXT。Firebase 說明了背後的計算方式:PDF 會視為影像處理,每頁算一張影像;若影像的長寬都不超過 384 px,每張會計 258 tokens(Firebase AI Logic 文件)。

Excel:工作表、儲存格範圍與三種內容層

根據 Discovery schema,SpreadsheetMetadata 會附加在透過 inline_data 或 file_data 提供的檔案部分上,並可放在輸入的 Part 或 FunctionResponsePart 中(ORIENS schema 報告):

  • sheetIndex:按照活頁簿順序編號,從 1 開始。Discovery v1beta 文字說明,省略時會選取所有工作表;Python 和 JavaScript SDK 的文字則表示會選第一個工作表。實務上每次都應明確設定。
  • visibleCells:例如 A1:G35 這樣的 A1 範圍;省略時,會選取指定工作表中實際有內容的區域。
  • contentLayers:DATA(值、合併儲存格、格式)、FORMULAS(公式與計算結果)、VISUAL(轉換後的影像)。據報告,預設值為 [DATA, FORMULAS]。

進行稽核時使用 DATA 搭配 FORMULAS;需要檢查版面或合併儲存格脈絡時,再加入 VISUAL;若只是查詢單一項目,就把 visibleCells 範圍縮到最小。

只送出需要的切片:Python REST 範例

以下欄位名稱對應 Discovery revision 20261116;目前格式仍屬 beta,穩定版 v1 尚未提供,因此正式上線前請先對照你安裝的 SDK 版本確認。

python
import os
from google import genai
import requests

client = genai.Client()  # reads GEMINI_API_KEY
workbook = client.files.upload(
    file="q3_revenue.xlsx",
    config={"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
)

api_key = os.environ["GEMINI_API_KEY"]
url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key={api_key}"
payload = {
    "contents": [{
        "parts": [
            {
                "fileData": {
                    "fileUri": workbook.uri,
                    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                },
                "spreadsheetMetadata": {
                    "sheetIndex": 2,
                    "visibleCells": "A1:G35",
                    "contentLayers": ["DATA", "FORMULAS"],
                },
            },
            {"text": "Summarize revenue variance in this range using computed values."},
        ]
    }]
}
r = requests.post(url, json=payload, timeout=120)
r.raise_for_status()
print(r.json()["candidates"][0]["content"]["parts"][0]["text"])

處理 Word 時,將 "documentMetadata": {"startPage": 12, "endPage": 18, "contentLayers": ["PAGE_TEXT"]} 放入請求,並改用 .docx 的 MIME 類型即可。PowerPoint 也是相同的 documentMetadata 格式,搭配 .pptx MIME 類型和投影片頁碼。

計費怎麼算:什麼時候切片真的能省錢

變更記錄或 Firebase 定價說明中,沒有獨立的切片 SKU;實際節省的金額,就是少處理的輸入 tokens,並按照標準費率計算。變更記錄列出的 gemini-4-hydrogen 價格是每 1M input tokens $1.50。

以下用一份 200 頁的報告示範,假設實際只需要第 12–18 頁;其中每頁文字 800 tokens 是本例假設值,不是官方公布的費率:

  • 切片前:200 頁以影像處理,每頁至少 258 tokens x 200 = 51,600 input tokens。費用:51,600 / 1,000,000 x $1.50 = $0.0774。
  • 切片後:7 頁擷取文字,每頁假設 800 tokens,共 5,600 input tokens。費用:5,600 / 1,000,000 x $1.50 = $0.0084。
  • 節省:這次請求的輸入成本約減少 89%,尚未計入輸出 tokens。實際應以你測得的頁面密度替換假設值。

建議直接用自己的活頁簿測試範圍大小:切得太碎、發出大量小型請求,總成本可能反而高於一次選好範圍的請求(@zg0820)。

讓流程穩定運作:驗證與遷移清單

檔案成功上傳,不代表內容就一定解析成功。每條處理流程都應逐項驗證:

  1. 確認解析結果。 要求模型回傳資料列數、工作表名稱或頁數,再與來源檔案比對。
  2. 每個選擇器都要明確設定。 包括 sheetIndex、visibleCells 或頁面範圍,以及 contentLayers。
  3. 根據問題選擇內容層。 圖表與版面需要 VISUAL 或 PAGE_IMAGE;稽核需要 DATA 搭配 FORMULAS;搜尋則使用 PAGE_TEXT。
  4. 在 staging 測試超出範圍的行為。 Schema 沒有說明輸入無效頁碼或範圍時,系統會報錯、限制到有效範圍,還是直接回傳空內容。
  5. 留意上傳上限。 60 MB 的檔案仍會因超過 50 MB 上限而失敗;超過 20 MB 的內嵌資料請改用 Cloud Storage URL。
  6. 按照這個順序遷移。 Excel 拆分器改用 sheetIndex 加 visibleCells;報告點陣化流程改用頁面範圍搭配 PAGE_TEXT(只有需要版面時才使用 PAGE_IMAGE);整份檔案的工具回傳則改成切片後的函式回應。

引用的來源沒有交代以下情況:隱藏列、合併儲存格、圖表、嵌入圖片,以及受密碼保護、啟用巨集或損毀檔案的處理方式,都未在上述切片公告或 Firebase 輸入需求頁面中說明。請使用自己的範本逐一驗證。

常見問題

函式回應中的內容也能切片嗎?

可以。工具可以回傳檔案 URI 搭配 SpreadsheetMetadata 或 DocumentMetadata,讓模型只看到指定摘錄,特別適合代理型文件工作流程。

哪個 API 版本支援切片?

目前在 Discovery revision 20261116 的 v1beta 和 v1alpha 中觀察到這項功能,穩定版 v1 尚未提供。正式環境前請固定版本,並在目標模型上測試。

為什麼 Gemini 說它看不到我上傳的檔案?

先對照上方的表格與限制,檢查 MIME 類型、檔案大小和明確指定的選擇器;接著要求模型回傳工作表名稱或頁數,確認檔案是否成功解析。

延伸閱讀:Gemini 4 Carbon vs Hydrogen API guide,了解如何選擇 Office 流程背後使用的模型。