README.en.md

Grok2API

中文 | English | Docs

Note

This project is for learning and research only. You must comply with Grok Terms of Use and local laws and regulations. Do not use for illegal purposes.

Note

Open source projects welcome everyone's support for secondary development and pull requests, but please retain the original author's and frontend's logos to respect the work of others!

Grok2API rebuilt with FastAPI, fully aligned with the latest web call format. Supports streaming/non-streaming chat, tools call, image generation/editing, video generation/upscale (text-to-video and image-to-video), deep reasoning, token pool concurrency, and automatic load balancing.

Quick Start

Docs

Local

uv sync

uv run granian --interface asgi --host 0.0.0.0 --port 8000 --workers 1 main:app

Docker Compose

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

cd grok2api

docker compose up -d

Docker Compose port variables:

• SERVER_PORT: app listening port inside the container
• HOST_PORT: host-side published port (Docker Compose only)

Tip: mapping follows HOST_PORT:SERVER_PORT - users connect to HOST_PORT, while the app listens on SERVER_PORT inside the container.

Example: HOST_PORT=9000 SERVER_PORT=8011 docker compose up -d, then access http://localhost:9000.

Vercel

Set DATA_DIR=/tmp/data and disable file logs with LOG_FILE_ENABLED=false.

For persistence, use MySQL / Redis / PostgreSQL and set SERVER_STORAGE_TYPE and SERVER_STORAGE_URL.

Render

Render free instances sleep after 15 minutes of inactivity; redeploy/restart will lose data.

For persistence, use MySQL / Redis / PostgreSQL and set SERVER_STORAGE_TYPE and SERVER_STORAGE_URL.

Admin Panel

• Access: http://<host>:<port>/admin (use SERVER_PORT for local run and HOST_PORT for Docker Compose; both default to 8000)
• Default password: grok2api (config app.app_key, recommended to change)

Features:

• Token Management: import/add/delete tokens, view status and quota
• Status Filter: filter by status (active/limited/expired) or NSFW status
• Batch Ops: batch refresh/export/delete/enable NSFW
• NSFW Enable: one-click Unhinged for tokens (proxy or cf_clearance required)
• Config Management: update system config online
• Cache Management: view and clear media cache

Environment Variables

Configure .env

Name	Description	Default	Example
LOG_LEVEL	Log level	INFO	DEBUG
LOG_FILE_ENABLED	Enable file logging	true	false
DATA_DIR	Data dir (config/tokens/locks)	./data	/data
SERVER_HOST	Bind address	0.0.0.0	0.0.0.0
SERVER_PORT	Server port	8000	8000
HOST_PORT	Host published port for Docker Compose	8000	9000
SERVER_WORKERS	Server worker count	1	2
SERVER_STORAGE_TYPE	Storage type (local/redis/mysql/pgsql)	local	pgsql
SERVER_STORAGE_URL	Storage DSN (optional for local)	""	postgresql+asyncpg://user:password@host:5432/db

Cloudflare Workers Bridge Variables

When using Cloudflare Workers as a front bridge layer, you can additionally configure:

Name	Description	Default
CHAT_BRIDGE_BACKEND_URL	Backend base URL for non-stream chat function bridge, e.g. https://your-backend.example.com	""
IMAGINE_BRIDGE_BACKEND_URL	Backend base URL for non-stream imagine function bridge	""
VIDEO_BRIDGE_BACKEND_URL	Backend base URL for non-stream video function bridge	""

Notes:

• These variables are used by the Workers bridge layer only and do not change the Python backend routes themselves.
• The current bridge scope mainly covers the minimal executable flow for function pages.
• If a specific bridge backend URL is not configured, chat / imagine / video fall back to probe or init-only mode.
• When forwarding to the backend, the bridge will try to reuse app.api_key as the backend Bearer token automatically.
• Bridge responses include x-grok2api-*-bridge headers so the frontend can distinguish probe and backend-forward modes.
• If the backend returns trace or rate-limit hints, the bridge also forwards x-grok2api-backend-trace-id and retry-after.

Current bridge mode summary:

• chat: non-stream function-page bridge is available; if no backend URL is configured, it falls back to probe.
• imagine: minimal non-stream function-page bridge is available; without a backend URL it falls back to probe/init-only.
• video: minimal non-stream function-page bridge is available; without a backend URL it falls back to probe/init-only.

Current Stage Status

• Phase I: non-stream chat bridge is complete.
• Phase J: minimal imagine bridge loop is complete.
• Video: minimal non-stream bridge loop is complete.
• Phase K: one round of shared bridge helper / execution-wrapper consolidation is complete.

Phase 1 Light Smoke / Manual Regression Notes

At the end of Phase 1, the following lightweight checks are recommended:

Phase 2 automated smoke (deployment side)

• The Cloudflare Workers deployment workflow already checks: /health, /ready, /meta, /config, and /config/sections.
• If a change touches Worker manifest or bridge runtime metadata, also spot-check /v1/function/manifest after deployment.

Manual regression (function pages)

1. chat page

• The initial status is correct in backend-forward-ready mode.
• The initial status is correct in probe-only mode.
• Send, retry, and regenerate all show consistent bridge success/failure feedback.

1. imagine page

• The initial status is correct in backend-forward-ready mode.
• The status text is correct in init-only / probe fallback modes.
• Probe responses show the accepted-probe hint; backend-forward responses render image results correctly.

1. video page

• The initial status is correct in backend-forward-ready mode.
• The status text is correct in init-only / probe fallback modes.
• Probe responses show the accepted-probe hint; backend-forward responses render video results correctly.

Recorded in this round

• Completed: initial bridge status text on all three function pages is now driven by shared helpers.
• Completed: chat bridge error feedback is unified across send / retry / regenerate.
• Completed: imagine / video probe and backend-forward success states now use shared response-header parsing.
• Completed: a leftover syntax issue in cloudflare/worker-entry.js was fixed so the workspace validates cleanly.

Phase 1 Actual Regression Summary

The following regression and validation results were actually completed in this round:

• Passed: static error checks for _public/static/common/js/admin-auth.js, chat.js, imagine.js, and video.js all returned zero errors.
• Passed: cloudflare/worker-entry.js also returned zero static errors after fixing a leftover syntax fragment.
• Confirmed: the related workspace changes were committed, and the Phase 1 code-consolidation changes are recorded in git history.
• Confirmed: the Cloudflare Workers deployment workflow already defines automated smoke checks for /health, /ready, /meta, /config, and /config/sections.

The following items were not actually executed in this round:

• No fresh Workers deployment smoke run was executed against a live deployment.
• No real browser-based click-through regression was performed for the chat / imagine / video pages.

Conclusion:

• Phase 1 code-level consolidation and static validation are complete.
• To fully close Phase 1, the next step should be either one real deployment smoke run or one recorded browser manual regression pass.

Phase 2 Chat Completion Light Smoke / Manual Regression Notes

At the end of Phase 2, the following lightweight checks are recommended:

Automated smoke (deployment side)

• After Cloudflare Workers deployment, spot-check /health, /ready, /meta, and /v1/function/manifest.
• If chat backend-forward is enabled, also verify the function chat page bootstrap manifest and bridge mode on first load.

Manual regression (chat page)

1. Success path

• Non-stream requests return content correctly in backend-forward-ready mode.
• If a streaming path is still enabled, confirm first chunk arrival, completion state, and post-cancel recovery all behave correctly.

1. Failure / terminal states

• Local duplicate submission lands consistently as a deferred terminal state across assistant message, status bar, and toast.
• User cancellation lands consistently as a cancelled terminal state across assistant message, status bar, and toast.
• First-byte timeout, total timeout, and generic failures land consistently as failure terminal states.

1. Actions and usability

• Recommended retry buttons keep label, icon, badge, title, aria-label, and inline “recommended retry path” text consistent.
• Successful messages keep only copy / edit / feedback, ordered as copy first, edit second, feedback last.
• Failed messages group actions as retry / info / edit, with the recommended retry button visually emphasized.

Phase 2 recorded in this round

• Completed: duplicate / cancelled / failure terminal states in chat now share the same terminal presentation model.
• Completed: toast, status bar, assistant inline text, and retry button title/aria/icon/badge/path text are largely consolidated into one strategy mapping.
• Completed: button ordering, grouping, and visual hierarchy for success vs failure messages were consolidated.

Phase 2 Actual Regression Summary

The following regression and validation results were actually completed in this round:

• Passed: _public/static/function/js/chat.js returned zero static errors.
• Passed: _public/static/function/css/chat.css returned zero static errors.
• Passed: _public/static/i18n/locales/zh.json and en.json returned zero static errors.
• Confirmed: deferred / cancelled / failure terminal states in chat now share one unified presentation object model and application path.
• Confirmed: recommended retry buttons, status text, inline hint text, and major failure toasts are now mostly driven by one shared strategy mapping.

