多模態 AI 工具集 是做什麼的?
使用 Google Gemini 多模態 API 處理音訊、圖片、影片、文件,以及生成圖片與影片。
設定
export GEMINI_API_KEY="your-key" # 從 https://aistudio.google.com/apikey 取得
pip install google-genai python-dotenv pillow
API 金鑰輪換(可選)
若用量較高或頻繁遇到速率限制,可設定多組 API 金鑰:
# 主要金鑰(必填)
export GEMINI_API_KEY="key1"
# 額外金鑰用於輪換(可選)
export GEMINI_API_KEY_2="key2"
export GEMINI_API_KEY_3="key3"
或在 .env 檔案中設定:
GEMINI_API_KEY=key1
GEMINI_API_KEY_2=key2
GEMINI_API_KEY_3=key3
功能特色:
- 遇到速率限制錯誤(429/RESOURCE_EXHAUSTED)時自動輪換金鑰
- 每組金鑰被限速後有 60 秒冷卻時間
- 使用
--verbose標記可記錄輪換事件 - 向後相容:單一組金鑰仍可正常運作
快速開始
驗證設定:python scripts/check_setup.py
分析媒體:python scripts/gemini_batch_process.py --files <file> --task <analyze|transcribe|extract>
- 提示:當您需要分析圖片時,請先檢查
gemini指令是否可用,若可用則使用echo "<圖片分析提示>" | gemini -y -m <gemini.model>指令(模型名稱從.opencode/.ck.json的gemini.model欄位讀取)。若gemini指令不可用,則使用python scripts/gemini_batch_process.py --files <file> --task analyze指令。 生成內容:python scripts/gemini_batch_process.py --task <generate|generate-video> --prompt "描述"
標準輸入支援:可直接透過 stdin 傳入檔案(自動偵測 PNG/JPG/PDF/WAV/MP3 格式)。
cat image.png | python scripts/gemini_batch_process.py --task analyze --prompt "描述這張圖片"python scripts/gemini_batch_process.py --files image.png --task analyze(傳統方式)
模型
- 圖片生成:
imagen-4.0-generate-001(標準)、imagen-4.0-ultra-generate-001(精細)、imagen-4.0-fast-generate-001(快速) - 影片生成:
veo-3.1-generate-preview(8 秒片段,含音訊) - 分析:
gemini-2.5-flash(推薦)、gemini-2.5-pro(進階)
指令碼
gemini_batch_process.py:CLI 編排器,支援transcribe|analyze|extract|generate|generate-video任務,自動解析 API 金鑰、依任務挑選合理的預設模型、串流內嵌檔案或使用 File API,並將結構化輸出(文字/JSON/CSV/Markdown 以及生成的圖片/影片素材)儲存。media_optimizer.py:基於 ffmpeg/Pillow 的前置處理工具,可壓縮、調整尺寸、轉換音訊/圖片/影片輸入,強制目標大小/位元率,將長片段分割為小時級區塊,並批次處理目錄中的媒體,確保符合 Gemini 的大小限制。document_converter.py:由 Gemini 驅動的文件轉換器,可上傳 PDF/圖片/Office 文件,套用保留 Markdown 格式的提示詞,批次處理多個檔案,在docs/assets目錄下自動命名輸出檔案,並支援 CLI 參數指定模型、提示詞、自動命名與詳細記錄。check_setup.py:互動式就緒檢查工具,驗證目錄結構、集中式環境變數解析器、必要的 Python 依賴套件以及 GEMINI_API_KEY 的可用性與格式,接著執行一次 Gemini API 即時呼叫,並在偵測到問題時顯示修復指引。
使用 --help 查看各指令的選項說明。
參考資料
載入以下文件以取得詳細指引:
| 主題 | 檔案 | 說明 |
|---|---|---|
| 音樂 | references/music-generation.md | Lyria RealTime API 用於背景音樂生成、風格提示、即時控制,以及與影片製作的整合。 |
| 音訊 | references/audio-processing.md | 音訊格式與限制、轉錄(時間戳、說話者、段落)、非語音分析、File API vs 內嵌輸入、TTS 模型、最佳實踐、成本與 Token 計算,以及具體的會議/播客/訪談處理方法。 |
| 圖片 | references/vision-understanding.md | 視覺能力概覽、支援格式與模型、標題生成/分類/VQA、物體偵測與分割、OCR 與文件閱讀、多圖片工作流程、結構化 JSON 輸出、Token 成本、最佳實踐,以及常見的產品/螢幕截圖/圖表/場景使用案例。 |
| 圖片生成 | references/image-generation.md | Imagen 4 與 Gemini 圖片模型概覽、generate_images vs generate_content API、長寬比與成本、文字/圖片/兩者混合模式、編輯與組合、風格與品質控制、安全設定、最佳實踐、疑難排解,以及常見的行銷/概念藝術/UI 應用場景。 |
| 影片 | references/video-analysis.md | 影片分析能力與支援格式、模型/上下文選擇、本機/內嵌/YouTube 輸入、裁剪與 FPS 控制、多影片比較、時間軸問答與場景偵測、搭配視覺上下文的轉錄、Token 與成本指引,以及最佳化與最佳實踐模式。 |
| 影片生成 | references/video-generation.md | Veo 模型矩陣、文字轉影片與圖片轉影片快速入門、多參考與擴展流程、攝影機與時間控制、設定(解析度、長寬比、音訊、安全)、提示詞設計模式、效能提示、限制、疑難排解,以及成本估算。 |
限制
格式:音訊(WAV/MP3/AAC,最長 9.5 小時)、圖片(PNG/JPEG/WEBP,最多 3,600 張)、影片(MP4/MOV,最長 6 小時)、PDF(最多 1,000 頁) 大小:內嵌方式最大 20 MB,File API 最大 2 GB 重要事項:
- 若要為音訊產生逐字稿,若音訊長度超過 15 分鐘,由於 Gemini API 回應的輸出 Token 限制,逐字稿常會被截斷。為取得完整逐字稿,需將音訊分割成較小的區塊(每個區塊最長 15 分鐘),分別轉錄每個區段,再合併完整逐字稿。
- 若要為影片產生逐字稿,若影片長度超過 15 分鐘,請使用 ffmpeg 從影片中擷取音訊,將音訊截斷為 15 分鐘長度,轉錄所有音訊區段,再將所有逐字稿合併為一份。 轉錄輸出要求:
- 格式:Markdown
- 中繼資料:時長、檔案大小、產生日期、描述、檔案名稱、涵蓋主題等。
- 段落:起訖時間(例如 00:00-00:15)、音訊區塊名稱、逐字稿、狀態等。
- 逐字稿格式:
[HH:MM:SS -> HH:MM:SS] 逐字稿內容 [HH:MM:SS -> HH:MM:SS] 逐字稿內容 ...