GitHub - chenyme/grok2api: Grok2API 是一个基于 FastAPI 构建的 Grok 网关，支持将 Grok Web 能力以 OpenAI 兼容 API 的方式转换。

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`
`ACCOUNT_SYNC_ACTIVE_INTERVAL`	账号目录检测到变化后的活跃同步间隔（秒）	`3`
`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_LOCAL_PATH`	`local` 模式账号 SQLite 路径	`${DATA_DIR}/accounts.db`
`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`
`CONFIG_LOCAL_PATH`	`local` 模式运行时配置文件路径	`${DATA_DIR}/config.toml`

运行时配置也支持 GROK_ 前缀环境变量覆盖，例如 GROK_APP_API_KEY 会覆盖 app.api_key，GROK_FEATURES_STREAM 会覆盖 features.stream。

系统配置项

分组	关键项
`app`	`app_key`, `app_url`, `api_key`, `webui_enabled`, `webui_key`
`logging`	`file_level`, `max_files`
`features`	`temporary`, `memory`, `stream`, `thinking`, `auto_chat_mode_fallback`, `thinking_summary`, `dynamic_statsig`, `enable_nsfw`, `show_search_sources`, `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`
`cache.local`	`image_max_mb`, `video_max_mb`
`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`
`grok-4.20-fast`	`fast`	`basic`，优先使用高等级账号池
`grok-4.20-auto`	`auto`	`basic`，优先使用高等级账号池
`grok-4.20-expert`	`expert`	`basic`，优先使用高等级账号池
`grok-4.20-heavy`	`heavy`	`heavy`
`grok-4.3-beta`	`grok-420-computer-use-sa`	`super`

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/video?id=...`	否	获取本地缓存视频
`GET /v1/files/image?id=...`	否	获取本地缓存图片

接口示例

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

GET /v1/models

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

字段说明

字段	位置	说明
`Authorization`	Header	当 `app.api_key` 非空时必填，格式为 `Bearer <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-auto",
    "stream": true,
    "reasoning_effort": "high",
    "deepsearch": "default",
    "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`	支持文本与多模态内容块
`stream`	是否流式输出；不传时使用 `features.stream` 默认值
`reasoning_effort`	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`；`none` 会关闭思考输出
`deepsearch`	深度搜索预设：`default`, `deeper`
`temperature` / `top_p`	采样参数，默认 `0.8` / `0.95`
`tools`	OpenAI function tools 结构
`tool_choice`	`auto`, `required` 或指定函数工具
`image_config`	图像模型参数
\|_ `n`	`lite` 为 `1-4`，其他图像模型为 `1-10`，编辑模型为 `1-2`
\|_ `size`	`1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024`
\|_ `response_format`	`url`, `b64_json`
`video_config`	视频模型参数
\|_ `seconds`	`6`, `10`, `12`, `16`, `20`
\|_ `size`	`720x1280`, `1280x720`, `1024x1024`, `1024x1792`, `1792x1024`
\|_ `resolution_name`	`480p`, `720p`
\|_ `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-auto",
    "input": "解释一下量子隧穿",
    "instructions": "用简洁的中文回答",
    "stream": true,
    "reasoning": {
      "effort": "high"
    }
  }'

字段说明

字段	说明
`model`	模型 ID，需为已启用模型
`input`	用户输入；支持字符串或 Responses API 风格的消息数组
`instructions`	可选系统指令，会作为 system 消息注入
`stream`	是否流式输出；不传时使用 `features.stream` 默认值
`reasoning`	可选思考配置
\|_ `effort`	`none` 会关闭思考输出；其他值会开启思考输出
`temperature` / `top_p`	采样参数，默认 `0.8` / `0.95`
`tools` / `tool_choice`	支持函数工具；Responses API 的扁平工具格式会自动转换

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-auto",
    "stream": true,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    },
    "messages": [
      {
        "role": "user",
        "content": "用三句话解释量子隧穿"
      }
    ]
  }'

字段说明

字段	说明
`model`	模型 ID，需为已启用模型
`messages`	Anthropic Messages 格式消息，支持文本、图片、文档和工具结果块
`system`	可选系统提示词，支持字符串或文本块数组
`stream`	是否流式输出；不传时使用 `features.stream` 默认值
`thinking`	可选思考配置
\|_ `type`	`disabled` 会关闭思考输出；其他配置会开启思考输出
`max_tokens`	接收但当前会忽略，Grok 上游不暴露该参数
`tools` / `tool_choice`	支持 Anthropic 工具格式，会转换为内部 function tools

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": "1792x1024",
    "response_format": "url"
  }'

字段说明

字段	说明
`model`	图像模型：`grok-imagine-image-lite`, `grok-imagine-image`, `grok-imagine-image-pro`
`prompt`	图片生成提示词
`n`	生成数量；`lite` 为 `1-4`，其他图像模型为 `1-10`
`size`	支持 `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024`
`response_format`	`url` 或 `b64_json`

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"

字段说明

字段	说明
`model`	图像编辑模型，目前为 `grok-imagine-image-edit`
`prompt`	编辑指令
`image[]`	参考图片，multipart 文件字段；最多使用 5 张
`n`	生成数量，范围 `1-2`
`size`	当前仅支持 `1024x1024`
`response_format`	`url` 或 `b64_json`
`mask`	暂不支持；传入会返回校验错误

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" \
  -F "input_reference[]=@/path/to/reference.png"

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

字段说明

字段	说明
`model`	视频模型，目前为 `grok-imagine-video`
`prompt`	视频生成提示词
`seconds`	视频长度：`6`, `10`, `12`, `16`, `20`
`size`	支持 `720x1280`, `1280x720`, `1024x1024`, `1024x1792`, `1792x1024`
`resolution_name`	`480p` 或 `720p`
`preset`	`fun`, `normal`, `spicy`, `custom`
`input_reference[]`	可选图生视频参考图，multipart 文件字段；最多使用前 5 张
`video_id`	`POST /v1/videos` 返回的视频任务 ID，用于查询任务或下载成片

Name		Name	Last commit message	Last commit date
Latest commit History 586 Commits
.github		.github
app		app
docs		docs
scripts		scripts
.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
uv.lock		uv.lock

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 10

Packages

Uh oh!

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

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages