---
name: gemini-api
description: Use when needing to call Gemini LLM for text generation or Gemini LMM for image generation via the local network Master API at 192.168.1.5:10900. Supports chat completion and image generation with concurrency control.
---

# Gemini API (Local Network)

## Overview

Wraps the local Gemini Master API (192.168.1.5:10900) for LLM text and LMM image generation. Max concurrency = 2. Uses `gemini_client.py` helper script.

## When to Use

- Need LLM text generation (chat/completion) via Gemini
- Need image generation via Gemini LMM
- Any task requiring Gemini model capabilities on the local network

## Quick Reference

| Capability | Endpoint | Model Options | Timeout |
|-----------|----------|---------------|---------|
| LLM Chat (sync) | `/api/v1/llm/chat/sync` | `pro` (default), `flash` | ~200s |
| LMM Image (sync) | `/api/v1/lmm/image/sync` | `nano-bananapro` (default) | ~350s |

## Usage

### Helper Script

All calls go through `~/.claude/skills/gemini-api/gemini_client.py`:

```bash
# LLM: text generation
python ~/.claude/skills/gemini-api/gemini_client.py chat "你的问题"

# LLM: with model selection
python ~/.claude/skills/gemini-api/gemini_client.py chat "你的问题" --model flash

# LMM: image generation (saves to file)
python ~/.claude/skills/gemini-api/gemini_client.py image --prompt "图片描述" --output result.png

# LMM: image + auto-remove Gemini watermark
python ~/.claude/skills/gemini-api/gemini_client.py image --prompt "图片描述" --output result.png --remove-watermark

# LMM: image from event data (JSON file)
python ~/.claude/skills/gemini-api/gemini_client.py image --event-data event.json --output result.png

# Batch: multiple requests with concurrency=2
python ~/.claude/skills/gemini-api/gemini_client.py batch requests.jsonl --output-dir ./results/
python ~/.claude/skills/gemini-api/gemini_client.py batch requests.jsonl --output-dir ./results/ --remove-watermark
```

### Python API (recommended for agents)

When writing inline Python scripts (not via CLI), import the module directly:

```python
import sys
sys.path.insert(0, r'C:\Users\ZhuanZ（无密码）\.claude\skills\gemini-api')
# Or on Linux/Mac: sys.path.insert(0, os.path.expanduser('~/.claude/skills/gemini-api'))
from gemini_client import image_sync, save_image_from_response, remove_watermark

# Generate image (always use base64 format)
resp = image_sync(prompt="your prompt here")

# Save to file
save_image_from_response(resp, "output.png")

# Remove watermark (optional)
remove_watermark("output.png")

# Or combine: generate + save + remove watermark in one flow
resp = image_sync(prompt="your prompt here")
save_image_from_response(resp, "output.png")
remove_watermark("output.png")  # overwrites in-place
```

## Image Generation: Critical Notes

### MUST use base64 format (NOT url)

The `output_format="url"` mode is **broken** — returned URLs consistently 404. The client defaults to `base64` which works reliably.

```python
# CORRECT — base64 (default, works)
resp = image_sync(prompt="...", output_format="base64")
save_image_from_response(resp, "out.png")

# WRONG — url download will fail with 404
resp = image_sync(prompt="...", output_format="url")
download_image_by_url(resp["result"]["image_url"], "out.png")  # 404!
```

### Watermark Removal

Gemini `nano-bananapro` adds a small **star/sparkle watermark** in the bottom-right corner of every generated image. Use `--remove-watermark` (CLI) or `remove_watermark()` (Python) to clean it.

**Requires**: `pip install opencv-python numpy` (one-time setup).

```python
from gemini_client import remove_watermark

# Remove watermark in-place
remove_watermark("image.png")

# Or save to a different file
remove_watermark("input.png", "clean.png")

# Custom region size (for non-standard watermark placement)
remove_watermark("input.png", region_w=300, region_h=250)
```

**How it works**: OpenCV `cv2.inpaint` with TELEA algorithm. Detects the watermark region by corner position, creates a mask, and fills in using surrounding pixels. Works well on both solid and complex backgrounds.

## Constraints

- **Concurrency**: Max 2 simultaneous requests (enforced by helper script)
- **API Key**: Uses one key per request, rotated from pool of 3
- **Rate Limit**: 10 req/min, 400 req/hour (server-side)
- **Proxy**: Must bypass system proxy for 192.168.1.5
- **Image format**: Always use `output_format="base64"`, not `"url"`
- **Watermark deps**: `remove_watermark()` needs `opencv-python` and `numpy`

## Common Mistakes

| Mistake | Consequence | Fix |
|---------|-------------|-----|
| Using `output_format="url"` | URL downloads return 404 | Use `"base64"` (default) |
| Forgetting `--noproxy '*'` with curl | Request hangs (proxy intercepts LAN) | Always add `--noproxy '*'` |
| Using `127.0.0.1` instead of `192.168.1.5` | Wrong host | Use `192.168.1.5` |
| Calling `download_image_by_url()` | 404 error | Use `save_image_from_response()` |
| Exceeding concurrency=2 | Queuing delays, timeouts | Use batch mode |
| Not checking `status` field | Missing errors silently | Check `resp.get("status") == "completed"` |
| Forgetting watermark removal | Star logo in bottom-right | Add `--remove-watermark` or call `remove_watermark()` |