justlovemaki/AIClient2API

💡 Tip: For the best experience, it is recommended to manage authorization visually through the Web UI console.

🌐 Web UI Quick Authorization (Recommended)

In the Web UI management interface, you can complete authorization configuration rapidly:

1. Generate Authorization: On the "Provider Pools" page or "Configuration" page, click the "Generate Authorization" button in the upper right corner of the corresponding provider (e.g., Codex).
2. Scan/Login: An authorization dialog will pop up, you can click "Open in Browser" for login verification. For Antigravity, complete the Google account authorization.
3. Auto-Save: After successful authorization, the system will automatically obtain credentials and save them to the corresponding directory in configs/. You can see the newly generated credentials on the "Config Files" page.
4. Visual Management: You can upload or delete credentials at any time in the Web UI, or use the "Quick Associate" function to bind existing credential files to providers with one click.

Antigravity OAuth Configuration

1. Personal Account: Personal accounts require separate authorization, application channels have been closed.
2. Pro Member: Antigravity is temporarily open to Pro members, you need to purchase a Pro membership first.
3. Organization Account: Organization accounts require separate authorization, contact the administrator to obtain authorization.

For free-tier model listings, legacy alias compatibility, and differences from upstream documentation, see the Antigravity free-tier model policy.

Kiro API Configuration

1. Environment Preparation: Download and install Kiro client
2. Complete Authorization: Log in to your account in the client to generate kiro-auth-token.json credential file
3. Best Practice: Recommended to use with Claude Code for optimal experience
4. Important Notice: Kiro service usage policy has been updated, please visit the official website for the latest usage restrictions and terms

Kiro Extended Thinking (Claude Models)

AIClient2API supports Kiro extended thinking when using Claude-compatible requests (/v1/messages) or OpenAI-compatible requests (/v1/chat/completions) routed to claude-kiro-oauth.

Claude-compatible (/v1/messages):

curl http://localhost:3000/claude-kiro-oauth/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "thinking": { "type": "enabled", "budget_tokens": 10000 },
    "messages": [{ "role": "user", "content": "Solve this step by step." }]
  }'

OpenAI-compatible (/v1/chat/completions):

curl http://localhost:3000/claude-kiro-oauth/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{ "role": "user", "content": "Solve this step by step." }],
    "extra_body": {
      "anthropic": {
        "thinking": { "type": "enabled", "budget_tokens": 10000 }
      }
    }
  }'

Adaptive mode:

• Claude: "thinking": { "type": "adaptive", "effort": "high" }
• OpenAI: "extra_body.anthropic.thinking": { "type": "adaptive", "effort": "high" }

Notes:

• budget_tokens is clamped to [1024, 24576] (default 20000 if omitted/invalid).
• Token acquisition/refresh/pool rotation is unchanged.

Codex OAuth Configuration

1. Generate Authorization: On the Web UI "Provider Pools" or "Configuration" page, click the "Generate Authorization" button for Codex
2. Browser Login: The system opens the OpenAI Codex authorization page to complete OAuth login
3. Auto Save: After successful authorization, the system automatically saves the Codex OAuth credential file
4. Callback Port: Ensure the OAuth callback port 1455 is not occupied

Grok CLI OAuth Configuration

1. Generate Authorization: On the Web UI "Provider Pools" or "Configuration" page, click the "Generate Authorization" button for Grok CLI
2. Browser Login: The system opens the xAI authorization page to complete OAuth login
3. Auto Save: After successful authorization, the system automatically saves the Grok CLI OAuth credential file to configs/grok-cli/
4. Callback Port: Ensure the OAuth callback port 56121 is not occupied

Grok Cookie/SSO Configuration

1. Obtain SSO Token: Log in to the Grok official website, copy the value of sso from Application -> Cookies in browser developer tools
2. Enter Configuration: In the Web UI "Configuration" page or directly modify the configuration file, enter the token into GROK_COOKIE_TOKEN
3. Supported Features:
   • Chat and Thinking models (Grok Thinking)
   • Image generation (Grok Imagine)
   • Video generation (Grok Video)
4. Notes: Ensure GROK_USER_AGENT matches the browser used when obtaining the cookie to avoid being blocked

Account Pool Management Configuration

1. Create Pool Configuration File: Create a configuration file referencing provider_pools.json.example
2. Configure Pool Parameters: Set PROVIDER_POOLS_FILE_PATH in configs/config.json to point to the pool configuration file
3. Startup Parameter Configuration: Use the --provider-pools-file <path> parameter to specify the pool configuration file path
4. Health Check: The system will automatically perform periodic health checks and avoid using unhealthy providers

