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+ License: CNC-1.0 Docker

δΈ­ζ–‡ | English | ζ—₯本θͺž

⚠️ 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

  1. Save the following content as docker-compose.yml file:
    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:
    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

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_password
  • x-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 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

{
  "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