GitHub - qoomezhu/grok2api: 基于 FastAPI 重构的 Grok2API，适配最新的Web调用格式，支持流式对话、图像生成、图像编辑、联网搜索、视频生成、深度思考，支持号池并发调用和自动负载均衡。

Note

本项目仅供学习与研究交流。请务必遵循 Grok 的使用条款及当地法律法规，不得用于非法用途！二开与 PR 请保留原作者与前端标识。

Grok2API 是一个基于 FastAPI 构建的 Grok 网关，支持将 Grok Web 能力以 OpenAI 兼容 API 的方式转换。核心特性：

OpenAI 兼容接口：/v1/models、/v1/chat/completions、/v1/responses、/v1/images/generations、/v1/images/edits、/v1/videos、/v1/videos/{video_id}、/v1/videos/{video_id}/content
Anthropic 兼容接口：/v1/messages
支持流式与非流式对话、显式思考输出、函数工具结构透传，以及统一的 token / usage 统计
支持多账号池、层级选号、失败反馈、额度同步与自动维护
支持本地缓存图片、视频与本地代理链接返回
支持文生图、图像编辑、文生视频、图生视频
内置 Admin 后台管理、Web Chat、Masonry 生图、ChatKit 语音页面

服务架构

flowchart LR
    Client["Clients\nOpenAI SDK / curl / Browser"] --> API["FastAPI App"]

    subgraph Products["Products"]
        direction TB
        OpenAI["OpenAI APIs\n/v1/*"]
        Anthropic["Anthropic APIs\n/v1/messages"]
        Web["Web Products\n/admin /webui/*"]
    end

    subgraph Control["Control"]
        direction TB
        Models["Model Registry"]
        Accounts["Account Services"]
        Proxies["Proxy Services"]
    end

    subgraph Dataplane["Dataplane"]
        direction TB
        Reverse["Reverse Protocol + Transport"]
        AccountDP["AccountDirectory"]
        ProxyDP["Proxy Runtime"]
    end

    subgraph Platform["Platform"]
        direction TB
        Tokens["Token Estimation"]
        Storage["Storage"]
        Config["Config Snapshot"]
        Auth["Auth"]
        Log["Logging"]
    end

    API --> OpenAI
    API --> Anthropic
    API --> Web

    OpenAI --> Models
    OpenAI --> AccountDP
    OpenAI --> ProxyDP
    OpenAI --> Reverse
    OpenAI --> Tokens
    OpenAI --> Storage

    Anthropic --> Models
    Anthropic --> AccountDP
    Anthropic --> ProxyDP
    Anthropic --> Reverse
    Anthropic --> Tokens

    Web --> Accounts
    Web --> Config
    Web --> Auth

    Accounts --> AccountDP
    Proxies --> ProxyDP
    Models --> Reverse

快速开始

本地部署

git clone https://github.com/chenyme/grok2api
cd grok2api
cp .env.example .env
uv sync
uv run granian --interface asgi --host 0.0.0.0 --port 8000 --workers 1 app.main:app

Docker Compose

git clone https://github.com/chenyme/grok2api
cd grok2api
cp .env.example .env
docker compose up -d

Vercel

Render

首次启动

修改 app.app_key
设置 app.api_key
设置 app.app_url（否则图片、视频的链接会 403 无权访问）

WebUI

页面入口

页面	路径
Admin 登录页	`/admin/login`
账号管理	`/admin/account`
配置管理	`/admin/config`
缓存管理	`/admin/cache`
WebUI 登录页	`/webui/login`
Web Chat	`/webui/chat`
Masonry	`/webui/masonry`
ChatKit	`/webui/chatkit`

鉴权规则

范围	配置项	规则
`/v1/*`	`app.api_key`	为空则不额外鉴权
`/admin/*`	`app.app_key`	默认值 `grok2api`
`/webui/*`	`app.webui_enabled`, `app.webui_key`	默认关闭；`webui_key` 为空则不额外校验

配置体系

配置分层

位置	用途	生效时机
`.env`	启动前配置	服务启动时
`${DATA_DIR}/config.toml`	运行时配置	保存后即时生效
`config.defaults.toml`	默认模板	首次初始化时

环境变量

