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 <檔案> --task <analyze|transcribe|extract>
- 提示:當你被要求分析圖片時,先檢查
gemini指令是否可用,若可用則使用echo "<分析圖片的提示>" | gemini -y -m <gemini.model>指令(從.claude/.ck.json讀取模型:gemini.model)。若gemini指令不可用,則使用python scripts/gemini_batch_process.py --files <檔案> --task analyze指令。 生成內容:python scripts/gemini_batch_process.py --task <generate|generate-video> --prompt "描述"
stdin 支援:你可以透過 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:用於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,600 張)、影片 (MP4/MOV, 6 小時)、PDF (1,000 頁) 大小:內聯 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] 轉錄內容 ...