SKILL.md

name	sub2api-opencode
description	Configure Sub2API as a provider in OpenCode. Use when setting up sub2api proxy, configuring antigravity endpoints, or connecting Claude/Gemini models through sub2api gateway in opencode.json. Handles provider setup, model registration, endpoint routing, and troubleshooting 404 errors.

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:

Sub2API domain (e.g., sub2api.example.com)
API Key (starts with sk-, get from Sub2API admin panel under "API Keys")
Which models they want to use (Claude, Gemini, or both)
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

Sub2API GitHub: https://github.com/Wei-Shaw/sub2api
Sub2API Demo: https://demo.sub2api.org/
OpenCode Docs: https://opencode.ai/docs
OpenCode Provider Config: https://opencode.ai/docs/providers/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sub2API OpenCode Configuration Guide

Critical Knowledge

Sub2API Endpoint Architecture

The #1 Mistake: Wrong SDK

Hybrid Scheduling Mode

Configuration Templates

Claude Models via Antigravity (Most Common)

Gemini Models via Antigravity

Both Claude + Gemini (Full Setup)

Using Environment Variables for API Key (Recommended for Security)

Step-by-Step Setup Process

Step 1: Gather Information

Step 2: Verify Connectivity

Step 3: Write Configuration

Step 4: Restart and Verify

Troubleshooting

Error: "Not Found: 404 page not found"

Error: "Service temporarily unavailable" (503)

Error: "Configuration is invalid"

Image/PDF not working

Claude Code Plan Mode stuck

Model format: `<provider>/<model>`

Nginx Reverse Proxy

Reference: Sub2API Endpoint Map

Reference: Claude Code Environment Variables

Reference: Available Models (Typical Antigravity Setup)

Claude Models

Gemini Models

Reference Links

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

Sub2API OpenCode Configuration Guide

Critical Knowledge

Sub2API Endpoint Architecture

The #1 Mistake: Wrong SDK

Hybrid Scheduling Mode

Configuration Templates

Claude Models via Antigravity (Most Common)

Gemini Models via Antigravity

Both Claude + Gemini (Full Setup)

Using Environment Variables for API Key (Recommended for Security)

Step-by-Step Setup Process

Step 1: Gather Information

Step 2: Verify Connectivity

Step 3: Write Configuration

Step 4: Restart and Verify

Troubleshooting

Error: "Not Found: 404 page not found"

Error: "Service temporarily unavailable" (503)

Error: "Configuration is invalid"

Image/PDF not working

Claude Code Plan Mode stuck

Model format: <provider>/<model>

Nginx Reverse Proxy

Reference: Sub2API Endpoint Map

Reference: Claude Code Environment Variables

Reference: Available Models (Typical Antigravity Setup)

Claude Models

Gemini Models

Reference Links

Model format: `<provider>/<model>`