chenyme/grok2api — 7.2k Stars

Topics

#grok #grok-build #grok-console #grok-imagine #grok-video #grok-web

Language breakdown

Go 80.5%

TypeScript 17.7%

Python 1.7%

CSS 0.1%

Dockerfile 0.0%

JavaScript 0.0%

▸ Files click to expand

README

Grok2API

A multi-account API gateway for Grok Build, Grok Web, and Grok Console

English | 简体中文

[!TIP]

Check out DEEIX-AI / DEEIX-Chat, a lightweight, integrated AI platform for model routing, chat, files, tools, billing, identity, and operations.

[!NOTE]

This project is for technical research and learning purposes only. Please comply with Grok's official terms of use and local laws when using it; otherwise, you will be solely responsible for all consequences!

Overview

Grok2API is a Go gateway with a built-in React admin console. It manages independent Grok Build, Grok Web, and Grok Console account pools and exposes unified OpenAI- and Anthropic-compatible APIs.

Architecture

flowchart LR
    %% Color definitions
    classDef access fill:#e1f5fe,stroke:#01579b
    classDef core fill:#fff3e0,stroke:#e65100
    classDef providers fill:#f3e5f5,stroke:#4a148c
    classDef infra fill:#e8f5e9,stroke:#1b5e20
    classDef upstream fill:#fce4ec,stroke:#880e4f
subgraph Access["Access Domain"]         direction LR         Clients["API Clients"]         Admin["React Admin"]     end
subgraph Core["Gateway Core Domain"]         direction LR         Management["Management Services<br/>Accounts · Models · Keys · Settings"]         Sync["Account Sync<br/>Credentials · Quota · Models"]         Gateway["Gateway Service<br/>Protocols · Routing · Selection · Retry"]         Audit["Audit Service<br/>Usage · Client Billing"]         Management --> Sync         Gateway -.-> Audit     end
subgraph Providers["Provider Channel Domain"]         direction LR         Registry["Provider Registry"]         Build["Grok Build<br/>OAuth · Dynamic Models · Billing"]         Web["Grok Web<br/>SSO · Remote Quota · Media"]         Console["Grok Console<br/>SSO · Local Window · Stateless"]         Registry --> Build         Registry --> Web         Registry --> Console     end
subgraph Infra["Shared Infrastructure Domain"]         direction LR         Egress["Egress Manager<br/>Scopes · Proxy Pool · Fallback · Clearance"]         Database[("SQLite / PostgreSQL")]         Runtime[("Memory / Redis")]     end
Upstream["🌐 Grok Upstream"]
%% Cross-domain calls     Clients --> Gateway     Admin --> Management     Gateway --> Registry     Sync --> Registry     Build -->|grok_build| Egress     Web -->|grok_web / asset| Egress     Console -->|grok_console| Egress     Egress --> Upstream     Management --> Database     Audit --> Database     Gateway <--> Runtime
%% Application styles     class Clients,Admin access     class Management,Sync,Gateway,Audit core     class Registry,Build,Web,Console providers     class Egress,Database,Runtime infra     class Upstream upstream

The Gateway routes requests through the Provider Registry. Account Sync refreshes credentials, quota, and models. Each Provider keeps independent account state and uses an isolated egress scope; usage, audits, and client billing are finalized after the request.

Core capabilities

Provider boundaries

Each Provider keeps its own credentials, quota, health, cooldown, concurrency, and model capabilities. Failover stays within the selected Provider.

Quick start

Official images support linux/amd64 and linux/arm64.

git clone https://github.com/chenyme/grok2api.git
cd grok2api
cp config.example.yaml config.yaml

Generate secrets and place them in config.yaml:

openssl rand -hex 32
openssl rand -base64 32

secrets: jwtSecret: "replace-with-the-generated-hex-value" credentialEncryptionKey: "replace-with-the-generated-base64-key"

bootstrapAdmin: username: "admin" password: "replace-with-a-strong-password"

Start the service:

docker compose pull
docker compose up -d
docker compose logs -f grok2api

Open http://127.0.0.1:8000. The image already includes the frontend; SQLite data and local media are stored in the Compose volume.

Run from source

cp config.example.yaml config.yaml
make run

For frontend development:

cd frontend
pnpm install
pnpm dev

Set up the gateway

