Gemini 檔案 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 "product-shot"
# 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 | 處理失敗 | 否 |
輸出解讀
上傳回應
Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
- 檔案名稱：在 API 呼叫中使用
- URI：內部 Google Cloud Storage 參考
- 狀態：PROCESSING = 等待，ACTIVE = 就緒
使用 --wait 旗標
Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!
- 腳本會持續輪詢直到狀態變為 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"State: {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
- 支援的格式：圖片、音訊、影片、文件（請參閱上方表格）