結論先說
- 請求總大小超過 100 MB(PDF 文件超過 50 MB)或同一份媒體文件要反覆提問時,必須改用 Files API:先上載拿到
uri,再在對話裏傳引用,避免每次重複傳幾百兆字節。 - 單文件上限為 2 GB,每個項目總暫存空間上限為 20 GB,文件保留時間為固定的 48 小時:到期由服務端自動清理,不支持手動延期,但可隨時調
delete提前刪除。 - Files API 上載和暫存本身完全免費,只有在你把文件
uri放進模型請求實際推理時,才會按對應多模態規則折算輸入 token 計費。 - 長影片上載後不要立刻發提問:影片需服務端異步預處理,務必先通過
files.get確認文件狀態從PROCESSING變為ACTIVE後再調用模型。 - 谷歌帳號準備與多工具訂閱入口:使用 Gemini、Google AI Studio 與 Antigravity 需具備符合地區與年齡要求的個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含帶 2FA 的 谷歌電郵成品號),跨平台付費訂閱總覽見 AI 會員充值中心。

圖:本站根據 Google Gemini API 文檔:Files API 整理的示意圖
本文根據 Google Gemini API 官方文檔《Files API》《Gemini Developer API Pricing》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 想把幾百 MB 的會議錄像、長播客音頻或上百頁的 PDF 財報餵給 Gemini 模型做總結、提取時間戳的開發者;
- 直接在請求裏內聯塞 Base64 字節流導致體積超限報
400錯誤,需要改用client.files.upload的人; - 關心上載後的文件存多久、收不收存儲費、單文件最大支持多少 GB 的工程師。
一、什麼時候用內聯傳參,什麼時候必須用 Files API
Gemini API 支持直接把小圖片、短音頻放進請求體,也支持通過 Files API 預上載。按官方現行規範對照如下:
| 指標項 | 請求體內聯傳入(Inline) | Files API 預上載(files.upload) |
|---|---|---|
| 觸發體積邊界 | 適合小圖短片段;總請求超 100 MB(PDF 超 50 MB)不可用 | 單個文件最高支持 2 GB,項目總空間 20 GB |
| 多輪對話複用 | 每輪都要重傳原始字節,浪費帶寬且易超時 | 上載一次拿到 myfile.uri,48 小時內無限次引用 |
| 保留與刪除 | 僅當次請求有效,不留存文件對象 | 預設保留 48 小時後自動銷燬,支持主動刪除 |
| 存儲費用 | 無 | 託管存儲免費,僅在送入模型推理時算輸入 token |
另外官方文檔說明,files.upload 返回的文件 URI 在 v1 與 v1beta 接口之間可以互通使用。如果你也在對比 Anthropic 同類接口的配額差異,可參考 Claude API Files API 怎麼用。
二、Python 與 Node.js 上載、輪詢狀態與刪除代碼
1. 上載音頻或 PDF 並直接提問(Python)
安裝官方 google-genai SDK(環境準備見 Gemini API Python 調用教學)後,上載並傳入新一代 Interactions API 的寫法如下:
python
import time
from google import genai
client = genai.Client()
# 1. 上載本地影片、音頻或大 PDF
myfile = client.files.upload(file="lecture.mp4")
# 2. 影片大文件需等待預處理完成變為 ACTIVE
while myfile.state.name == "PROCESSING":
time.sleep(3)
myfile = client.files.get(name=myfile.name)
if myfile.state.name != "ACTIVE":
raise RuntimeError(f"文件處理失敗,當前狀態: {myfile.state.name}")
# 3. 傳入 URI 讓模型分析內容
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{"type": "text", "text": "按章節列出這段影片的關鍵時間點與核心結論"},
{"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
],
)
print(interaction.output_text)
若使用 Node.js / TypeScript 開發,同樣調用 await client.files.upload({ file: "sample.mp3", config: { mimeType: "audio/mpeg" } }),基礎配置可看 Gemini API Node.js 調用教學。需要申請 AI Studio 密鑰但缺少帳號時,可在本站查看 谷歌帳號說明。
2. 列出已上載文件與主動清理
如果項目累計上載快要接近 20 GB 配額上限,或者涉及敏感內部資料不想留在雲端等滿 48 小時,可以用 list 與 delete 立即銷燬:
python
# 查看當前項目暫存的文件列表
for f in client.files.list():
print(f.name, f.uri)
# 分析完畢後主動刪除指定文件
client.files.delete(name=myfile.name)

