ds2api / agy2api /docs /README_EN.md
luckfun233
feat(agy): ε†…ε΅Œ agy2api,ζŽ₯ε…₯ Gemini ζ¨‘εž‹δΈŽη‹¬η«‹ AGY 青板
b0074f5
|
Raw History Blame Contribute Delete
23.8 kB
# AGY2API
**Convert Google Antigravity to OpenAI, Gemini, and Claude API Compatible Interfaces**
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: CNC-1.0](https://img.shields.io/badge/License-CNC--1.0-red.svg)](../LICENSE)
[![Docker](https://img.shields.io/badge/docker-available-blue.svg)](https://github.com/su-kaka/agy2api/pkgs/container/agy2api)
[δΈ­ζ–‡](../README.md) | English | [ζ—₯本θͺž](./README_JA.md)
> **⚠️ Important Change**: The GeminiCLI endpoint has been deprecated by Google. All GeminiCLI-related code has been completely removed; only the Antigravity mode remains.
## Installation Guide
### Termux Environment
**Initial Installation**
```bash
curl -o termux-install.sh "https://raw.githubusercontent.com/su-kaka/agy2api/refs/heads/master/termux-install.sh" && chmod +x termux-install.sh && ./termux-install.sh
```
**Restart Service**
```bash
cd agy2api
bash termux-start.sh
```
### Windows Environment
**Initial Installation**
```powershell
iex (iwr "https://raw.githubusercontent.com/su-kaka/agy2api/refs/heads/master/install.ps1" -UseBasicParsing).Content
```
**Restart Service**
Double-click to execute `start.bat`
### Linux Environment
**Initial Installation**
```bash
curl -o install.sh "https://raw.githubusercontent.com/su-kaka/agy2api/refs/heads/master/install.sh" && chmod +x install.sh && ./install.sh
```
**Restart Service**
```bash
cd agy2api
bash start.sh
```
### macOS Environment
**Initial Installation**
```bash
curl -o darwin-install.sh "https://raw.githubusercontent.com/su-kaka/agy2api/refs/heads/master/darwin-install.sh" && chmod +x darwin-install.sh && ./darwin-install.sh
```
**Restart Service**
```bash
cd agy2api
bash start.sh
```
### Docker Environment
**Docker Run Command**
```bash
docker run -d --name agy2api --network host -e API_PASSWORD=api_pwd -e PANEL_PASSWORD=panel_pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds -v $(pwd)/data/request_logs:/app/data/request_logs ghcr.io/su-kaka/agy2api:latest
```
**Docker Mac**
```bash
docker run -d \
--name agy2api \
-p 7861:7861 \
-p 8080:8080 \
-e API_PASSWORD=api_pwd \
-e PANEL_PASSWORD=panel_pwd \
-e PORT=7861 \
-v "$(pwd)/data/creds":/app/creds \
-v "$(pwd)/data/request_logs":/app/data/request_logs \
ghcr.io/su-kaka/agy2api:latest
```
**Docker Compose Run Command**
1. Save the following content as `docker-compose.yml` file:
```yaml
version: '3.8'
services:
agy2api:
image: ghcr.io/su-kaka/agy2api:latest
container_name: agy2api
restart: unless-stopped
network_mode: host
environment:
# Password configuration (separate passwords)
- API_PASSWORD=your_api_password
- PANEL_PASSWORD=your_panel_password
- PORT=7861
volumes:
- ./data/creds:/app/creds
- ./data/request_logs:/app/data/request_logs
healthcheck:
test: ["CMD-SHELL", "python -c \"import sys, urllib.request, os; port = os.environ.get('PORT', '7861'); req = urllib.request.Request(f'http://localhost:{port}/v1/models', headers={'Authorization': 'Bearer ' + os.environ.get('API_PASSWORD', 'pwd')}); sys.exit(0 if urllib.request.urlopen(req, timeout=5).getcode() == 200 else 1)\""]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
2. Start the service:
```bash
docker-compose up -d
```
## Core Features
### πŸ”„ API Endpoints and Format Support
**Multi-endpoint Multi-format Support**
- **OpenAI Compatible Endpoints**: `/v1/chat/completions` and `/v1/models`
- Supports standard OpenAI format (messages structure)
- Supports Gemini native format (contents structure)
- Automatic format detection and conversion, no manual switching required
- Supports multimodal input (text + images)
- **Gemini Native Endpoints**: `/v1/models/{model}:generateContent` and `streamGenerateContent`
- Supports complete Gemini native API specifications
- Multiple authentication methods: Bearer Token, x-goog-api-key header, URL parameter key
- **Claude Format Compatibility**: Full support for Claude API format
- Endpoint: `/v1/messages` (follows Claude API specification)
- Supports Claude standard messages format
- Supports system parameter and Claude-specific features
- Automatically converts to backend-supported format
- **Antigravity API Support**: Supports OpenAI, Gemini, and Claude formats
- OpenAI format endpoint: `/v1/chat/completions`
- Gemini format endpoint: `/v1/models/{model}:generateContent` and `streamGenerateContent`
- Claude format endpoint: `/v1/messages`
- Supports all Antigravity models (Claude, Gemini, etc.)
- Automatic model name mapping and thinking mode detection
### πŸ” Authentication and Security Management
**Flexible Password Management**
- **Separate Password Support**: API password (chat endpoints) and control panel password can be set independently
- **Multiple Authentication Methods**: Supports Authorization Bearer, x-goog-api-key header, URL parameters, etc.
- **JWT Token Authentication**: Control panel supports JWT token authentication
- **User Email Retrieval**: Automatically retrieves and displays Google account email addresses
### πŸ“Š Intelligent Credential Management System
**Advanced Credential Management**
- Multiple Google OAuth credential automatic rotation
- Enhanced stability through redundant authentication
- Load balancing and concurrent request support
- Automatic failure detection and credential disabling
- Credential usage statistics and quota management
- Credentials keyed by email (unique); re-importing the same email overwrites automatically
- Batch operations (enable, disable, delete)
**Credential Status Monitoring**
- Real-time credential health checks
- Error code tracking (429, 403, 500, etc.)
- Automatic banning mechanism (configurable)
### 🌊 Streaming and Response Processing
**Multiple Streaming Support**
- True real-time streaming responses
- Streaming anti-truncation feature (prevents answer truncation)
- Asynchronous task management and timeout handling
**Response Optimization**
- Thinking chain content separation
- Reasoning process (reasoning_content) handling
- Multi-turn conversation context management
### πŸŽ›οΈ Web Management Console
**Full-featured Web Interface**
- Antigravity OAuth authentication flow (with callback URL shortcut)
- Credential file upload, download, and management
- System configuration management
- Usage statistics and monitoring dashboard
- Mobile-friendly interface
**Batch Operation Support**
- ZIP/JSON batch credential upload (Antigravity)
- Batch enable/disable/delete credentials
- Batch user email retrieval
- Batch configuration management
- Unified batch upload interface for all credential types
### πŸ”§ Advanced Configuration and Customization
**Network and Proxy Configuration**
- HTTP/HTTPS proxy support
- Proxy endpoint configuration (OAuth, Google APIs, metadata service)
- Timeout and retry configuration
- Network error handling and recovery
**Performance and Stability Configuration**
- 429 error automatic retry (configurable interval and attempts)
- Anti-truncation maximum retry attempts
**Logging and Debugging**
- Multi-level logging system (DEBUG, INFO, WARNING, ERROR)
- Console-only logging (`ENABLE_LOG=0` for full silence)
### πŸ”„ Environment Variables and Configuration Management
**Flexible Configuration Methods**
- Environment variable configuration
- Hot configuration updates (partial configuration items)
- Configuration locking (environment variable priority)
## Supported Models
All models have 1M context window capacity. Each credential file provides 1000 request quota.
### πŸ€– Base Models
- `gemini-2.5-pro`
- `gemini-3-pro-preview`
- `gemini-3.1-pro-preview`
### 🧠 Thinking Models
- `gemini-2.5-pro-high`: Thinking mode
- `gemini-2.5-pro-low`: Low thinking mode
- Supports custom thinking budget configuration
- Automatic separation of thinking content and final answers
### πŸ” Search-Enhanced Models
- `gemini-2.5-pro-search`: Model with integrated search functionality
### πŸ–ΌοΈ Image Generation Models (Antigravity)
- `gemini-3.1-flash-image`: Base image generation model
- **Resolution Suffixes**:
- `-2k`: 2K resolution
- `-4k`: 4K HD resolution
- **Aspect Ratio Suffixes**:
- `-1x1`: Square (avatar)
- `-16x9`: Landscape (desktop wallpaper)
- `-9x16`: Portrait (mobile wallpaper)
- `-21x9`: Ultra-wide (ultrawide monitor)
- `-4x3`: Traditional display
- `-3x4`: Portrait poster
- **Combination Examples**:
- `gemini-3.1-flash-image-4k-16x9`: 4K landscape
- `gemini-3.1-flash-image-2k-9x16`: 2K portrait
- When no ratio is specified, the API automatically decides the aspect ratio
### 🌊 Special Feature Variants
- **Anti-truncation Mode**: Add `ζŠ—ζˆͺζ–­-` prefix to model name
- Example: `ζŠ—ζˆͺζ–­-gemini-2.5-pro`
- Uses synthetic tool calls to bypass truncation limits and ensure complete answers (works for both streaming and non-streaming)
### πŸ”§ Automatic Model Feature Detection
- System automatically recognizes feature identifiers in model names
- Transparently handles feature mode transitions
- Supports feature combination usage
---
## Configuration Instructions
1. Visit `http://127.0.0.1:7861` (default port, modifiable via PORT environment variable)
2. Complete OAuth authentication flow (default password: `pwd`, modifiable via environment variables)
3. Configure client:
**OpenAI Compatible Client:**
- **Endpoint Address**: `http://127.0.0.1:7861/v1`
- **API Key**: `pwd` (default value, modifiable via API_PASSWORD environment variable)
**Gemini Native Client:**
- **Endpoint Address**: `http://127.0.0.1:7861`
- **Authentication Methods**:
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL parameter: `?key=your_api_password`
## πŸ’Ύ Data Storage Mode
### 🌟 Storage Backend Support
agy2api supports two storage backends: **Local SQLite (Default)** and **PostgreSQL (Cloud Distributed Storage)**
### πŸ“ Local SQLite Storage (Default)
**Default Storage Method**
- No configuration required, works out of the box
- Data is stored in a local SQLite database (`creds/credentials.db`)
- Suitable for single-machine deployment and personal use
**Credential Structure**
Credentials are stored as structured database columns (no JSON blobs), keyed uniquely by **email**:
`email`, `access_token`, `refresh_token`, `client_id`, `client_secret`, `project_id`, `expiry`, `tier`
Import/export uses a standardized JSON format: `{"refresh_token": "...", "access_token": "...", "expiry": "...", "email": "...", "tier": "...", "project_id": "..."}` (only `refresh_token` is required; an unexpired `access_token` is reused directly; the rest are fetched automatically).
### Environment Variable Configuration
**Basic Configuration**
- `PORT`: Service port (default: 7861)
- `HOST`: Server listen address (default: 0.0.0.0)
**Password Configuration**
- `API_PASSWORD`: Chat API access password (default: pwd)
- `PANEL_PASSWORD`: Control panel access password (default: pwd)
**Access Control Configuration**
- `IP_WHITELIST_ENABLED`: Enable IP whitelist (default: false, no restriction)
- `IP_WHITELIST`: IP whitelist, comma or newline separated (default: empty). Each entry supports a single IP (`192.168.1.1`), CIDR range (`192.168.1.0/24`), or start-end range (`10.0.0.1-10.0.0.100`), for both IPv4 / IPv6. Once enabled, only whitelisted IPs can access the panel and API; all others get 403. Effective immediately after panel save
**Model Name Rewrite**
- `MODEL_REWRITE_ENABLED`: Enable model name rewriting (default: false)
- `MODEL_REWRITE_RULES`: Rewrite rules, each `[match regex, replacement model name]` (default: empty). First match from top wins; replacements support regex backreferences (e.g. `\1`). Example: map `gpt-4o` to `gemini-2.5-pro`. Effective immediately after panel save
**Performance and Stability Configuration**
- `RETRY_429_ENABLED`: Enable 429 error automatic retry (default: true)
- `RETRY_429_MAX_RETRIES`: Maximum retry attempts for 429 errors (default: 5)
- `RETRY_429_INTERVAL`: Retry interval for 429 errors, in seconds (default: 1.0)
- `ANTI_TRUNCATION_MAX_ATTEMPTS`: Maximum retry attempts for anti-truncation (default: 3)
**Network and Proxy Configuration**
- `PROXY`: Proxy address (supports `http://`, `https://`, `socks5://`, `socks5h://`, optionally with credentials `user:pass@host:port`)
- `OAUTH_PROXY_URL`: OAuth authentication proxy endpoint
- `GOOGLEAPIS_PROXY_URL`: Google APIs proxy endpoint
- `PATH_PREFIX`: When the reverse proxy preserves the path prefix (e.g. `/AGY2API`), set this so the backend strips it before routing; default: empty (no stripping)
**Automation Configuration**
- `AUTO_BAN`: Enable automatic credential banning (default: false)
- `AUTO_BAN_ERROR_CODES`: Error codes that trigger automatic banning (default: 403)
**Logging Configuration**
- `LOG_LEVEL`: Log level (DEBUG/INFO/WARNING/ERROR, default: INFO)
- `ENABLE_LOG`: Full silence, no log output (set to 0 to enable, default: 1)
**Response Behavior Configuration**
- `RETURN_THOUGHTS_TO_FRONTEND`: Return thinking chain to the frontend (default: true)
**Sensitive Word Filtering**
- `SENSITIVE_WORDS_ENABLED`: Enable sensitive word filtering (default: false)
- `SENSITIVE_WORDS`: Sensitive word list, comma or newline separated (default: empty). Matches are replaced with empty string, case-insensitive, Chinese supported, effective immediately after panel save
**Usage Log**
- `USAGE_LOG_ENABLED`: Enable request logging (default: true). Records every API request (model, credential, token usage, latency, status) to the database. No automatic cleanup; use the panel to clear logs manually
**Request Body Debug Log**
- `REQUEST_LOG_ENABLED`: Enable request body debug logging (default: false). When enabled and the final status code matches the configured codes, the full request headers (redacted) and body sent upstream are saved as JSON files under `data/request_logs/`. Only the file index is stored in the database; view it from the request log detail modal. Mainly for debugging request body errors (e.g. 400); clearing/truncating logs also deletes these files (mount `./data/request_logs:/app/data/request_logs` in Docker to persist)
- `REQUEST_LOG_ERROR_CODES`: Status codes that trigger debug logging, comma separated (default: 400)
**Credential Select Mode**
- `CREDENTIAL_SELECT_MODE`: Credential selection mode (default: cache)
- `random` β€” Fully random load balancing, each request picks a random credential
- `cache` β€” Cache affinity (recommended): hashes "model + system instruction (or first user message)" into a session key; the same session reuses the same credential, hitting Google's upstream prompt cache; automatically switches and rebinds after credential cooldown
- `sticky` β€” Sticky: all requests lock onto one credential until it enters cooldown or gets disabled
- `REDIS_URL`: Redis connection string (optional). When set, cache-mode session bindings are stored in Redis for multi-instance sharing; otherwise an in-process memory backend is used
**Storage Configuration**
**SQLite (Default)**
- No configuration required, database file created in `creds/` automatically
**PostgreSQL (Optional Cloud Storage)**
- `POSTGRESQL_URI`: PostgreSQL connection string (enables PostgreSQL mode when set)
**Docker Usage Example**
```bash
docker run -d --name agy2api \
-e API_PASSWORD=my_api_password \
-e PANEL_PASSWORD=my_panel_password \
-e PORT=7861 \
ghcr.io/su-kaka/agy2api:latest
```
### API Usage Methods
This service supports multiple complete sets of API endpoints:
#### 3. Claude API Format Endpoints
**Endpoint:** `/v1/messages`
**Authentication:** `x-api-key: your_api_password` or `Authorization: Bearer your_api_password`
**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/v1/messages" \
-H "x-api-key: your_api_password" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-pro",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'
```
**Support for system parameter:**
```json
{
"model": "gemini-2.5-pro",
"max_tokens": 1024,
"system": "You are a helpful assistant",
"messages": [
{"role": "user", "content": "Hello"}
]
}
```
**Notes:**
- Fully compatible with Claude API format specification
- Automatically converts to Gemini format for backend calls
- Supports all Claude standard parameters
- Response format follows Claude API specification
#### 4. Antigravity API Endpoints
**Supports three formats: OpenAI, Gemini, and Claude**
##### Antigravity OpenAI Format Endpoints
**Endpoint:** `/v1/chat/completions`
**Authentication:** `Authorization: Bearer your_api_password`
**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/v1/chat/completions" \
-H "Authorization: Bearer your_api_password" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"messages": [
{"role": "user", "content": "Hello"}
],
"stream": true
}'
```
##### Antigravity Gemini Format Endpoints
**Non-streaming Endpoint:** `/v1/models/{model}:generateContent`
**Streaming Endpoint:** `/v1/models/{model}:streamGenerateContent`
**Authentication Methods (choose one):**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL parameter: `?key=your_api_password`
**Request Examples:**
```bash
# Gemini format non-streaming request
curl -X POST "http://127.0.0.1:7861/v1/models/claude-sonnet-4-5:generateContent" \
-H "x-goog-api-key: your_api_password" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "Hello"}]}
],
"generationConfig": {
"temperature": 0.7
}
}'
# Gemini format streaming request
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-flash:streamGenerateContent?key=your_api_password" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "Hello"}]}
]
}'
```
##### Antigravity Claude Format Endpoints
**Endpoint:** `/v1/messages`
**Authentication:** `x-api-key: your_api_password`
**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/v1/messages" \
-H "x-api-key: your_api_password" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello"}
]
}'
```
**Supported Antigravity Models:**
- Claude series: `claude-sonnet-4-5`, `claude-opus-4-5`, etc.
- Gemini series: `gemini-2.5-flash`, `gemini-2.5-pro`, etc.
- Automatically supports thinking models
**Gemini Native Example:**
```python
from io import BytesIO
from PIL import Image
from google.genai import Client
from google.genai.types import HttpOptions
from google.genai import types
# The client gets the API key from the environment variable `GEMINI_API_KEY`.
client = Client(
api_key="pwd",
http_options=HttpOptions(base_url="http://127.0.0.1:7861"),
)
prompt = (
"""
Draw a cat
"""
)
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=[prompt],
config=types.GenerateContentConfig(
image_config=types.ImageConfig(
aspect_ratio="16:9",
)
)
)
for part in response.candidates[0].content.parts:
if part.text is not None:
print(part.text)
elif part.inline_data is not None:
image = Image.open(BytesIO(part.inline_data.data))
image.save("generated_image.png")
```
**Notes:**
- OpenAI endpoints return OpenAI-compatible format
- Gemini endpoints return Gemini native format
- Both endpoints use the same API password
## πŸ“‹ Complete API Reference
### Web Console API
**Authentication Endpoints**
- `POST /auth/login` - User login
- `POST /auth/start` - Start Antigravity OAuth authentication
- `POST /auth/callback` - Handle OAuth callback
- `POST /auth/callback-url` - Complete authentication directly from callback URL
- `GET /auth/status/{project_id}` - Check authentication status
**Credential Management Endpoints**
- `POST /creds/upload` - Batch upload credential files (supports JSON and ZIP)
- `GET /creds/status` - Get credential status list (supports pagination and filtering)
- `GET /creds/detail/{email}` - Get single credential details
- `POST /creds/action` - Single credential operation (enable/disable/delete)
- `POST /creds/batch-action` - Batch credential operations
- `GET /creds/export/{email}` - Export single credential as standardized JSON
- `GET /creds/download-all` - Package download all credentials (standardized JSON, one file per email)
- `GET /creds/quota/{email}` - Get credential quota information
**Configuration Management Endpoints**
- `GET /config/get` - Get current configuration
- `POST /config/save` - Save configuration
**Version Information Endpoints**
- `GET /version/info` - Get version information (optional `check_update=true` parameter to check for updates)
### Chat API Features
**Multimodal Support**
```json
{
"model": "gemini-2.5-pro",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image"},
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA..."
}
}
]
}
]
}
```
**Thinking Mode Support**
```json
{
"model": "gemini-2.5-pro-high",
"messages": [
{"role": "user", "content": "Complex math problem"}
]
}
```
Response will include separated thinking content:
```json
{
"choices": [{
"message": {
"role": "assistant",
"content": "Final answer",
"reasoning_content": "Detailed thought process..."
}
}]
}
```
**Anti-truncation Usage**
```json
{
"model": "ζŠ—ζˆͺζ–­-gemini-2.5-pro",
"messages": [
{"role": "user", "content": "Write a long article"}
],
"stream": true
}
```
---
## πŸ› οΈ Frontend Development
The panel frontend source lives in `frontend/` (React + Vite + Tailwind CSS):
```bash
cd frontend
npm install
npm run dev # Development mode, port 3000, proxies backend API
npm run build # Build to dist/ (used in production)
```
The backend serves the compiled static files under `dist/` directly; no Node.js runtime required.
## πŸ’¬ Community
Welcome to join the QQ group for discussion!
**QQ Group: 1083250744**
---
## License and Disclaimer
This project is for learning and research purposes only. Using this project indicates that you agree to:
- Not use this project for any commercial purposes
- Bear all risks and responsibilities of using this project
- Comply with relevant terms of service and legal regulations
The project authors are not responsible for any direct or indirect losses arising from the use of this project.
## ⚠️ License Declaration
**This project is licensed under the Cooperative Non-Commercial License (CNC-1.0)**
This is a strict anti-commercial open source license. Please refer to the [LICENSE](../LICENSE) file for details.
### βœ… Permitted Uses:
- Personal learning, research, and educational purposes
- Non-profit organization use
- Open source project integration (must comply with the same license)
- Academic research and publication
### ❌ Prohibited Uses:
- Any form of commercial use
- Enterprise use with annual revenue exceeding $1 million
- Venture capital-backed or publicly traded companies
- Providing paid services or products
- Commercial competitive use