okooooooo/grok2api

0 Fork 0

Files

T

History

Chenyme b47d847e88 docs: support vercel deploy

2026-02-08 00:10:54 +08:00

README.en.md

docs: support vercel deploy

2026-02-08 00:10:54 +08:00

README.en.md

Grok2API

中文 | English

Note

This project is for learning and research only. You must comply with Grok's Terms of Use and applicable laws. Do not use it for illegal purposes.

Grok2API rebuilt with FastAPI, fully aligned with the latest web call format. Supports streaming and non-streaming chat, image generation/editing, deep thinking, token pool concurrency, and automatic load balancing.

Usage

How to start

Local development

uv sync

uv run main.py

Deployment

git clone https://github.com/chenyme/grok2api

docker compose up -d

One-click deploy (Render)

Render free instances spin down after 15 minutes of inactivity; data is lost on resume/restart/redeploy.

For persistence, use MySQL / Redis / PostgreSQL, on Render set: SERVER_STORAGE_TYPE (mysql/redis/pgsql) and SERVER_STORAGE_URL.

Vercel Deployment

Make sure to set DATA_DIR=/tmp/data and disable file logging (LOG_FILE_ENABLED=false).

For persistence, use MySQL / Redis / PostgreSQL. On Vercel set: SERVER_STORAGE_TYPE (mysql/redis/pgsql) and SERVER_STORAGE_URL.

Render Deployment

Render free instances spin down after 15 minutes of inactivity; data is lost on resume/restart/redeploy.

For persistence, use MySQL / Redis / PostgreSQL. On Render set: SERVER_STORAGE_TYPE (mysql/redis/pgsql) and SERVER_STORAGE_URL.

Admin panel

URL: http://<host>:8000/admin
Default password: grok2api (config key app.app_key, change it in production).

Environment variables

Variable	Description	Default	Example
`LOG_LEVEL`	Log level	`INFO`	`DEBUG`
`LOG_FILE_ENABLED`	Enable file logging	`true`	`false`
`DATA_DIR`	Data directory (config/tokens/locks)	`./data`	`/data`
`SERVER_HOST`	Bind address	`0.0.0.0`	`0.0.0.0`
`SERVER_PORT`	Service port	`8000`	`8000`
`SERVER_WORKERS`	Uvicorn worker count	`1`	`2`
`SERVER_STORAGE_TYPE`	Storage type (`local`/`redis`/`mysql`/`pgsql`)	`local`	`pgsql`
`SERVER_STORAGE_URL`	Storage URL (empty for local)	`""`	`postgresql+asyncpg://user:password@host:5432/db`

MySQL example: mysql+aiomysql://user:password@host:3306/db (if you set mysql://, it will be normalized to mysql+aiomysql://)

Usage limits

Basic account: 80 requests / 20h
Super account: 140 requests / 2h

Models

Model	Cost	Account	Chat	Image	Video
`grok-3`	1	Basic/Super	Yes	Yes	-
`grok-3-fast`	1	Basic/Super	Yes	Yes	-
`grok-4`	1	Basic/Super	Yes	Yes	-
`grok-4-mini`	1	Basic/Super	Yes	Yes	-
`grok-4-fast`	1	Basic/Super	Yes	Yes	-
`grok-4-heavy`	4	Super	Yes	Yes	-
`grok-4.1`	1	Basic/Super	Yes	Yes	-
`grok-4.1-thinking`	4	Basic/Super	Yes	Yes	-
`grok-imagine-1.0`	4	Basic/Super	-	Yes	-
`grok-imagine-1.0-edit`	4	Basic/Super	-	Yes	-
`grok-imagine-1.0-video`	-	Basic/Super	-	-	Yes

API

`POST /v1/chat/completions`

Generic endpoint: chat, image generation, image editing, video generation, video upscaling

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4",
    "messages": [{"role":"user","content":"Hello"}]
  }'

Supported request parameters

Field	Type	Description	Allowed values
`model`	string	Model ID	-
`messages`	array	Message list	`developer`, `system`, `user`, `assistant`
`stream`	boolean	Enable streaming	`true`, `false`
`thinking`	string	Thinking mode	`enabled`, `disabled`, `null`
`video_config`	object	Video model only	-
└─ `aspect_ratio`	string	Video aspect ratio	`16:9`, `9:16`, `1:1`, `2:3`, `3:2`
└─ `video_length`	integer	Video length (seconds)	`6`, `10`, `15`
└─ `resolution_name`	string	Resolution	`480p`, `720p`
└─ `preset`	string	Style preset	`fun`, `normal`, `spicy`

