Skills

sub2api-opencode

Installation
SKILL.md

Sub2API OpenCode Configuration Guide

Configure Sub2API as an AI provider in OpenCode.

Sub2API is an open-source AI API Gateway (6K+ stars) that converts Antigravity, Claude, OpenAI, and Gemini subscriptions into unified API endpoints. It supports multi-account management, smart scheduling, sticky sessions, token-level billing, and concurrency control.

Official domains: sub2api.org and pincc.ai. Other sites using the Sub2API name may be third-party deployments.

Critical Knowledge

Sub2API Endpoint Architecture

Sub2API exposes different endpoints for different model families and protocols:

Endpoint Path Protocol Model Family SDK to Use
/antigravity/v1/messages Anthropic Messages API Claude (via Antigravity) @ai-sdk/anthropic
/antigravity/v1beta/ Google Generative AI API Gemini (via Antigravity) @ai-sdk/google-generative-ai
/v1/messages Anthropic Messages API Claude (direct/hybrid) @ai-sdk/anthropic
/v1beta/ Google Generative AI API Gemini (direct/hybrid) @ai-sdk/google-generative-ai
/v1/chat/completions OpenAI Chat Completions OpenAI models @ai-sdk/openai-compatible

The #1 Mistake: Wrong SDK

NEVER use @ai-sdk/openai-compatible for Claude or Gemini models on Sub2API. It sends requests to /chat/completions which does not exist on the /antigravity/ path, causing 404 page not found.

Correct SDK mapping:

Model Family npm Package Endpoint Called
Claude @ai-sdk/anthropic /v1/messages
Gemini @ai-sdk/google-generative-ai /v1beta/
OpenAI @ai-sdk/openai-compatible /v1/chat/completions

Hybrid Scheduling Mode

When hybrid scheduling is enabled in Sub2API admin, the general endpoints /v1/messages and /v1beta/ will also route to Antigravity accounts.

Warning: Anthropic Claude and Antigravity Claude cannot be mixed within the same conversation context. Use groups to isolate them.

Configuration Templates

