aistudio-to-api

Custom models and their behaviors can be configured in configs/models.json. You can also override settings by appending suffixes to the model name.

Suffix Order

When using multiple suffixes, they must follow this specific order: Thinking $\rightarrow$ Streaming $\rightarrow$ Built-in Tools.

Supported Suffixes

1. Thinking Level: -THINKING_LEVEL or (THINKING_LEVEL). Supported values: high, low, medium, minimal.
2. Streaming Mode: -real or -fake. (Note: This suffix has higher priority than the system-wide STREAMING_MODE but only affects streaming requests).
3. Built-in Tools:
   • -search: Forces web search.
   • -code: Forces code execution.

Examples

• gemini-3-flash-preview(minimal)-fake-search-code (Thinking + Fake Streaming + Search + Code)
• gemini-3-flash-preview-minimal-search (Thinking + Search)
• gemini-3-flash-preview-real-code (Real Streaming + Code)

To access the aistudio-to-api service via a domain name or to enable HTTPS and load balancing, use Nginx as a reverse proxy.

When configuring the location / block, ensure you include the following critical settings:

• client_max_body_size 0; to allow large request bodies.
• proxy_pass http://127.0.0.1:7860; to point to the service container.
• proxy_buffering off; to support streaming AI responses.
• WebSocket support (using Upgrade and Connection headers) to enable VNC access.
• Extended timeout settings (proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout) set to 600s to accommodate long-running AI requests.

server {
    listen 80;
    listen [::]:80;  # IPv6 support
    server_name your-domain.com;  # Replace with your domain

    # For HTTPS, uncomment the following lines and configure SSL certificates
    # listen 443 ssl http2;
    # listen [::]:443 ssl http2;  # IPv6 HTTPS
    # ssl_certificate /path/to/your/certificate.crt;
    # ssl_certificate_key /path/to/your/private.key;

    # Client request body size limit (0 = unlimited)
    client_max_body_size 0;

    location / {
        # Reverse proxy to Docker container
        proxy_pass http://127.0.0.1:7860;

        # Critical: Pass real client IP
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # Other necessary proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout settings (adapted for long-running AI requests)
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;

        # Disable buffering to support streaming responses
        proxy_buffering off;

        # WebSocket support (required to access VNC)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

If your architecture involves multiple Nginx proxies (e.g., Client $\rightarrow$ Public Gateway $\rightarrow$ Internal Gateway $\rightarrow$ App), you must handle the X-Real-IP header carefully to avoid losing the original client IP.

• Outermost Public Gateway: Use proxy_set_header X-Real-IP $remote_addr; to capture the actual client IP.
• Inner Proxies: Do NOT use $remote_addr. Instead, pass through the existing header using proxy_set_header X-Real-IP $http_x_real_ip;.

# Inner Nginx (internal gateway) configuration example
location / {
    proxy_pass http://127.0.0.1:7860;

    # Critical: Pass through upstream X-Real-IP, do NOT override with $remote_addr
    proxy_set_header X-Real-IP $http_x_real_ip;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # Other necessary proxy headers
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Timeout settings
    proxy_connect_timeout 600s;
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;

    # Disable buffering
    proxy_buffering off;

    # WebSocket support (required to access VNC)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

Docker deployment is recommended as it allows for VNC-based account management via the Web Console.

Using Docker CLI

docker run -d \
  --name aistudio-to-api \
  -p 7860:7860 \
  -v /path/to/auth:/app/configs/auth \
  -v /path/to/data:/app/data \
  -e API_KEYS=your-api-key-1,your-api-key-2 \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  ghcr.io/ibuhub/aistudio-to-api:latest

Using Docker Compose

Create a docker-compose.yml file:

name: aistudio-to-api
services:
  app:
    image: ghcr.io/ibuhub/aistudio-to-api:latest
    container_name: aistudio-to-api
    ports:
      - 7860:7860
    restart: unless-stopped
    volumes:
      - ./auth:/app/configs/auth
      - ./data:/app/data
    environment:
      API_KEYS: your-api-key-1,your-api-key-2
      TZ: Asia/Shanghai

Parameter Reference

• -p 7860:7860: API server port. If using a reverse proxy, it is highly recommended to use 127.0.0.1:7860.
• -v /path/to/auth:/app/configs/auth: Mount directory containing authentication files.
• -v /path/to/data:/app/data: Mount directory for persisting usage statistics (/app/data/usage-stats.jsonl).
• -e API_KEYS: List of API keys for authentication, separated by commas.
• -e TZ: Timezone setting (e.g., Asia/Shanghai).