Note: any other parameters will be discarded and ignored.

`POST /v1/images/generations`

Image generation endpoint

curl http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-1.0",
    "prompt": "A cat floating in space",
    "n": 1
  }'

Supported request parameters

Field	Type	Description	Allowed values
`model`	string	Image model ID	`grok-imagine-1.0`
`prompt`	string	Prompt	-
`n`	integer	Number of images	`1` - `10` (streaming: `1` or `2` only)
`stream`	boolean	Enable streaming	`true`, `false`
`size`	string	Image size	`1024x1024` (WS mode maps to aspect ratio)
`quality`	string	Image quality	`standard` (not customizable yet)
`response_format`	string	Response format	`url`, `b64_json`
`style`	string	Style	- (not supported yet)

Note: when grok.image_ws=true, size is mapped to aspect ratio (only 5 supported: 16:9, 9:16, 1:1, 2:3, 3:2); you can also pass those ratio strings directly:
1024x576/1280x720/1536x864 -> 16:9, 576x1024/720x1280/864x1536 -> 9:16, 1024x1024/512x512 -> 1:1, 1024x1536/512x768/768x1024 -> 2:3, 1536x1024/768x512/1024x768 -> 3:2, otherwise defaults to 2:3. Other parameters are ignored.

`POST /v1/images/edits`

Image edit endpoint (multipart/form-data)

curl http://localhost:8000/v1/images/edits \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -F "model=grok-imagine-1.0-edit" \
  -F "prompt=Make it sharper" \
  -F "image=@/path/to/image.png" \
  -F "n=1"

Supported request parameters

Field	Type	Description	Allowed values
`model`	string	Image model ID	`grok-imagine-1.0-edit`
`prompt`	string	Edit prompt	-
`image`	file	Image file	`png`, `jpg`, `webp`
`n`	integer	Number of images	`1` - `10` (streaming: `1` or `2` only)
`stream`	boolean	Enable streaming	`true`, `false`
`size`	string	Image size	`1024x1024` (not customizable yet)
`quality`	string	Image quality	`standard` (not customizable yet)
`response_format`	string	Response format	`url`, `b64_json`
`style`	string	Style	- (not supported yet)

Note: size, quality, style are OpenAI compatibility placeholders and are not customizable yet.

Configuration

Config file: data/config.toml

Note

In production or behind a reverse proxy, make sure app.app_url is set to the public URL. Otherwise file links may be incorrect or return 403.

Tip

v2.0 Config Upgrade: Existing users will have their config auto-migrated to the new structure upon update. Custom values from the old [grok] section will be automatically mapped to the corresponding new sections.

Module	Field	Key	Description	Default
app	`app_url`	App URL	External access URL for Grok2API (used for file links).	`http://127.0.0.1:8000`
	`app_key`	Admin password	Password for the Grok2API admin panel (required).	`grok2api`
	`api_key`	API key	Token for calling Grok2API (optional).	`""`
	`image_format`	Image format	Output image format (`url` or `base64`).	`url`
	`video_format`	Video format	Output video format (html tag or processed url).	`html`
network	`timeout`	Request timeout	Timeout for Grok requests (seconds).	`120`
	`base_proxy_url`	Base proxy URL	Base service address proxying Grok official site.	`""`
	`asset_proxy_url`	Asset proxy URL	Proxy URL for Grok static assets (images/videos).	`""`
security	`cf_clearance`	CF Clearance	Cloudflare clearance cookie for bypassing anti-bot.	`""`
	`browser`	Browser fingerprint	curl_cffi browser fingerprint (e.g. chrome136).	`chrome136`
	`user_agent`	User-Agent	HTTP User-Agent string.	`Mozilla/5.0 (Macintosh; ...)`
