Gemini 檔案 API
透過可執行腳本上傳與管理檔案，供 Gemini 模型使用，支援圖片、音訊、影片、PDF 及其他檔案類型。
使用時機
當你需要進行以下操作時使用此技能：
- 上傳圖片進行多模態分析
- 上傳影片進行內容處理
- 上傳 PDF 進行文件分析
- 上傳音訊進行轉寫或處理
- 預先上傳檔案進行批次操作
- 檢查檔案處理狀態
- 列出與管理已上傳的檔案
- 搭配其他 Gemini 技能 (文字、圖片等) 使用檔案
可用腳本
scripts/upload.py
用途：上傳檔案至 Gemini 檔案 API
使用時機：
- 上傳任何檔案供 Gemini 處理
- 準備檔案進行多模態生成
- 上傳文件進行分析
- 批次檔案準備
關鍵參數：
| 參數 | 說明 | 範例 |
|---|---|---|
path | 檔案路徑 (必填) | image.jpg |
--name, -n | 顯示名稱 | "my-document" |
--wait, -w | 等待處理完成 | 旗標 |
輸出：檔案名稱、URI 與狀態資訊
工作流程
工作流程 1：基本檔案上傳
python scripts/upload.py image.jpg
- 適用於：快速上傳、簡單檔案
- 輸出：檔案名稱與 API 使用的 URI
- 狀態：PROCESSING 或 ACTIVE
工作流程 2：上傳並自訂名稱
python scripts/upload.py document.pdf --name "2026 年第四季季報"
- 適用於：組織檔案、追蹤上傳
- 使用時機：原始檔名不夠描述性
- 顯示名稱會出現在檔案列表中
工作流程 3：上傳並等待處理
python scripts/upload.py video.mp4 --wait
- 適用於：大型檔案、影片、音訊
- 等待檔案變為 ACTIVE 狀態
- 使用時機：上傳後需立即使用檔案
工作流程 4：上傳圖片進行分析
# 1. 上傳圖片
python scripts/upload.py photo.png --name "產品照"
# 2. 搭配 gemini-text 進行分析
python skills/gemini-text/scripts/generate.py "描述這張圖片" --image photo.png
- 適用於：圖片分析、生成說明、視覺問答
- 搭配：gemini-text 進行多模態處理
工作流程 5：上傳 PDF 進行內容提取
# 1. 上傳 PDF
python scripts/upload.py research-paper.pdf --name "AI-研究論文" --wait
# 2. 使用 gemini-text 提取內容
python skills/gemini-text/scripts/generate.py "提取此文件的關鍵發現" --image research-paper.pdf
- 適用於：文件處理、內容提取
- 搭配：gemini-text 進行分析
工作流程 6：批量上傳多個檔案
# 1. 上傳多個檔案
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. 使用已上傳檔案建立批次工作 (gemini-batch 技能)
- 適用於：準備檔案進行批次處理
- 搭配：gemini-batch 進行大量操作
工作流程 7：上傳音訊進行轉寫
# 1. 上傳音訊
python scripts/upload.py interview.mp3 --name "訪談-001" --wait
# 2. 使用 gemini-text 處理 (若有轉寫功能)
python skills/gemini-text/scripts/generate.py "轉寫並總結此音訊" --image interview.mp3
- 適用於：音訊處理、轉寫、Podcast 分析
- 搭配：gemini-text 進行音訊分析
工作流程 8：上傳影片進行內容分析
# 1. 上傳影片 (可能需要時間)
python scripts/upload.py product-demo.mp4 --name "示範影片" --wait
# 2. 使用 gemini-text 分析
python skills/gemini-text/scripts/generate.py "分析這支產品示範影片" --image product-demo.mp4
- 適用於：影片分析、內容摘要
- 注意：影片可能需要較長處理時間
參數參考
支援的檔案類型
| 類型 | 副檔名 | 最大大小 | 處理時間 |
|---|---|---|---|
| 圖片 | jpg, jpeg, png, gif, webp | 20MB | 數秒 |
| 音訊 | mp3, wav, aac, flac | 25MB | 數秒至數分鐘 |
| 影片 | mp4, mov, avi, webm | 2GB | 數分鐘至數小時 |
| 文件 | pdf, txt | 50MB | 數秒至數分鐘 |
MIME 類型
腳本根據副檔名自動偵測：
- 圖片：image/jpeg, image/png, image/gif, image/webp
- 音訊：audio/mpeg, audio/wav
- 影片：video/mp4, video/quicktime, video/webm
- 文件：application/pdf, text/plain
檔案狀態
| 狀態 | 說明 | 可供使用 |
|---|---|---|
PROCESSING | 檔案正在分析中 | 否 |
ACTIVE | 檔案已準備就緒 | 是 |
FAILED | 處理失敗 | 否 |
輸出解讀
上傳回應
正在上傳 photo.png...
已上傳：files/abc123...
URI：gs://generation-tmp/abc123...
狀態：PROCESSING
- 檔案名稱：用於 API 呼叫
- URI：Google Cloud Storage 內部參考
- 狀態：PROCESSING = 等待中，ACTIVE = 已就緒
使用 --wait 旗標
正在上傳 video.mp4...
已上傳：files/xyz789...
URI：gs://generation-tmp/xyz789...
狀態：PROCESSING
正在等待處理...
仍在處理中...
檔案已就緒！
- 腳本會持續輪詢直到狀態變為 ACTIVE
- 適用於需要處理的大型檔案
- 影片可能需要數分鐘
使用已上傳的檔案
上傳後，可透過檔案名稱引用：
# 搭配 gemini-text
python skills/gemini-text/scripts/generate.py "分析" --image <上傳檔案路徑>
常見問題
"google-genai 未安裝"
pip install google-genai
"找不到檔案"
- 確認檔案路徑是否正確
- 若相對路徑失敗，請使用絕對路徑
- 檢查副檔名是否為支援的類型
"檔案過大"
- 檢查該檔案類型的尺寸限制
- 盡可能壓縮圖片/影片
- 將大檔案分割成較小部分
"不支援的檔案類型"
- 檢查支援的副檔名
- 若可能，轉換為支援的格式
- 圖片：jpg, png, gif, webp
- 影片：mp4, mov, avi, webm
"處理失敗"
- 檢查檔案是否損毀
- 嘗試重新上傳檔案
- 確認檔案格式有效
- 檢查 API 配額限制
"檔案仍在處理中" (未使用 --wait)
- 檔案狀態為 PROCESSING，而非 ACTIVE
- 使用
--wait旗標或稍後再檢查狀態 - 大型檔案 (尤其是影片) 需要時間
- 處理可能需要數分鐘至數小時
最佳實踐
上傳策略
- 若需立即使用檔案，請使用
--wait - 批次上傳時可跳過
--wait以節省時間 - 使用描述性的
--name便於組織 - 記錄檔案名稱以備後續使用
檔案組織
- 使用一致的命名慣例
- 在名稱中包含日期或版本
- 將相關檔案分組
- 在程式碼中註明檔案名稱
效能提示
- 可平行上傳多個檔案 (分開的程序)
- 為批次操作預先上傳檔案
- 使用前檢查檔案狀態
- 刪除舊檔案以管理儲存空間
錯誤處理
- 上傳後檢查回傳狀態
- 重試失敗的上傳
- 上傳前驗證檔案完整性
- 記錄檔案名稱以供稽核
與其他技能的整合
- gemini-text：多模態分析、文件處理
- gemini-image：根據上傳的參考圖片生成圖片
- gemini-batch：在批次工作中使用上傳的檔案
- gemini-embeddings：從檔案內容建立嵌入向量
檔案生命週期
- 上傳 → PROCESSING → ACTIVE → 用於 API
- 刪除舊檔案以釋放儲存空間
- 檔案可能在一定期限後過期
- 備份重要檔案
相關技能
- gemini-text：透過文字生成分析上傳的檔案
- gemini-image：根據上傳的參考圖片建立圖片
- gemini-batch：在批次處理中使用上傳的檔案
- gemini-embeddings：從檔案內容生成嵌入向量
快速參考
# 基本上傳
python scripts/upload.py image.jpg
# 自訂名稱
python scripts/upload.py document.pdf --name "我的文件"
# 等待處理
python scripts/upload.py video.mp4 --wait
# 多個檔案
for file in *.jpg; do python scripts/upload.py "$file"; done
檔案管理 API
雖然不在腳本中，你也可以透過 Python 管理檔案：
from google import genai
client = genai.Client()
# 列出所有檔案
for file in client.files.list():
print(f"{file.name}: {file.display_name} ({file.state})")
# 取得檔案資訊
file = client.files.get(name="files/abc123...")
print(f"狀態：{file.state}")
# 刪除檔案
client.files.delete(name="files/abc123...")
參考資料
- 取得 API 金鑰：https://aistudio.google.com/apikey
- 文件：https://ai.google.dev/gemini-api/docs/file-upload
- 檔案 API：https://ai.google.dev/gemini-api/docs/files
- 支援格式：圖片、音訊、影片、文件 (請參閱上方表格)