Download agy2api/docs/README_EN.md from a3216/ds2api: direct link, hf CLI and curl.
- Browser
- Download file 23.8 kB
-
https://huggingface.co/spaces/a3216/ds2api/resolve/main/agy2api/docs/README_EN.md
- Command line
-
hf download hf://spaces/a3216/ds2api/agy2api/docs/README_EN.md
-
curl -L -o README_EN.md https://huggingface.co/spaces/a3216/ds2api/resolve/main/agy2api/docs/README_EN.md
AGY2API
Convert Google Antigravity to OpenAI, Gemini, and Claude API Compatible Interfaces
β οΈ 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
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
cd agy2api
bash termux-start.sh
Windows Environment
Initial Installation
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
curl -o install.sh "https://raw.githubusercontent.com/su-kaka/agy2api/refs/heads/master/install.sh" && chmod +x install.sh && ./install.sh
Restart Service
cd agy2api
bash start.sh
macOS Environment
Initial Installation
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
cd agy2api
bash start.sh
Docker Environment
Docker Run Command
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
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
- Save the following content as
docker-compose.ymlfile: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 - Start the service:
docker-compose up -d
Core Features
π API Endpoints and Format Support
Multi-endpoint Multi-format Support
- OpenAI Compatible Endpoints:
/v1/chat/completionsand/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}:generateContentandstreamGenerateContent- 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
- Endpoint:
- Antigravity API Support: Supports OpenAI, Gemini, and Claude formats
- OpenAI format endpoint:
/v1/chat/completions - Gemini format endpoint:
/v1/models/{model}:generateContentandstreamGenerateContent - Claude format endpoint:
/v1/messages - Supports all Antigravity models (Claude, Gemini, etc.)
- Automatic model name mapping and thinking mode detection
- OpenAI format endpoint:
π 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=0for 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-progemini-3-pro-previewgemini-3.1-pro-preview
π§ Thinking Models
gemini-2.5-pro-high: Thinking modegemini-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 landscapegemini-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)
- Example:
π§ Automatic Model Feature Detection
- System automatically recognizes feature identifiers in model names
- Transparently handles feature mode transitions
- Supports feature combination usage
Configuration Instructions
- Visit
http://127.0.0.1:7861(default port, modifiable via PORT environment variable) - Complete OAuth authentication flow (default password:
pwd, modifiable via environment variables) - 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_passwordx-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: mapgpt-4otogemini-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 (supportshttp://,https://,socks5://,socks5h://, optionally with credentialsuser:pass@host:port)OAUTH_PROXY_URL: OAuth authentication proxy endpointGOOGLEAPIS_PROXY_URL: Google APIs proxy endpointPATH_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 underdata/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_logsin 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 credentialcacheβ 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 cooldownstickyβ 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
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:
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:
{
"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:
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_passwordx-goog-api-key: your_api_password- URL parameter:
?key=your_api_password
Request Examples:
# 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:
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:
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 loginPOST /auth/start- Start Antigravity OAuth authenticationPOST /auth/callback- Handle OAuth callbackPOST /auth/callback-url- Complete authentication directly from callback URLGET /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 detailsPOST /creds/action- Single credential operation (enable/disable/delete)POST /creds/batch-action- Batch credential operationsGET /creds/export/{email}- Export single credential as standardized JSONGET /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 configurationPOST /config/save- Save configuration
Version Information Endpoints
GET /version/info- Get version information (optionalcheck_update=trueparameter to check for updates)
Chat API Features
Multimodal Support
{
"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
{
"model": "gemini-2.5-pro-high",
"messages": [
{"role": "user", "content": "Complex math problem"}
]
}
Response will include separated thinking content:
{
"choices": [{
"message": {
"role": "assistant",
"content": "Final answer",
"reasoning_content": "Detailed thought process..."
}
}]
}
Anti-truncation Usage
{
"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):
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 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