134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
---
|
||
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()` |
|