grok2api/docs/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

Star History