Gemini File API
透過可執行的腳本上傳與管理檔案，以便與 Gemini 模型搭配使用，支援圖片、音訊、影片、PDF 及其他檔案類型。
何時使用此技能
當您需要下列操作時，可使用此技能：
- 上傳圖片進行多模態分析
- 上傳影片進行內容處理
- 上傳 PDF 進行文件分析
- 上傳音訊進行轉錄或處理
- 預先上傳檔案以進行批次作業
- 檢查檔案處理狀態
- 列出並管理已上傳的檔案
- 與其他 Gemini 技能（文字、圖片等）搭配使用
可用腳本
scripts/upload.py
目的：將檔案上傳至 Gemini File 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
- 最佳用途：音訊處理、轉錄、播客分析
- 結合技能：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以便組織 - 記錄檔案名稱以供後續使用
檔案組織
- 使用一致的命名慣例
- 在名稱中包含日期或版本
- 將相關檔案分組在一起
- 在程式碼中記錄檔案名稱
效能提示
- 可平行上傳多個檔案（分開處理）
- 預先上傳批次作業所需的檔案
- 在 API 呼叫前檢查檔案狀態
- 刪除舊檔案以節省儲存空間
錯誤處理
- 上傳後檢查回傳狀態
- 重試失敗的上傳
- 上傳前確認檔案完整性
- 記錄檔案名稱以供稽核
與其他技能的整合
- 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
- File API：https://ai.google.dev/gemini-api/docs/files
- 支援格式：圖片、音訊、影片、文件（請參閱上方表格）