Sign in with the bootstrap administrator.
Connect a Build, Web, or Console account.
Wait for its quota and model capabilities to sync.
Review the public routes under Model Routes.
Create a client key under Client Keys.
Call a /v1/* endpoint with that key.

After first sign-in, change the administrator password and remove bootstrapAdmin from the configuration. Never rotate credentialEncryptionKey after credentials have been stored.

Account operations

Imports accept UTF-8 BOM. Bulk quota sync, Build credential renewal, Web→Build/Console conversion, account tools, and cleanup report live progress.

Web account tools can accept the terms, set a random birthday corresponding to an age of 20–40, and enable NSFW. Completed steps are recorded and skipped on later runs.

Automatic deletion of old reauthRequired accounts is available but disabled by default. Active inference leases and video jobs are protected.

[!TIP]

To migrate from the Python version, export Grok Web SSO tokens as TXT and import them under Grok Web. Old pool metadata and databases are not compatible.

Models and routing

Build models are discovered from each account's actual capabilities. Web and Console use built-in catalogs. The Model Routes page shows Provider-qualified routes, endpoint capabilities, and supporting-account counts; clients should treat the currently serviceable results from GET /v1/models as authoritative.

Grok Build

Build does not use one global static model list. Account synchronization reads the upstream /models endpoint, and different accounts, subscription tiers, or staged rollouts may expose different models. Routing retains these per-account capabilities instead of replacing the global catalog with one account's response.

Conversation requests are translated to the Build Responses protocol while preserving the tool, reasoning, multi-turn, and prompt-cache compatibility required by Codex and Claude Code. Build currently exposes no image generation or image editing routes.

Grok Web

Web uses a built-in catalog filtered by account tier; higher tiers inherit lower-tier models.

Grok Console

Console uses the catalog built into the current release. Conversation forwarding is stateless, while image and video models use the standard xAI resource APIs.

Generation and editing capabilities for the same Console image model are grouped into one logical model row; no separate -edit model copy is required.

Public names normally omit the Provider. Internally, routes use Build/, Web/, or Console/; qualified names can pin a request to one source.

Web can be weakly linked one-to-one with matching Build and Console accounts. Links share only an anonymous egress identity and provenance display. They never merge credentials, quota, health, cooldown, concurrency, capabilities, or billing.

Codex, Claude Code, and prompt caching

Responses and Messages support streaming, tools, reasoning, multi-turn sessions, and compaction. Stable client session signals are preserved for Grok Build prompt-cache affinity. Cache hits still require a compatible upstream account and an unchanged prompt prefix.

Responses and Chat Completions report OpenAI-style total input. Messages reports Anthropic-style uncached input and cache reads separately. Audits retain total and cached input for billing reconciliation.

API

Inference endpoints use a client key:

Authorization: Bearer g2axxxxxx

| Method | Path | Purpose | | :-- | :-- | :-- | | GET | /healthz, /readyz | Liveness and readiness | | GET | /v1/models | Serviceable models | | POST | /v1/responses | Responses JSON/SSE | | POST | /v1/responses/compact | Compact a supported Response session | | GET, DELETE | /v1/responses/{id} | Read or delete a stored response | | POST | /v1/chat/completions | Chat Completions JSON/SSE | | POST | /v1/messages | Anthropic Messages JSON/SSE | | POST | /v1/images/generations, /v1/images/edits | Generate or edit images | | POST, GET | /v1/videos/* | Create and inspect video jobs | | GET | /v1/media/images/{assetid}, /v1/media/videos/{assetid} | Read archived media |

Stored responses and compact depend on the selected Provider. The signed-in admin console provides live examples at /docs; Swagger is available only when server.swaggerEnabled: true.

Client keys support model allowlists and optional RPM, concurrency, spend, and expiry limits.

curl http://127.0.0.1:8000/v1/responses \
  -H "Authorization: Bearer g2axxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "input": "Explain quantum tunneling in three sentences.",
    "stream": true
  }'

Egress and Cloudflare

Egress nodes are scoped to Build, Web, Console, or Web assets. The admin console supports:

HTTP, HTTPS, SOCKS4/4A, SOCKS5/5H, and Resin
Subscription and text/Base64 import
Batch probes, filtering, deletion, assignment, and balancing
Fallback per scope: none, direct, or a fixed node
Proxy-pool mode without global cooldown after one connection failure
Immediate recovery probes after fixed-proxy transport failures, with per-node coalescing and bounded waiting for fast retry
Optional Egress Quality Guard for active per-node model probes, guarded quarantine, and recovery; enable it with the built-in quality-guard Compose profile

To enable the guard, add a qualityGuard section to config.yaml, then start the profile. The main service creates and reuses a non-exportable system probe identity automatically:

qualityGuard:
  enabled: true
  model: "grok-4.5"

docker compose --profile quality-guard up -d --build

Existing preview deployments that still contain clientKeyID can upgrade directly. The field is accepted for compatibility but ignored and can be removed; any manually created probe key is intentionally left untouched.

After changing this configuration, run docker compose --profile quality-guard restart grok2api egress-quality-guard to reload the base settings; policy edits made in the admin page still hot-reload.

The normal docker compose up -d command does not start the guard or generate probe traffic. The sidecar receives a narrowly scoped internal credential from the main service and never stores or uses the administrator password. See the linked guide before enabling automatic quarantine.

Resin usernames can contain {account}:

socks5h://Default.{account}:RESINPROXYTOKEN@resin:2260

The placeholder becomes a stable anonymous identity. Linked Web, Build, and Console accounts can share it; raw tokens and email addresses are not used.

For managed Web/Console Cloudflare Clearance:

docker compose --profile flaresolverr up -d

Then select FlareSolverr under Runtime Settings → Media & Network → Clearance and use http://flaresolverr:8191.

The egress layer retries only connection failures known to occur before request submission. It does not replay submitted generation requests, authentication failures, exhausted quotas, or upstream rate limits.

When a fixed proxy enters cooldown after a transport failure, grok2api starts an independent connectivity probe immediately. Concurrent failures share one probe. A later request bound to that node waits for at most five seconds, reloads persisted node state after a healthy probe, and continues without waiting for the full cooldown. An unhealthy probe preserves the cooldown. Proxy-pool leases use fresh tunnels, so one rotating exit failure never cools the whole pool. See Immediate egress failure probe and bounded retry for the design and safety invariants.

Configuration and deployment

config.yaml contains startup settings; Provider and operational settings are managed in the admin console and hot-reload unless marked otherwise.

Multi-instance deployments require a unique deployment.instanceID per replica, one shared clusterID, and sharedMedia: true only after the media directory is shared correctly.

PostgreSQL credentials can be injected without storing them in config.yaml:

GROK2APIDATABASEURL='postgresql://user:password@host:5432/grok2api?sslmode=require' docker compose up -d

A non-empty GROK2APIDATABASEURL overrides database.postgres.dsn and automatically selects the postgres driver. An empty value is ignored. Supported URL schemes are postgres:// and postgresql://; SQLAlchemy's postgresql+asyncpg:// form is rejected with a migration hint. The application does not implicitly read the generic DATABASEURL; platforms that provide it can map it explicitly with GROK2APIDATABASEURL: "${DATABASEURL}". Database configuration precedence is built-in defaults, config.yaml, then GROK2APIDATABASEURL. The current CLI has no database override.

Important optional settings:

audit.ledgerMode: observe reports ledger faults; enforce can pause new inference to protect billing integrity.
routing.accountIsolatedConnections: partitions outbound TCP/HTTP pools by account for external L4 or connection-hash load balancers. It is off by default because it increases connections, TLS handshakes, memory, and file-descriptor usage.
routing.segmentedSelectorEnabled: optimizes large account pools while retaining full-planner fallback and atomic guards.
Build response-header timeout and exact-match 403 invalidation rules are hot-reloadable.
Sync latest version applies the validated Grok Build client version and User-Agent.

Production checklist

Use HTTPS and enable auth.secureCookies.
Keep Swagger disabled on public deployments.
Use strong, backed-up secrets; never commit credentials, cookies, exports, or databases.
Back up config.yaml, the database, and media storage.
Use PostgreSQL, Redis, and shared media for multiple instances.
Put a reverse proxy and access controls in front of public deployments.

Development

cd backend
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/grok2api

cd frontend
pnpm install --frozen-lockfile
pnpm lint
pnpm build

Regenerate Swagger after changing public API annotations:

make swagger

Documentation

🔗 More in this category

	Krill AI provides fast, stable API access to GPT, Claude, Gemini, and leading Chinese models, with enterprise customization, invoicing, 7×16 support, and optimized WebSocket connections for faster first-token latency. Register through the exclusive link and use code “grok2api” for 23% off your first Codex package.
	DEEIX-Chat is an open-source, self-hostable AI Chat platform for individuals, teams, and enterprises that need stable, long-term, unified access to multiple models. It brings models, conversations, files, tool calling, and administration together in one deployable and extensible system. Click here to start deploying.
	Right Code is an enterprise-grade AI Agent distribution platform that primarily provides stable access services for Claude Code, Codex, Gemini, and other models. It supports invoicing and dedicated one-to-one assistance for enterprises and teams. Thanks to Right Code for providing token support. Click here to register and get started.
	FennoAI provides enterprise-grade OpenAI/Anthropic-compatible APIs for Codex, Claude Code, and OpenCode, processing hundreds of billions of tokens daily with global business settlement and invoicing. Through the Grok2API exclusive offer, USD 1.99 unlocks USD 50 in Coding Plan credits, plus referral commissions up to 20%.
	Qiniu Cloud AI, Qiniu Cloud’s (02567.HK) enterprise MaaS platform, offers protocol-compatible access to 150+ global models for text, image, audio, video, and files, serving 1.69+ million users. Grok2API registrations through the exclusive link receive 12 million free enterprise tokens or 3 million developer tokens.

Sponsors