Grok2API Documentation

The frontend project is organized into the following directory structure:

• src/app/: Routing and application shell.
• src/features/: Pages and interactions organized by business capability.
• src/entities/: Domain DTOs and query interfaces.
• src/shared/: API, authentication, configuration, components, and general utilities.
• src/components/ui/: Base components from shadcn/ui.

Key Patterns:

• All business requests are unified through shared/api.
• Server state is managed by TanStack Query.
• Pages compose business capabilities and do not directly maintain repetitive request, authentication, or formatting logic.

To get Grok2API running quickly using Docker, clone the repository, prepare the configuration file, and generate necessary secrets. The official images support linux/amd64 and linux/arm64 architectures.

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

# Generate secrets
openssl rand -hex 32
openssl rand -base64 32

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

All inference endpoints require a client key passed via the Authorization header using the Bearer scheme.

Header Format: Authorization: Bearer g2a_xxx_xxx

Client keys can be configured with model allowlists and optional limits for RPM (Requests Per Minute), concurrency, spend, and expiry.

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

To create a production build of the frontend, run the pnpm build command. The build output is placed in the dist/ directory.

Note: The backend hosts this directory using the frontend.staticPath configuration from the root config. The backend also provides SPA fallback for non-API paths. The frontend does not read raw YAML files; instead, public runtime information is provided via backend-controlled interfaces.

If you have modified public API annotations, use the following command to regenerate the Swagger documentation.

make swagger

If you modify the comments on public interface definitions, you must regenerate the Swagger documentation. Run the following command from the repository root to update backend/docs/docs.go, swagger.json, and swagger.yaml.

Note: For production environments, ensure server.swaggerEnabled is set to false.

make swagger

To set up the development environment, follow these steps for the backend and frontend packages.

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

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

To verify the backend and frontend environments during development, run the following commands:

Backend:

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

Frontend:

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

API Documentation: To regenerate Swagger documentation after modifying public API comments, use:

make swagger

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

# Frontend verification
cd frontend
pnpm install --frozen-lockfile
pnpm lint
pnpm build

# Regenerate Swagger
make swagger

The gateway supports importing and exporting accounts for different providers:

Key Features:

• Web Account Tools: Supports setting random birthdays (20–40 years old) and enabling NSFW.
• Auto-Cleanup: The system can automatically delete accounts stuck in reauthRequired status (disabled by default). It will not delete accounts with active reasoning leases or video tasks.
• Migration: When migrating from a Python version, export Grok Web SSO as TXT and import it into "Grok Web".

To automatically maintain Cloudflare Clearance for Web and Console nodes, you can use FlareSolverr.

1. Start the FlareSolverr service using Docker Compose:

   docker compose --profile flaresolverr up -d

2. In the management interface, navigate to 运行设置 (Runtime Settings) → 媒体与网络 (Media & Network) → Clearance.
3. Select FlareSolverr as the method.
4. Set the address to http://flaresolverr:8191.

Choose your deployment type based on your scaling requirements:

Multi-instance requirements:

• Each replica must have a unique deployment.instanceID.
• All replicas must share one clusterID.
• Set sharedMedia: true only after the media directory is correctly shared across instances.

If you prefer running from source, use make for the backend and pnpm for the frontend.

Backend:

cp config.example.yaml config.yaml
make run

Frontend (Development):

cd frontend
pnpm install
pnpm dev