变量名	说明	默认值
`TZ`	时区	`Asia/Shanghai`
`LOG_LEVEL`	日志级别	`INFO`
`LOG_FILE_ENABLED`	写入本地文件日志	`true`
`ACCOUNT_SYNC_INTERVAL`	账号目录增量同步间隔（秒）	`30`
`SERVER_HOST`	服务监听地址	`0.0.0.0`
`SERVER_PORT`	服务监听端口	`8000`
`SERVER_WORKERS`	Granian worker 数量	`1`
`HOST_PORT`	Docker Compose 宿主机映射端口	`8000`
`DATA_DIR`	本地数据目录	`./data`
`LOG_DIR`	本地日志目录	`./logs`
`ACCOUNT_STORAGE`	账号存储后端	`local`
`ACCOUNT_REDIS_URL`	`redis` 模式 Redis DSN	`""`
`ACCOUNT_MYSQL_URL`	`mysql` 模式 SQLAlchemy DSN	`""`
`ACCOUNT_POSTGRESQL_URL`	`postgresql` 模式 SQLAlchemy DSN	`""`
`ACCOUNT_SQL_POOL_SIZE`	SQL 连接池核心连接数	`5`
`ACCOUNT_SQL_MAX_OVERFLOW`	SQL 连接池最大溢出连接数	`10`
`ACCOUNT_SQL_POOL_TIMEOUT`	等待连接池空闲连接的超时时间（秒）	`30`
`ACCOUNT_SQL_POOL_RECYCLE`	连接最大复用时间（秒），超时后自动重连	`1800`

系统配置项

分组	关键项
`app`	`app_key`, `app_url`, `api_key`, `webui_enabled`, `webui_key`
`logging`	`file_level`, `max_files`
`features`	`temporary`, `memory`, `stream`, `thinking`, `dynamic_statsig`, `enable_nsfw`, `custom_instruction`, `image_format`, `video_format`
`proxy.egress`	`mode`, `proxy_url`, `proxy_pool`, `resource_proxy_url`, `resource_proxy_pool`, `skip_ssl_verify`
`proxy.clearance`	`mode`, `cf_cookies`, `user_agent`, `browser`, `flaresolverr_url`, `timeout_sec`, `refresh_interval`
`retry`	`reset_session_status_codes`, `max_retries`, `on_codes`
`account.refresh`	`basic_interval_sec`, `super_interval_sec`, `heavy_interval_sec`, `usage_concurrency`, `on_demand_min_interval_sec`
`chat`	`timeout`
`image`	`timeout`, `stream_timeout`
`video`	`timeout`
`voice`	`timeout`
`asset`	`upload_timeout`, `download_timeout`, `list_timeout`, `delete_timeout`
`nsfw`	`timeout`
`batch`	`nsfw_concurrency`, `refresh_concurrency`, `asset_upload_concurrency`, `asset_list_concurrency`, `asset_delete_concurrency`

图片、视频格式

配置项	可选值
`features.image_format`	`grok_url`, `local_url`, `grok_md`, `local_md`, `base64`
`features.video_format`	`grok_url`, `local_url`, `grok_html`, `local_html`

模型支持

可通过 GET /v1/models 获取当前支持模型列表。

Chat

模型名	mode	tier
`grok-4.20-0309-non-reasoning`	`fast`	`basic`
`grok-4.20-0309`	`auto`	`basic`
`grok-4.20-0309-reasoning`	`expert`	`basic`
`grok-4.20-0309-non-reasoning-super`	`fast`	`super`
`grok-4.20-0309-super`	`auto`	`super`
`grok-4.20-0309-reasoning-super`	`expert`	`super`
`grok-4.20-0309-non-reasoning-heavy`	`fast`	`heavy`
`grok-4.20-0309-heavy`	`auto`	`heavy`
`grok-4.20-0309-reasoning-heavy`	`expert`	`heavy`
`grok-4.20-multi-agent-0309`	`heavy`	`heavy`

Image

模型名	mode	tier
`grok-imagine-image-lite`	`fast`	`basic`
`grok-imagine-image`	`auto`	`super`
`grok-imagine-image-pro`	`auto`	`super`

Image Edit

模型名	mode	tier
`grok-imagine-image-edit`	`auto`	`super`

Video