Default storage locations for authorization credential files of each service:

Note: ~ represents the user home directory (Windows: C:\Users\username, Linux/macOS: /home/username or /Users/username)

Custom Path: Can specify custom storage location via relevant parameters in configuration file or environment variables

1. Proxy Configuration

This project supports flexible proxy configuration, allowing you to configure a unified proxy for different providers or use provider-specific proxied endpoints.

Configuration Methods:

1. Web UI Configuration (Recommended): Convenient configuration management

In the "Configuration" page of the Web UI, you can visually configure all proxy options:

• Unified Proxy: Fill in the proxy address in the "Proxy Settings" area and check the providers that need to use the proxy
• Provider Endpoints: In each provider's configuration area, directly modify the Base URL to a proxied endpoint
• Click "Save Configuration": Takes effect immediately without restarting the service

2. Unified Proxy Configuration: Configure a global proxy and specify which providers use it

   • Web UI Configuration: Fill in the proxy address in the "Proxy Settings" area of the "Configuration" page and check the providers that need to use the proxy
   • Configuration File: Configure in configs/config.json

   {
     "PROXY_URL": "http://127.0.0.1:7890",
      "PROXY_ENABLED_PROVIDERS": [
        "gemini-antigravity",
        "claude-kiro-oauth",
        "grok-web"
      ]
    }
   

3. Provider-Specific Proxied Endpoints: Some providers (like OpenAI, Claude) support configuring proxied API endpoints

   • Web UI Configuration: In each provider's configuration area on the "Configuration" page, modify the corresponding Base URL
   • Configuration File: Configure in configs/config.json

   {
     "OPENAI_BASE_URL": "https://your-proxy-endpoint.com/v1",
     "CLAUDE_BASE_URL": "https://your-proxy-endpoint.com/v1"
   }
   

Supported Proxy Types:

• HTTP Proxy: http://127.0.0.1:7890
• HTTPS Proxy: https://127.0.0.1:7890
• SOCKS5 Proxy: socks5://127.0.0.1:1080

Use Cases:

• Network-Restricted Environments: Use in network environments where Google, OpenAI, and other services cannot be accessed directly
• Hybrid Configuration: Some providers use unified proxy, others use their own proxied endpoints
• Flexible Switching: Enable/disable proxy for specific providers at any time in the Web UI

Notes:

• Proxy configuration priority: Unified proxy configuration > Provider-specific endpoints > Direct connection
• Ensure the proxy service is stable and available, otherwise it may affect service quality
• SOCKS5 proxy usually performs better than HTTP proxy

2. Model Filtering Configuration

Support excluding unsupported models through notSupportedModels configuration, the system will automatically skip these providers.

Configuration: Add notSupportedModels field for providers in configs/provider_pools.json:

{
  "gemini-antigravity": [
    {
      "uuid": "provider-1",
      "notSupportedModels": ["gemini-3.0-pro", "gemini-3.5-flash"],
      "checkHealth": true
    }
  ]
}

How It Works:

• When requesting a specific model, the system automatically filters out providers that have configured the model as unsupported
• Only providers that support the model will be selected to handle the request

Use Cases:

• Some accounts cannot access specific models due to quota or permission restrictions
• Need to assign different model access permissions to different accounts

3. Cross-Type Fallback Configuration

When all accounts under a Provider Type (e.g., claude-kiro-oauth) are exhausted due to 429 quota limits or marked as unhealthy, the system can automatically fallback to another compatible Provider Type (e.g., claude-custom) instead of returning an error directly.

Configuration: Add providerFallbackChain configuration in configs/config.json:

{
  "providerFallbackChain": {
    "claude-kiro-oauth": ["claude-custom"],
    "claude-custom": ["claude-kiro-oauth"]
  }
}

How It Works:

1. Try to select a healthy account from the primary Provider Type pool
2. If all accounts in that type are unhealthy or return 429:
   • Look up the configured fallback types
   • Check if the fallback type supports the requested model (protocol compatibility check)
   • Select a healthy account from the fallback type's pool
3. Supports multi-level degradation chains: claude-kiro-oauth → claude-custom → openai-custom
4. Only returns an error if all fallback types are also unavailable

Use Cases:

• In batch task scenarios, the free RPD quota of a single Provider Type can be easily exhausted in a short time
• Through cross-type Fallback, you can fully utilize the independent quotas of multiple Providers, improving overall availability and throughput

Notes:

• Fallback only occurs between protocol-compatible types (e.g., between gemini-*, between claude-*)
• The system automatically checks if the target Provider Type supports the requested model

4. TLS Sidecar (Bypass 403/Cloudflare)

For services like Grok that strictly validate TLS fingerprints (JA3/JA4), this project integrates a Sidecar proxy based on Go uTLS, which effectively solves 403 Forbidden errors by simulating browser TLS features.

Configuration Instructions:

1. Compile the Binary: Since TLS simulation requires Go language support, you need to compile the sidecar first:

   cd tls-sidecar
   go build -o tls-sidecar
   

   Windows users, after compiling, ensure the generated tls-sidecar.exe is located in the tls-sidecar/ or the root directory.

2. Enable Configuration: Enable TLS Sidecar in the "Configuration" page of the Web UI, or modify configs/config.json:

   {
     "TLS_SIDECAR_ENABLED": true,
     "TLS_SIDECAR_PORT": 9090
   }
   

3. How It Works:

   • When enabled, the system automatically starts and manages the Go process.
   • Requests for specific providers (like Grok) are automatically routed to the Sidecar.
   • The Sidecar uses the latest Chrome fingerprint for TLS handshakes and supports automatic HTTP/2 negotiation.

Notes:

• Local running requires a Go environment (1.20+).
• Docker Users: The image already includes the pre-compiled binary; just enable it in the configuration, no manual compilation required.

1. OAuth Authorization Failed

Problem Description: After clicking "Generate Authorization", the browser opens the authorization page but authorization fails or cannot be completed.

Solutions:

• Check Network Connection: Ensure you can access Google, Alibaba Cloud, and other services normally
• Check Port Occupation: OAuth callbacks require specific ports (Antigravity: 8086, Codex: 1455, Grok CLI: 56121, Kiro: 19876-19880), ensure these ports are not occupied
• Clear Browser Cache: Try using incognito mode or clearing browser cache and retry
• Check Firewall Settings: Ensure the firewall allows access to local callback ports
• Docker Users: Ensure all OAuth callback ports are correctly mapped

2. Port Already in Use

Problem Description: When starting the service, it shows the port is already in use (e.g., EADDRINUSE).

Solutions:

# Windows - Find the process occupying the port
netstat -ano | findstr :3000
# Then use Task Manager to end the corresponding PID process

# Linux/macOS - Find and end the process occupying the port
lsof -i :3000
kill -9 <PID>

Or modify the port configuration in configs/config.json to use a different port.

3. Docker Container Won't Start

Problem Description: Docker container fails to start or exits immediately.

Solutions:

• Check Logs: docker logs aiclient2api to view error messages
• Check Mount Path: Ensure the local path in the -v parameter exists and has read/write permissions
• Check Port Conflicts: Ensure all mapped ports are not occupied on the host
• Re-pull Image: docker pull justlikemaki/aiclient-2-api:latest

4. Credential File Not Recognized

Problem Description: After uploading or configuring credential files, the system shows it cannot be recognized or format error.

Solutions:

• Check File Format: Ensure the credential file is valid JSON format
• Check File Path: Ensure the file path is correct, Docker users need to ensure the file is in the mounted directory
• Check File Permissions: Ensure the service has permission to read the credential file
• Regenerate Credentials: If credentials have expired, try re-authorizing via OAuth

5. Request Returns 429 Error

Problem Description: API requests frequently return 429 Too Many Requests error.

Solutions:

• Configure Account Pool: Add multiple accounts to provider_pools.json, enable polling mechanism
• Configure Fallback: Configure providerFallbackChain in config.json for cross-type degradation
• Enable 429 Cooldown: Set RATE_LIMIT_COOLDOWN_ENABLED to true and tune RATE_LIMIT_COOLDOWN_MS so rate-limited accounts temporarily leave the pool and recover automatically
• Reduce Request Frequency: Appropriately increase request intervals to avoid triggering rate limits
• Wait for Quota Reset: Free quotas usually reset daily or per minute

6. Model Unavailable or Returns Error

Problem Description: When requesting a specific model, it returns an error or shows the model is unavailable.

Solutions:

• Check Model Name: Ensure you're using the correct model name (case-sensitive)
• Check Provider Support: Confirm the currently configured provider supports that model
• Check Account Permissions: Some advanced models may require specific account permissions
• Configure Model Filtering: Use notSupportedModels to exclude unsupported models

7. Web UI Cannot Be Accessed

Problem Description: Browser cannot open http://localhost:3000.

Solutions:

• Check Service Status: Confirm the service has started successfully, check terminal output
• Check Port Mapping: Docker users ensure -p 3000:3000 parameter is correct
• Try Other Address: Try accessing http://127.0.0.1:3000
• Check Firewall: Ensure the firewall allows access to port 3000

8. Streaming Response Interrupted

Problem Description: When using streaming output, the response is interrupted midway or incomplete.

Solutions:

• Check Network Stability: Ensure network connection is stable
• Increase Timeout: Increase request timeout in client configuration
• Check Proxy Settings: If using a proxy, ensure the proxy supports long connections
• Check Service Logs: Check for error messages

9. Configuration Changes Not Taking Effect

Problem Description: After modifying configuration in Web UI, service behavior doesn't change.

Solutions:

• Refresh Page: Refresh the Web UI page after modification
• Check Save Status: Confirm the configuration was saved successfully (check prompt messages)
• Restart Service: Some configurations may require service restart to take effect
• Check Configuration File: Directly check configs/config.json to confirm changes were written

10. API Returns 404

Solutions:

• Check Endpoint Path: Ensure you're using the correct endpoint path, such as /v1/chat/completions etc.
• Check Client Auto-completion: Some clients (like Cherry-Studio, NextChat) automatically append paths (like /v1/chat/completions) after the Base URL, causing path duplication. Check the actual request URL in the console and remove redundant path parts
• Check Service Status: Confirm the service has started normally, visit http://localhost:3000 to view Web UI
• Check Port Configuration: Ensure requests are sent to the correct port (default 3000)
• View Available Routes: Check "Interactive Routing Examples" on the Web UI dashboard page to see all available endpoints

11. Unauthorized: API key is invalid or missing

Problem Description: When calling API endpoints, it returns Unauthorized: API key is invalid or missing. error.

Solutions:

• Check API Key Configuration: Ensure API Key is correctly configured in configs/config.json or Web UI
• Check Request Header Format: Ensure the request contains the correct Authorization header format, such as Authorization: Bearer your-api-key
• Check Service Logs: View detailed error messages on the "Real-time Logs" page in Web UI to locate the specific cause

12. No available and healthy providers for type

Problem Description: When calling API, it returns No available and healthy providers for type xxx error.

Solutions:

• Check Provider Status: Check if providers of the corresponding type are in healthy status on the "Provider Pools" page in Web UI
• Check Credential Validity: Confirm OAuth credentials have not expired; if expired, regenerate authorization
• Check Quota Limits: Some providers may have reached free quota limits; wait for quota reset or add more accounts
• Enable Fallback: Configure providerFallbackChain in config.json to automatically switch to backup providers when the primary provider is unavailable
• View Detailed Logs: Check specific health check failure reasons on the "Real-time Logs" page in Web UI

13. Request Returns 403 Forbidden Error

Problem Description: API requests return 403 Forbidden error.

Solutions:

• Enable TLS Sidecar: For services like Grok, 403 is often due to TLS fingerprint blocking. Please refer to Advanced Configuration - TLS Sidecar to enable and compile the Sidecar.
• Check Node Status: If you see the node status is normal (health check passed) on the "Provider Pools" page in Web UI, you can ignore this error as the system will handle it automatically
• Check Account Permissions: Confirm the account has permission to access the requested model or service
• Check API Key Permissions: Some providers' API Keys may have access scope restrictions; ensure the Key has sufficient permissions
• Check Regional Restrictions: Some services may have regional access restrictions; try using a proxy or VPN
• Check Credential Status: OAuth credentials may have been revoked or expired; try regenerating authorization
• Check Request Frequency: Some providers have strict request frequency limits; reduce request frequency and retry
• View Provider Documentation: Visit the official documentation of the corresponding provider to understand specific access restrictions and requirements

14. Why should I enable "OAuth Token Auto-Refresh"?

Problem Description: Unsure if token auto-refresh is necessary.

Solution: OAuth tokens (e.g., Gemini, Antigravity, Codex) typically have a limited lifespan (e.g., 1 hour).

• With it enabled: The system automatically checks and refreshes tokens before they expire in the background. This ensures 24/7 stable API service and avoids 401 Unauthorized or 403 Forbidden errors due to expired tokens.
• Without it: Once a token expires, the system cannot automatically obtain a new one, causing API requests to fail until you manually re-authorize.

15. What is the impact of not enabling "Preload Model Providers" on token maintenance?

Problem Description: Confusion about the "Preload Model Providers" configuration and its relation to token refresh.

Solution: The system only performs auto-refresh tasks for providers that are loaded into the active pool.

• Impact: If a provider is not checked as a "Preload Model Provider" in the configuration, it won't be initialized when the system starts. Since it's not in the pool, the background refresh task will not process its token.
• Consequence: If you don't use that provider for a long time, its token will expire silently. When you eventually call it via a specific route, the request will fail due to the expired token.
• Recommendation: Always check providers you intend to use frequently and need to keep active in the "Preload Model Providers" list.