The following items were not actually executed in this round:

• No fresh live-deployment smoke run was executed for Phase 2 Workers / chat behavior.
• No real browser click-through regression was completed for the chat page.
• No live backend verification pass was completed for first-byte timeout, total timeout, cancellation, and duplicate submission behavior.

Conclusion:

• Phase 2 code-level consolidation, interaction-semantic unification, and static validation are close to complete.
• To formally close Phase 2, the next step should be one real deployment smoke run plus one recorded browser manual regression pass for chat.

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

Quotas

• 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-mini	1	Basic/Super	Yes	Yes	-
grok-3-thinking	1	Basic/Super	Yes	Yes	-
grok-4	1	Basic/Super	Yes	Yes	-
grok-4-thinking	1	Basic/Super	Yes	Yes	-
grok-4-heavy	4	Super	Yes	Yes	-
grok-4.1-mini	1	Basic/Super	Yes	Yes	-
grok-4.1-fast	1	Basic/Super	Yes	Yes	-
grok-4.1-expert	4	Basic/Super	Yes	Yes	-
grok-4.1-thinking	4	Basic/Super	Yes	Yes	-
grok-4.20-beta	1	Basic/Super	Yes	Yes	-
grok-imagine-1.0	-	Basic/Super	-	Yes	-
grok-imagine-1.0-fast	-	Basic/Super	-	Yes	-
grok-imagine-1.0-edit	-	Basic/Super	-	Yes	-
grok-imagine-1.0-video	-	Basic/Super	-	-	Yes

API

The examples below use localhost:8000 by default; if you set HOST_PORT in Docker Compose, replace the port accordingly.

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	See model list above
messages	array	Message list	See message format below
stream	boolean	Enable streaming	true, false
reasoning_effort	string	Reasoning effort	none, minimal, low, medium, high, xhigh
temperature	number	Sampling temperature	0 ~ 2
top_p	number	Nucleus sampling	0 ~ 1
tools	array	Tool definitions	OpenAI function tools
tool_choice	string/object	Tool choice	auto, required, none, or a specific tool
parallel_tool_calls	boolean	Allow parallel tool calls	true, false
video_config	object	Video model only	Supported: grok-imagine-1.0-video
└─ aspect_ratio	string	Video aspect ratio	16:9, 9:16, 1:1, 2:3, 3:2, 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
└─ video_length	integer	Video length (seconds)	6 ~ 30
└─ resolution_name	string	Resolution	480p, 720p
└─ preset	string	Style preset	fun, normal, spicy, custom
image_config	object	Image models only	Supported: grok-imagine-1.0 / grok-imagine-1.0-fast / grok-imagine-1.0-edit
└─ n	integer	Number of images	1 ~ 10
└─ size	string	Image size	1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
└─ response_format	string	Response format	url, b64_json, base64

Message format (messages):

Field	Type	Description
role	string	developer, system, user, assistant
content	string/array	Plain text or multimodal array

Multimodal content block types (content array):

type	Description	Example
text	Text	{"type": "text", "text": "Describe this image"}
image_url	Image URL	{"type": "image_url", "image_url": {"url": "https://..."}}
input_audio	Audio	{"type": "input_audio", "input_audio": {"data": "https://..."}}
file	File	{"type": "file", "file": {"file_data": "https://..."}}

Notes:

• image_url/input_audio/file only supports URL or Data URI (data:<mime>;base64,...); raw base64 will be rejected.
• reasoning_effort: none disables thinking output; any other value enables it.
• Tool calling is prompt-based + client-executed: the model emits <tool_call>{...}</tool_call> and the server parses it into tool_calls; tools are not executed server-side.
• grok-imagine-1.0-fast works similarly to the imagine waterfall stream, and can be called directly via /v1/chat/completions. Its n/size/response_format are globally controlled by the server's [imagine_fast] config.
• grok-imagine-1.0-fast streaming output in /chat/completions only returns the final image, hiding intermediate preview images.
• grok-imagine-1.0-fast streaming URL output will retain the original image filename (without appending -final).
• grok-imagine-1.0-edit requires an image; if multiple are provided, the last 3 images and last text are used.
• grok-imagine-1.0-video supports text-to-video and image-to-video via image_url (only the first image is used).
• Any other parameters will be discarded and ignored.

POST /v1/responses

OpenAI Responses API compatible endpoint (subset)

curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4",
    "input": "Explain quantum tunneling",
    "stream": true
  }'

Supported request parameters

Field	Type	Description
model	string	Model ID
input	string/array	Input content (string, message array, or multimodal blocks)
instructions	string	System instructions
stream	boolean	Enable streaming
temperature	number	Sampling temperature
top_p	number	Nucleus sampling
tools	array	Tool definitions (function tools; built-in tool types listed below)
tool_choice	string/object	Tool choice (auto/required/none or a specific tool)
parallel_tool_calls	boolean	Allow parallel tool calls
reasoning	object	Reasoning options (supports effort)
└─ effort	string	Reasoning effort

Notes:

• Built-in tools web_search / file_search / code_interpreter are mapped to function tools for tool call emission only; hosted tool execution is not performed.
• Streaming includes response.output_text.* and response.function_call_arguments.* events.

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	1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
quality	string	Image quality	- (not supported)
response_format	string	Response format	url, b64_json, base64
style	string	Style	- (not supported)

Notes:

• quality and style are OpenAI compatibility placeholders and are not customizable yet.
• If more than 3 images are provided, only the last 3 are used.

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 the image clearer" \
  -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	Source image	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	1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
quality	string	Image quality	- (not supported)
response_format	string	Response format	url, b64_json, base64
style	string	Style	- (not supported)

Notes:

• quality and style are OpenAI compatibility placeholders and are not customizable yet.

POST /v1/videos

Video generation endpoint (OpenAI videos.create compatible)

curl http://localhost:8000/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-1.0-video",
    "prompt": "Neon rainy street at night, cinematic slow tracking shot",
    "size": "1792x1024",
    "seconds": 18,
    "quality": "standard"
  }'

Supported request parameters

Field	Type	Description	Allowed values
model	string	Video model	grok-imagine-1.0-video
prompt	string	Video prompt	-
size	string	Frame size (mapped to aspect_ratio)	1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
seconds	integer	Target duration (seconds)	6 ~ 30
quality	string	Video quality (mapped to resolution)	standard, high
image_reference	object/string	Reference image (optional)	{"image_url":"https://..."} or Data URI
input_reference	file	multipart reference image (optional)	png, jpg, webp

Notes:

• Server-side chain extension now supports 6~30 seconds automatically, so /v1/video/extend is not required.
• quality=standard maps to 480p; quality=high maps to 720p.
• For basic-pool requests at 720p, generation falls back to 480p first, then upscales according to video.upscale_timing.
• If both image_reference and input_reference are provided, references are processed in order; the video pipeline uses the first image only.

Configuration

Config file: data/config.toml

Note

In production or behind a reverse proxy, make sure app.app_url is a publicly accessible URL, otherwise file links may be incorrect or result in 403.

Tip

v2.0 config migration: old configs are automatically migrated. The old [grok] section is mapped into the new config structure.

Module	Field	Key	Description	Default
app	app_url	App URL	External base URL used for file links.	""
	app_key	Admin password	Login password for admin panel.	grok2api
	api_key	API key	Optional API key for access (comma-separated string or array).	""
	function_enabled	Function mode	Enable function pages/features.	false
	function_key	Function key	Access key for function endpoints/pages (optional).	""
	image_format	Image format	url or base64.	url
	video_format	Video format	html or url (processed link).	html
	temporary	Temporary chat	Enable temporary chat mode.	true
	disable_memory	Disable memory	Disable Grok memory.	true
	stream	Stream	Enable streaming by default.	true
	thinking	Thinking	Enable reasoning output by default.	true
	dynamic_statsig	Dynamic statsig	Generate dynamic Statsig values.	true
	custom_instruction	Custom instruction	Multi-line text passed through as Grok customPersonality.	""
	filter_tags	Filter tags	Filter special tags in responses.	["xaiartifact","xai:tool_usage_card","grok:render"]
proxy	base_proxy_url	Base proxy URL	Proxy to Grok web.	""
	asset_proxy_url	Asset proxy URL	Proxy to Grok assets (img/video).	""
	cf_cookies	CF cookies	Full cookie string written by FlareSolverr refresh.	""
	skip_proxy_ssl_verify	Skip proxy SSL verify	Enable when proxy uses a self-signed cert (proxy only; upstream TLS is still verified).	false
	enabled	CF auto refresh	Enable Cloudflare auto refresh.	false
	flaresolverr_url	FlareSolverr URL	FlareSolverr HTTP endpoint.	""
	refresh_interval	Refresh interval	Refresh cf_clearance interval (seconds).	3600
	timeout	Challenge timeout	CF challenge timeout (seconds).	60
	cf_clearance	CF clearance	Cloudflare clearance cookie.	""
	browser	Browser fingerprint	curl_cffi fingerprint (e.g. chrome136).	chrome136
	user_agent	User-Agent	HTTP User-Agent string.	Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36