chat	`temporary`	Temporary chat	Enable temporary conversation mode.	`true`
	`disable_memory`	Disable memory	Disable Grok memory to prevent irrelevant context.	`true`
	`stream`	Streaming	Enable streaming by default.	`true`
	`thinking`	Thinking chain	Enable model thinking output.	`true`
	`dynamic_statsig`	Dynamic fingerprint	Enable dynamic Statsig value generation.	`true`
	`filter_tags`	Filter tags	Auto-filter special tags in Grok responses.	`["xaiartifact", "xai:tool_usage_card", "grok:render"]`
retry	`max_retry`	Max retries	Max retries on Grok request failure.	`3`
	`retry_status_codes`	Retry status codes	HTTP status codes that trigger retry.	`[401, 429, 403]`
	`retry_backoff_base`	Backoff base	Base delay for retry backoff (seconds).	`0.5`
	`retry_backoff_factor`	Backoff factor	Exponential multiplier for retry backoff.	`2.0`
	`retry_backoff_max`	Backoff max	Max wait per retry (seconds).	`30.0`
	`retry_budget`	Backoff budget	Max total retry time per request (seconds).	`90.0`
timeout	`stream_idle_timeout`	Stream idle timeout	Idle timeout for streaming responses (seconds).	`120.0`
	`video_idle_timeout`	Video idle timeout	Idle timeout for video generation (seconds).	`90.0`
image	`image_ws`	WebSocket generation	When enabled, `/v1/images/generations` uses WebSocket.	`true`
	`image_ws_nsfw`	NSFW mode	Enable NSFW in WebSocket requests.	`true`
	`image_ws_blocked_seconds`	Blocked threshold	Mark blocked if no final image after this many seconds post-medium.	`15`
	`image_ws_final_min_bytes`	Final min bytes	Minimum bytes to treat an image as final (JPG usually > 100KB).	`100000`
	`image_ws_medium_min_bytes`	Medium min bytes	Minimum bytes for medium quality image.	`30000`
token	`auto_refresh`	Auto refresh	Enable automatic token refresh.	`true`
	`refresh_interval_hours`	Refresh interval	Regular token refresh interval (hours).	`8`
	`super_refresh_interval_hours`	Super refresh interval	Super token refresh interval (hours).	`2`
	`fail_threshold`	Failure threshold	Consecutive failures before a token is disabled.	`5`
	`save_delay_ms`	Save delay	Debounced save delay for token changes (ms).	`500`
	`reload_interval_sec`	Sync interval	Token state refresh interval in multi-worker setups (sec).	`30`
cache	`enable_auto_clean`	Auto clean	Enable cache auto clean; cleanup when exceeding limit.	`true`
	`limit_mb`	Cleanup threshold	Cache size threshold (MB) that triggers cleanup.	`1024`
performance	`media_max_concurrent`	Media concurrency	Concurrency cap for video/media generation. Recommended 50.	`50`
	`assets_max_concurrent`	Assets concurrency	Concurrency cap for batch asset find/delete. Recommended 25.	`25`
	`assets_batch_size`	Assets batch size	Batch size for asset find/delete. Recommended 10.	`10`
	`assets_max_tokens`	Assets max tokens	Max tokens per asset find/delete batch. Recommended 1000.	`1000`
	`assets_delete_batch_size`	Assets delete batch	Batch concurrency for single-account asset deletion. Recommended 10.	`10`
	`usage_max_concurrent`	Token refresh concurrency	Concurrency cap for batch usage refresh. Recommended 25.	`25`
	`usage_batch_size`	Token refresh batch size	Batch size for usage refresh. Recommended 50.	`50`
	`usage_max_tokens`	Token refresh max tokens	Max tokens per usage refresh batch. Recommended 1000.	`1000`
	`nsfw_max_concurrent`	NSFW enable concurrency	Concurrency cap for enabling NSFW in batch. Recommended 10.	`10`
	`nsfw_batch_size`	NSFW enable batch size	Batch size for enabling NSFW. Recommended 50.	`50`
	`nsfw_max_tokens`	NSFW enable max tokens	Max tokens per NSFW batch to avoid mistakes. Recommended 1000.	`1000`

README.en.md

Grok2API

Usage

How to start

One-click deploy (Render)

Vercel Deployment

Render Deployment

Admin panel

Environment variables

Usage limits

Models

API

POST /v1/chat/completions

POST /v1/images/generations

POST /v1/images/edits

Configuration

Star History

`POST /v1/chat/completions`

`POST /v1/images/generations`

`POST /v1/images/edits`