圖:本站根據 Google Gemini API 文檔:Files API 整理的示意圖
谷歌開發帳號與主力編程訂閱提示:若當前帳號卡在地區不支持、手機核驗或工作空間限制,可在本站選購已配置兩步驗證的 谷歌帳號成品號(即時發貨,質保首登,到手請按指引先登後改密);日常搭配主力模型開發,也可同步了解免境外卡自助兌換的 ChatGPT Plus 與 Claude Pro。
三、長影片與大文檔省費及報錯排查
- 剛傳完影片馬上提問報
FAILED_PRECONDITION或400:基本都是沒等state變成ACTIVE就調了生成接口。加上上面的files.get循環等待即可解決;更多狀態碼含義見 Gemini API 報錯 400、403、429、500 怎麼辦。 - 過了兩天覆用舊
uri報403或404:文件已滿 48 小時被自動清理。業務數據庫裏不要把 Gemini 的file.uri當永久對象存儲地址儲存,應當保留你自己的源文件路徑,捕獲過期錯誤後自動重傳一次刷新uri。 - 同一長影片連續追問十幾次帳單偏高:Files API 只免掉「網盤託管費」,每次把 1 小時影片的
uri放進請求都會重新計算幾十萬影片輸入 token。多輪密集追問同一文件時,建議把上載後的文件配合上下文緩存一起用,計費細則見 Gemini API 價格。
常見問題
問:Files API 裏上載的文件能下載回本地嗎?
答:不能。官方設計 Files API 僅用於向 Gemini 模型喂入多模態上下文,只支持上載(upload)、查元數據(get / list)和刪除(delete),不提供原始文件字節下載接口。
問:不同的 API Key 之間能共享同一個 file.uri 嗎?
答:文件歸屬於創建該 API Key 所在的 Google Cloud / AI Studio 項目(Project)。跨項目的密鑰無法讀取彼此上載的文件 URI,會直接返回權限拒絕錯誤。
問:PDF 裏的圖表和掃描件排版會被識別嗎?
答:通過 Files API 傳入 PDF 時,Gemini 會按原生多模態視覺方式逐頁解析頁面圖像與文字,不僅能讀純文本,還能看懂裏面的折線圖、表格與掃描頁內容。
問:YouTube 公開影片也需要先下載再用 Files API 上載嗎?
答:不需要。如果分析對象是公開的 YouTube 影片連結,Gemini API 支持直接在輸入裏傳入影片網址解析;Files API 主要用於上載本地私有錄屏、內部會議音頻或未公開的超大 PDF 文檔。
問:沒有可用的個人谷歌帳號,或者同時想開其他主流 AI 會員怎麼辦?
答:本站提供即買即發的 谷歌電郵成品號(登入方法見 谷歌帳號購買頁),同時支持支付寶、微信支付與 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服務,實時價格與質保細則以各商品頁說明為準。
相關教學
- Gemini API Python 調用教學:安裝 google-genai SDK、流式輸出、多輪對話與傳圖片
- Gemini API Node.js / JavaScript 調用教學:@google/genai 安裝、流式輸出
- Gemini API 報錯 400、403、429、500、503、504 怎麼辦
- Claude API Files API 怎麼用:上載一次、用 file_id 反覆引用
參考資料
- Google Gemini API 官方文檔:Files API — https://ai.google.dev/gemini-api/docs/files
- Google Gemini API 官方文檔:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 條評論
還沒有評論,來搶沙發~