gemini-image 0.1.0__tar.gz

gemini_image-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# 瀏覽器
+HEADLESS=false
+PROFILE_DIR=profiles
+GEMINI_URL=https://gemini.google.com/app
+
+# Stealth
+STEALTH_LANGUAGE=zh-TW,zh,en-US,en
+STEALTH_TIMEZONE=Asia/Taipei
+
+# 服務
+HOST=0.0.0.0
+PORT=8070
+QUEUE_MAX_SIZE=10
+DEFAULT_TIMEOUT=180
+
+# 心跳
+HEARTBEAT_INTERVAL=300

gemini_image-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gemini_image-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

gemini_image-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.env
+profiles/
+*.egg-info/
+dist/
+.venv/
+logs/
+bin/

gemini_image-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: gemini-image
+Version: 0.1.0
+Summary: Gemini 圖片生成 API 服務
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.49
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

gemini_image-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Gemini Image
+
+使用 Playwright 自動化 Gemini 網頁版生成含繁體中文文字的圖片。提供 **CLI 工具**和 **HTTP API** 兩種使用方式。
+
+自動移除 Gemini 可見水印（使用 [GeminiWatermarkTool](https://github.com/allenk/GeminiWatermarkTool)）。
+
+## 安裝
+
+### 一行安裝（推薦）
+
+```bash
+uv tool install git+https://github.com/yazelin/gemini-image.git && playwright install chromium
+```
+
+或用 pipx：
+
+```bash
+pipx install git+https://github.com/yazelin/gemini-image.git && playwright install chromium
+```
+
+安裝完成後 `gemini-image` 指令全域可用。
+
+### 從原始碼安裝
+
+```bash
+git clone https://github.com/yazelin/gemini-image.git
+cd gemini-image
+bash scripts/setup.sh
+```
+
+## 首次登入 Google
+
+首次使用需手動登入一次，之後 session 自動持久化：
+
+```bash
+gemini-image login
+```
+
+在彈出的瀏覽器中登入 Google 帳號，確認進入 Gemini 頁面，按 Enter 關閉。
+
+## 使用方式
+
+### CLI 工具
+
+```bash
+# 生成圖片
+gemini-image generate "A cute cat sitting on a windowsill" -o cat.png
+
+# 生成圖片 + 自動去水印
+gemini-image generate "A poster with text '歡迎光臨'" -o poster.png --no-watermark
+
+# 查看說明
+gemini-image --help
+gemini-image generate --help
+```
+
+### HTTP API
+
+```bash
+# 啟動 API 服務
+gemini-image serve
+
+# 或直接用 uvicorn
+uv run uvicorn src.main:app --host 0.0.0.0 --port 8070
+```
+
+#### POST /api/generate
+
+```bash
+curl -X POST http://localhost:8070/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "A poster with text 歡迎來到台北, modern design"}'
+```
+
+回傳：
+
+```json
+{
+  "success": true,
+  "images": ["data:image/png;base64,..."],
+  "prompt": "...",
+  "elapsed_seconds": 27.8
+}
+```
+
+API 模式會自動去水印。
+
+#### GET /api/health
+
+```json
+{
+  "status": "ok",
+  "browser_alive": true,
+  "logged_in": true,
+  "queue_size": 0,
+  "uptime_seconds": 3600
+}
+```
+
+#### POST /api/new-chat
+
+手動重置 Gemini 對話（除錯用）。
+
+### systemd 服務部署
+
+```bash
+# 確認 .env 中 HEADLESS=true
+sudo bash scripts/install-service.sh
+```
+
+## AI Agent 整合
+
+### 作為 MCP 工具
+
+在你的 AI agent 中呼叫 CLI：
+
+```bash
+gemini-image generate "detailed prompt here" -o /path/to/output.png --no-watermark
+```
+
+### 作為 HTTP API
+
+```python
+import httpx
+resp = httpx.post("http://localhost:8070/api/generate", json={"prompt": "..."}, timeout=200)
+data = resp.json()
+if data["success"]:
+    images = data["images"]  # base64 list
+```
+
+## 環境變數
+
+| 變數 | 說明 | 預設 |
+|------|------|------|
+| `HEADLESS` | 無頭模式（首次登入設 false） | `false` |
+| `PROFILE_DIR` | 瀏覽器 session 目錄 | `profiles` |
+| `GEMINI_URL` | Gemini 網址 | `https://gemini.google.com/app` |
+| `PORT` | API 服務埠 | `8070` |
+| `DEFAULT_TIMEOUT` | 生圖超時秒數 | `180` |
+| `QUEUE_MAX_SIZE` | 最大排隊數 | `10` |
+| `HEARTBEAT_INTERVAL` | 心跳檢查間隔秒數 | `300` |
+
+## 去水印
+
+使用 [GeminiWatermarkTool](https://github.com/allenk/GeminiWatermarkTool)（反向 Alpha 混合 + AI 降噪）移除 Gemini 右下角可見水印。
+
+- **首次使用時自動下載**對應平台的 binary（Windows/Linux/macOS）
+- 快取位置：`~/.gemini-image/bin/`
+- API 模式：自動去水印
+- CLI 模式：加 `--no-watermark` 參數
+
+注意：不可見的 SynthID 浮水印無法移除。
+
+## 已知限制
+
+- 一次只能處理一個生圖請求（其他排隊）
+- Google 登入過期需手動重新登入（`gemini-image login`）
+- Gemini 改版可能導致 DOM selector 失效，需手動更新 `src/selectors.py`
+- 違反 Google 服務條款，帳號有被封風險
+- 生圖耗時約 20-60 秒，視 Gemini 伺服器負載而定
+
+## 開發
+
+```bash
+uv sync --extra dev
+uv run pytest -v
+```

gemini_image-0.1.0/docs/design.md

@@ -0,0 +1,243 @@
+# Gemini Image API 設計規格
+
+## 概述
+
+獨立的圖片生成 API 服務，使用 Playwright 瀏覽器自動化操作 Gemini 網頁版（Nano Banana / Gemini 3 Pro Image），生成含繁體中文文字的圖片，供多個內部系統透過 HTTP API 呼叫。
+
+## 需求
+
+- **使用場景**：多個內部系統共用（CTOS-Lite、其他專案）
+- **併發量**：低量（< 10 張/小時）
+- **圖片用途**：混合（社群圖文、文件插圖等），由呼叫端決定 prompt
+- **認證**：無認證，內網部署不對外暴露
+- **回傳格式**：Base64 JSON
+- **選擇 Gemini 的原因**：唯一能正確渲染繁體中文文字的圖片生成模型
+
+## 技術棧
+
+| 元件 | 技術 |
+|------|------|
+| API 框架 | Python FastAPI |
+| 瀏覽器自動化 | Playwright（Chromium） |
+| 套件管理 | uv + hatchling |
+| 部署 | systemd 服務 |
+
+## 目錄結構
+
+```
+gemini-image-api/
+├── src/
+│   ├── main.py              # FastAPI 入口、lifespan 管理
+│   ├── config.py            # 環境變數設定
+│   ├── browser.py           # Playwright 瀏覽器管理（啟動、stealth、session）
+│   ├── gemini.py            # Gemini 頁面互動（輸入、等待、擷取圖片）
+│   ├── selectors.py         # DOM CSS selector 集中管理
+│   └── queue.py             # asyncio 請求佇列
+├── profiles/                # 瀏覽器 session 持久化目錄
+├── pyproject.toml
+├── .env.example
+└── Dockerfile               # 可選
+```
+
+## 架構
+
+```
+POST /api/generate {"prompt": "..."}
+    ↓
+asyncio.Queue（排隊，maxsize=10）
+    ↓
+單一 Worker
+    ↓
+browser.py — 持久化 Chromium context（已登入 Gemini）
+    ↓
+gemini.py — 輸入 prompt → 送出 → 等待圖片生成 → 從 DOM 擷取
+    ↓
+回傳 {"images": ["data:image/png;base64,..."]}
+```
+
+## 瀏覽器管理（browser.py）
+
+### 啟動策略
+
+- 使用 `chromium.launch_persistent_context()` 將 Google 登入狀態存在 `profiles/` 目錄
+- 首次啟動：`HEADLESS=false`，手動登入 Google，之後改 `HEADLESS=true`
+- 服務啟動時自動開瀏覽器，服務關閉時自動清理
+
+### Stealth 防偵測
+
+參考 Project Golem 的 BrowserLauncher：
+
+- 偽裝 `navigator.webdriver` 為 false
+- 設定真實 User-Agent、語言（zh-TW）、時區（Asia/Taipei）
+- 偽裝 WebGL vendor/renderer
+- 擋掉不必要的資源（字體、追蹤腳本）減少流量
+
+### Session 保活
+
+- 定時心跳（每 5 分鐘檢查頁面是否還活著）
+- 偵測到 Google 登入過期 → log 警告，API 回傳 503
+- 不自動重新登入（安全考量，需人工介入）
+
+### 頁面管理
+
+- 單一分頁複用，每次生圖完點擊「新對話」重置
+- 避免開太多分頁導致記憶體膨脹
+
+## Gemini 頁面互動（gemini.py）
+
+### 互動流程
+
+1. 確認頁面就緒（輸入框可用）
+2. 在輸入框輸入 prompt
+3. 按 Enter 或點擊送出按鈕
+4. 等待回應完成（偵測「停止生成」按鈕消失）
+5. 從回應區域擷取圖片元素
+6. 將圖片轉為 base64
+7. 點擊「新對話」重置狀態
+
+### 圖片擷取策略
+
+Gemini 生成的圖片可能以幾種形式出現：
+
+- `<img src="data:image/...">`（直接 base64）
+- `<img src="https://...">`（遠端 URL）
+- `<canvas>` 元素
+
+統一用 `page.evaluate()` 在瀏覽器端把圖片繪製到 canvas → 匯出 base64，不管原始格式都能處理。
+
+### 容錯機制
+
+| 情況 | 處理 |
+|------|------|
+| Gemini 拒絕生圖（內容審查） | 偵測拒絕訊息文字，回傳 `error: "content_blocked"` |
+| 回應超時（預設 60 秒） | 回傳 408 `error: "timeout"` |
+| DOM 結構變了找不到元素 | 回傳 502 `error: "browser_error"` + 詳細 log |
+| Gemini 回了文字沒有圖 | 回傳 `error: "no_image"`，附帶 Gemini 的文字回應 |
+
+## DOM Selector 管理（selectors.py）
+
+所有 CSS selector 集中管理，Gemini 改版時只需更新此檔案：
+
+```python
+SELECTORS = {
+    "input": "div[contenteditable='true']",
+    "send": "button[aria-label='Send']",
+    "response": "div.response-container",
+    "images": "img.generated-image",
+    "new_chat": "button[aria-label='New chat']",
+    "stop": "button[aria-label='Stop']",
+}
+```
+
+注意：以上為示意值，實際 selector 需在開發時對照真實 Gemini DOM 確認。
+
+## 請求佇列（queue.py）
+
+- `asyncio.Queue(maxsize=10)` 排隊緩衝
+- 超過 10 個排隊 → 429 Too Many Requests
+- 單一 worker 循環取任務 → 操作瀏覽器 → 回傳結果
+- 每個請求帶 timeout，佇列等待超過 timeout 回 408
+
+## API 介面
+
+### POST /api/generate
+
+```json
+// Request
+{
+    "prompt": "畫一張台北101的夜景海報，標題寫「歡迎來到台北」",
+    "timeout": 60
+}
+
+// Response 成功
+{
+    "success": true,
+    "images": ["data:image/png;base64,..."],
+    "prompt": "畫一張...",
+    "elapsed_seconds": 12.3
+}
+
+// Response 失敗
+{
+    "success": false,
+    "error": "content_blocked",
+    "message": "Gemini 拒絕生成此內容"
+}
+```
+
+### GET /api/health
+
+```json
+{
+    "status": "ok",
+    "browser_alive": true,
+    "logged_in": true,
+    "queue_size": 2,
+    "uptime_seconds": 3600
+}
+```
+
+### POST /api/new-chat
+
+手動重置 Gemini 對話（除錯用），回傳 `{"success": true}`。
+
+## 環境變數
+
+```bash
+# 瀏覽器
+HEADLESS=false              # 首次登入設 false，之後改 true
+PROFILE_DIR=profiles        # 瀏覽器 session 目錄
+GEMINI_URL=https://gemini.google.com/app
+
+# Stealth
+STEALTH_LANGUAGE=zh-TW,zh,en-US,en
+STEALTH_TIMEZONE=Asia/Taipei
+
+# 服務
+HOST=0.0.0.0
+PORT=8070
+QUEUE_MAX_SIZE=10
+DEFAULT_TIMEOUT=60
+
+# 心跳
+HEARTBEAT_INTERVAL=300      # 秒
+```
+
+## 部署
+
+### 首次啟動（手動登入）
+
+```bash
+cd ~/SDD/gemini-image-api
+uv sync
+playwright install chromium
+HEADLESS=false uv run uvicorn src.main:app --port 8070
+# 在彈出的瀏覽器中手動登入 Google
+# 登入完成後關閉服務，修改 .env 中 HEADLESS=true
+```
+
+### 正式運行
+
+```bash
+uv run uvicorn src.main:app --host 0.0.0.0 --port 8070
+```
+
+### systemd 服務
+
+提供 `scripts/install-service.sh`，跟 CTOS-Lite 同樣模式。
+
+### 部署位置
+
+```
+~/SDD/gemini-image-api/     # 獨立 repo，獨立部署
+~/SDD/ctos-lite/            # 透過內網 HTTP 呼叫 gemini-image-api
+```
+
+## 已知風險與限制
+
+1. **Google ToS 違規** — 瀏覽器自動化操作 Gemini 違反使用條款，帳號有被封風險
+2. **DOM 會變** — Gemini 改版時 selector 需要手動更新，服務可能突然壞掉
+3. **登入過期** — Google session 過期需人工重新登入，無法自動化
+4. **單一瀏覽器瓶頸** — 同時只能處理一個生圖請求，其他排隊等待
+5. **圖片擷取不保證** — Gemini 回傳圖片的 DOM 結構可能變化
+6. **內容審查** — Gemini 對人像、版權角色等有嚴格限制，部分 prompt 會被拒絕