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>指令(從.claude/.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 "描述"
標準輸入支援:你可以透過標準輸入直接傳送檔案(會自動偵測 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:用於transcribe|analyze|extract|generate|generate-video任務的 CLI 編排器,能自動解析 API 金鑰、為每個任務挑選合理的預設模型、以內聯方式或 File API 串流檔案,並將結構化輸出(文字/JSON/CSV/markdown 以及生成的資產)儲存,適用於 Imagen 4 和 Veo 工作流程。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 與內聯輸入、TTS 模型、最佳實踐、成本與 Token 計算,以及具體的會議/播客/訪談範例。 |
| 圖片 | references/vision-understanding.md | 視覺能力概述、支援的格式與模型、標題生成/分類/VQA、偵測與分割、OCR 與文件閱讀、多圖片工作流程、結構化 JSON 輸出、Token 成本、最佳實踐,以及常見的產品/螢幕截圖/圖表/場景用例。 |
| 圖像生成 | references/image-generation.md | Imagen 4 與 Gemini 圖像模型概述、generate_images 與 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.6k)、影片(MP4/MOV,6 小時)、PDF(1000 頁) 大小:內聯 20MB,File API 2GB 重要事項:
- 如果要為音訊生成逐字稿,且音訊長度超過 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] 逐字稿內容 ...