retry	max_retry	Max retry	Max retries for upstream failures.	3
	retry_status_codes	Retry codes	HTTP status codes that trigger retry.	[401, 429, 403]
	reset_session_status_codes	Reset session codes	HTTP status codes that trigger session reset (proxy rotation).	[403]
	retry_backoff_base	Backoff base	Retry backoff base seconds.	0.5
	retry_backoff_factor	Backoff factor	Exponential backoff factor.	2.0
	retry_backoff_max	Backoff max	Max delay per retry (seconds).	20.0
	retry_budget	Retry budget	Max total retry time (seconds).	60.0
token	auto_refresh	Auto refresh	Enable token auto refresh.	true
	refresh_interval_hours	Refresh interval	Basic token refresh interval (hours).	8
	super_refresh_interval_hours	Super refresh interval	Super token refresh interval (hours).	2
	fail_threshold	Fail threshold	Consecutive failures to disable.	5
	save_delay_ms	Save delay	Merge write delay (ms).	500
	usage_flush_interval_sec	Usage flush interval	Minimum interval to flush usage fields to DB (seconds).	5
	reload_interval_sec	Reload interval	Multi-worker token reload interval (seconds).	30
cache	enable_auto_clean	Auto clean	Enable cache auto cleanup.	true
	limit_mb	Size limit	Cleanup threshold (MB).	512
chat	concurrent	Concurrency	Reverse chat concurrency limit.	50
	timeout	Timeout	Reverse chat timeout (seconds).	60
	stream_timeout	Stream timeout	Stream idle timeout (seconds).	60
image	timeout	Timeout	WebSocket timeout (seconds).	60
	stream_timeout	Stream timeout	WS stream idle timeout (seconds).	60
	final_timeout	Final timeout	Seconds to wait for final image.	15
	blocked_grace_seconds	Blocked grace	Grace seconds for suspected moderation.	10
	nsfw	NSFW	Enable NSFW.	true
	medium_min_bytes	Medium min bytes	Min bytes for medium image.	30000
	final_min_bytes	Final min bytes	Min bytes for final image.	100000
	blocked_parallel_attempts	Parallel attempts	Parallel retries on suspected block.	5
	blocked_parallel_enabled	Parallel enabled	Enable parallel retries.	true
imagine_fast	n	Count	Applies to grok-imagine-1.0-fast only.	1
	size	Size	1280x720 / 720x1280 / 1792x1024 / 1024x1792 / 1024x1024	1024x1024
	response_format	Response format	url / b64_json / base64	url
video	concurrent	Concurrency	Reverse video concurrency limit.	100
	timeout	Timeout	Reverse video timeout (seconds).	60
	stream_timeout	Stream timeout	Stream idle timeout (seconds).	60
	upscale_timing	Upscale timing	Basic-pool 720p upscale mode: single (after each extension round) / complete (after all rounds).	complete
voice	timeout	Timeout	Voice request timeout (seconds).	60
asset	upload_concurrent	Upload concurrency	Upload concurrency.	100
	upload_timeout	Upload timeout	Upload timeout (seconds).	60
	download_concurrent	Download concurrency	Download concurrency.	100
	download_timeout	Download timeout	Download timeout (seconds).	60
	list_concurrent	List concurrency	Asset list concurrency.	100
	list_timeout	List timeout	Asset list timeout (seconds).	60
	list_batch_size	List batch size	Tokens per list batch.	50
	delete_concurrent	Delete concurrency	Asset delete concurrency.	100
	delete_timeout	Delete timeout	Asset delete timeout (seconds).	60
	delete_batch_size	Delete batch size	Tokens per delete batch.	50
nsfw	concurrent	Concurrency	NSFW batch concurrency.	60
	batch_size	Batch size	NSFW batch size.	30
	timeout	Timeout	NSFW timeout (seconds).	60
usage	concurrent	Concurrency	Usage batch concurrency.	100
	batch_size	Batch size	Usage batch size.	50
	timeout	Timeout	Usage timeout (seconds).	60

Star History