Claude Models via Antigravity (Most Common)

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api-claude/claude-sonnet-4-6",
  "provider": {
    "sub2api-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Sub2API Claude",
      "options": {
        "baseURL": "https://<YOUR_SUB2API_DOMAIN>/antigravity/v1",
        "apiKey": "<YOUR_SUB2API_API_KEY>"
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-6": {
          "name": "Claude Opus 4.6",
          "limit": { "context": 200000, "output": 128000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-6-thinking": {
          "name": "Claude Opus 4.6 (Thinking)",
          "limit": { "context": 200000, "output": 128000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-sonnet-4-5-thinking": {
          "name": "Claude Sonnet 4.5 (Thinking)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-5-thinking": {
          "name": "Claude Opus 4.5 (Thinking)",
          "limit": { "context": 200000, "output": 128000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Gemini Models via Antigravity

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api-gemini/gemini-3-flash",
  "provider": {
    "sub2api-gemini": {
      "npm": "@ai-sdk/google-generative-ai",
      "name": "Sub2API Gemini",
      "options": {
        "baseURL": "https://<YOUR_SUB2API_DOMAIN>/antigravity/v1beta",
        "apiKey": "<YOUR_SUB2API_API_KEY>"
      },
      "models": {
        "gemini-3-flash": {
          "name": "Gemini 3 Flash",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3-pro-low": {
          "name": "Gemini 3 Pro (Low Thinking)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3-pro-high": {
          "name": "Gemini 3 Pro (High Thinking)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3.1-pro-low": {
          "name": "Gemini 3.1 Pro (Low)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3.1-pro-high": {
          "name": "Gemini 3.1 Pro (High)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Both Claude + Gemini (Full Setup)

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api-claude/claude-sonnet-4-6",
  "provider": {
    "sub2api-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Sub2API Claude",
      "options": {
        "baseURL": "https://<YOUR_SUB2API_DOMAIN>/antigravity/v1",
        "apiKey": "<YOUR_SUB2API_API_KEY>"
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-6": {
          "name": "Claude Opus 4.6",
          "limit": { "context": 200000, "output": 128000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-6-thinking": {
          "name": "Claude Opus 4.6 (Thinking)",
          "limit": { "context": 200000, "output": 128000 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    },
    "sub2api-gemini": {
      "npm": "@ai-sdk/google-generative-ai",
      "name": "Sub2API Gemini",
      "options": {
        "baseURL": "https://<YOUR_SUB2API_DOMAIN>/antigravity/v1beta",
        "apiKey": "<YOUR_SUB2API_API_KEY>"
      },
      "models": {
        "gemini-3-flash": {
          "name": "Gemini 3 Flash",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3-pro-high": {
          "name": "Gemini 3 Pro (High Thinking)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Using Environment Variables for API Key (Recommended for Security)

Instead of hardcoding the API key, use OpenCode's {env:VAR_NAME} syntax:

"options": {
  "baseURL": "https://your-sub2api-domain/antigravity/v1",
  "apiKey": "{env:SUB2API_KEY}"
}

Then set the environment variable:

export SUB2API_KEY="sk-your-api-key"

Step-by-Step Setup Process

Step 1: Gather Information

Ask the user for:

  1. Sub2API domain (e.g., sub2api.example.com)
  2. API Key (starts with sk-, get from Sub2API admin panel under "API Keys")
  3. Which models they want to use (Claude, Gemini, or both)
  4. Endpoint type - Antigravity (/antigravity/) or direct (/)

Step 2: Verify Connectivity

Test the API endpoint before configuring:

# Test Claude endpoint (Antigravity)
curl -s "https://<DOMAIN>/antigravity/v1/messages" -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "hi"}], "max_tokens": 10}'

# Test available models
curl -s "https://<DOMAIN>/antigravity/v1/models" \
  -H "Authorization: Bearer <API_KEY>"

# Test Gemini endpoint (Antigravity)
curl -s "https://<DOMAIN>/antigravity/v1beta/models" \
  -H "Authorization: Bearer <API_KEY>"

A successful Claude response returns JSON with "type": "message". If you get 404 page not found, the endpoint path is wrong. If you get 503, all upstream accounts are rate-limited or unavailable.

Step 3: Write Configuration

Use the appropriate template from above. Write to:

  • ~/.config/opencode/opencode.json for global config
  • ./opencode.json for project-specific config

Step 4: Restart and Verify

After saving, restart OpenCode and use /models command to check if Sub2API models appear.

Troubleshooting

Error: "Not Found: 404 page not found"

This is the most common error. Check these in order:

# Check Fix
1 Using @ai-sdk/openai-compatible for Claude? Change npm to @ai-sdk/anthropic
2 Using @ai-sdk/openai-compatible for Gemini? Change npm to @ai-sdk/google-generative-ai
3 baseURL ends with /v1 for Gemini? Change to /v1beta
4 baseURL missing /antigravity? Add /antigravity/v1 or /antigravity/v1beta
5 Using wrong model ID? Check with curl <baseURL>/models

Error: "Service temporarily unavailable" (503)

Sub2API has no available upstream accounts, or all are in cooldown.

Fix: Wait for cooldown, or add more upstream accounts in Sub2API admin.

Error: "Configuration is invalid"

The provider field must be an object {}, never a string.

// WRONG - causes "expected record, received string"
"provider": "google"

// CORRECT
"provider": {
  "sub2api-claude": { ... }
}

Also check for unrecognized top-level keys. All provider definitions must be inside the provider object.

Image/PDF not working

Missing modalities in model config. OpenCode defaults to text-only if not specified.

"modalities": {
  "input": ["text", "image", "pdf"],
  "output": ["text"]
}

Claude Code Plan Mode stuck

Known Sub2API issue: In Claude Code, Plan Mode cannot exit automatically.

Workaround: Press Shift + Tab to manually exit Plan Mode.

Model format: <provider>/<model>

OpenCode's model field uses the format <provider-key>/<model-id>:

{
  "model": "sub2api-claude/claude-sonnet-4-6",
  "provider": {
    "sub2api-claude": { ... }
  }
}

The part before / must match a key inside provider.

Nginx Reverse Proxy

If you use Nginx in front of Sub2API, add this to the http block:

underscores_in_headers on;

Nginx drops headers with underscores by default (e.g. session_id), breaking sticky session routing.

Reference: Sub2API Endpoint Map

Path Purpose Protocol
/antigravity/v1/messages Claude chat (Antigravity accounts) Anthropic
/antigravity/v1/models List available models REST
/antigravity/v1beta/ Gemini chat (Antigravity accounts) Google AI
/v1/messages Claude chat (direct + hybrid) Anthropic
/v1beta/ Gemini chat (direct + hybrid) Google AI
/v1/chat/completions OpenAI chat (if configured) OpenAI

Reference: Claude Code Environment Variables

For Claude Code CLI (not OpenCode), use:

export ANTHROPIC_BASE_URL="https://<YOUR_DOMAIN>/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

Reference: Available Models (Typical Antigravity Setup)

Claude Models

  • claude-sonnet-4-6 - Latest, fast and capable
  • claude-opus-4-6 - Latest, most capable
  • claude-opus-4-6-thinking - With extended thinking
  • claude-sonnet-4-5 - Previous generation
  • claude-sonnet-4-5-thinking - Previous gen with thinking
  • claude-opus-4-5-thinking - Previous gen, most capable with thinking

Gemini Models

  • gemini-3-flash - Latest fast model
  • gemini-3-pro-low / gemini-3-pro-high - Pro with thinking levels
  • gemini-3.1-pro-low / gemini-3.1-pro-high - Latest Pro
  • gemini-3.1-flash-image - Latest image generation
  • gemini-2.5-flash / gemini-2.5-flash-thinking - Previous generation
  • gemini-2.5-flash-image - Image generation

Note: Actual available models depend on your Sub2API instance. Query the models endpoint to check.

Reference Links

Installs
1
Repository
nianyi778/sub2a…de-skill
First Seen
Mar 17, 2026