Gemini File API
透過可執行的 Python 腳本上傳和管理檔案，以供 Gemini 模型使用。支援圖片、音訊、影片、PDF 及其他檔案類型。
何時使用此技能
當您需要進行以下操作時，請使用此技能：
- 上傳圖片進行多模態分析
- 上傳影片進行內容處理
- 上傳 PDF 進行文件分析
- 上傳音訊進行轉錄或處理
- 預先上傳檔案以進行批次操作
- 檢查檔案處理狀態
- 列出並管理已上傳的檔案
- 將檔案與其他 Gemini 技能（文字、圖片等）搭配使用
可用腳本
scripts/upload.py
目的：將檔案上傳至 Gemini File API
使用時機：
- 上傳任何需要 Gemini 處理的檔案
- 為多模態生成預先準備檔案
- 上傳文件進行分析
- 批次檔案準備
關鍵參數：
| 參數 | 說明 | 範例 |
|---|---|---|
path | 檔案路徑（必要） | image.jpg |
--name, -n | 顯示名稱 | "我的文件" |
--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 "人工智慧研究論文" --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 | 處理失敗 | 否 |
輸出解讀
上傳回應
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"狀態: {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
- 支援的格式：圖片、音訊、影片、文件（請見上方表格）