模型名	mode	tier
`grok-imagine-video`	`auto`	`super`

API 一览

接口	是否鉴权	说明
`GET /v1/models`	是	列出当前启用模型
`GET /v1/models/{model_id}`	是	获取单个模型信息
`POST /v1/chat/completions`	是	对话 / 图像 / 视频统一入口
`POST /v1/responses`	是	OpenAI Responses API 兼容子集
`POST /v1/messages`	是	Anthropic Messages API 兼容接口
`POST /v1/images/generations`	是	独立图像生成接口
`POST /v1/images/edits`	是	独立图像编辑接口
`POST /v1/videos`	是	异步视频任务创建
`GET /v1/videos/{video_id}`	是	查询视频任务
`GET /v1/videos/{video_id}/content`	是	获取最终视频文件
`GET /v1/files/image?id=...`	否	获取本地缓存图片
`GET /v1/files/video?id=...`	否	获取本地缓存视频

接口示例

以下示例默认使用 http://localhost:8000 地址。

GET /v1/models

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $GROK2API_API_KEY"

POST /v1/chat/completions

对话：

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

图像：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "stream": true,
    "messages": [
      {"role":"user","content":"一只在太空漂浮的猫"}
    ],
    "image_config": {
      "n": 2,
      "size": "1024x1024",
      "response_format": "url"
    }
  }'

视频：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "stream": true,
    "messages": [
      {"role":"user","content":"霓虹雨夜街头，电影感慢镜头追拍"}
    ],
    "video_config": {
      "seconds": 10,
      "size": "1792x1024",
      "resolution_name": "720p",
      "preset": "normal"
    }
  }'

关键字段：

字段	说明
`messages`	支持文本与多模态内容块
`thinking`	是否显式输出思考过程
`reasoning_effort`	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`
`tools`	OpenAI function tools 结构
`image_config.n`	`lite` 为 `1-4`，其他图像模型为 `1-10`，编辑模型为 `1-2`
`image_config.size`	`1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024`
`video_config.seconds`	`6`, `10`, `12`, `16`, `20`
`video_config.size`	`720x1280`, `1280x720`, `1024x1024`, `1024x1792`, `1792x1024`
`video_config.resolution_name`	`480p`, `720p`
`video_config.preset`	`fun`, `normal`, `spicy`, `custom`

POST /v1/responses

curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4.20-0309",
    "input": "解释一下量子隧穿",
    "stream": true
  }'

POST /v1/messages

curl http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4.20-0309",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "用三句话解释量子隧穿"
      }
    ]
  }'

POST /v1/images/generations

curl http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "一只在太空漂浮的猫",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

POST /v1/images/edits

curl http://localhost:8000/v1/images/edits \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -F "model=grok-imagine-image-edit" \
  -F "prompt=把这张图变清晰一些" \
  -F "image[]=@/path/to/image.png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "response_format=url"

POST /v1/videos

curl http://localhost:8000/v1/videos \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -F "model=grok-imagine-video" \
  -F "prompt=霓虹雨夜街头，电影感慢镜头追拍" \
  -F "seconds=10" \
  -F "size=1792x1024" \
  -F "resolution_name=720p" \
  -F "preset=normal"

curl http://localhost:8000/v1/videos/<video_id> \
  -H "Authorization: Bearer $GROK2API_API_KEY"

curl -L http://localhost:8000/v1/videos/<video_id>/content \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -o result.mp4

Name		Name	Last commit message	Last commit date
Latest commit History 503 Commits
.github		.github
app		app
docs		docs
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
config.defaults.toml		config.defaults.toml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
render.yaml		render.yaml
uv.lock		uv.lock
vercel.json		vercel.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

服务架构

快速开始

本地部署

Docker Compose

Vercel

Render

首次启动

WebUI

页面入口

鉴权规则

配置体系

配置分层

环境变量

系统配置项

图片、视频格式

模型支持

Chat

Image

Image Edit

Video

API 一览

接口示例

Star History

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

服务架构

快速开始

本地部署

Docker Compose

Vercel

Render

首次启动

WebUI

页面入口

鉴权规则

配置体系

配置分层

环境变量

系统配置项

图片、视频格式

模型支持

Chat

Image

Image Edit

Video

API 一览

接口示例

Star History

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages