基于 FastAPI 构建的 Grok2API,支持将 Grok.com 的 Web 端服务一键转换为 OpenAI API 兼容的调用格式。项目支持原生流式对话、非流式对话、图像生成、图像编辑、视频生成、工具调用、语音聊天、一键NSFW、号池并发与自动负载均衡一体化,且提供后台管理、功能玩法等 WebUI,方便小白快速上手。
本项目仅供学习、研究和技术交流之用。请务必遵循 Grok 的 使用条款 以及 法律法规,不得用于非法用途,使用者须自行承担一切风险,本项目作者概不负责。
修改.env或docker-compose.yml文件生效
变量名 | 说明 | 默认值 | 示例 |
|---|---|---|---|
LOG_LEVEL | 日志级别 | INFO | DEBUG |
LOG_FILE_ENABLED | 启用日志文件 | true | false |
DATA_DIR | 数据存放路径 | ./data | /data |
SERVER_HOST | 服务监听地址 | 0.0.0.0 | 0.0.0.0 |
SERVER_PORT | 服务端口 | 8000 | 8000 |
HOST_PORT | Docker Compose 宿主机映射端口 | 8000 | 9000 |
SERVER_WORKERS | Uvicorn worker 数量 | 1 | 2 |
SERVER_STORAGE_TYPE | 存储类型,支持 local/redis/mysql/pgsql | local | pgsql |
SERVER_STORAGE_URL | 存储连接串,存储类型为 local 时可为空 | "" | postgresql+asyncpg://user:password@host:5432/db |
git clone https://github.com/chenyme/grok2api
uv sync
uv run granian --interface asgi main:appgit clone https://github.com/chenyme/grok2api
cd grok2api
docker compose up -dservices:
grok2api:
container_name: grok2api
image: ghcr.io/chenyme/grok2api:latest
ports:
- "${HOST_PORT:-8000}:${SERVER_PORT:-8000}"
environment:
TZ: Asia/Shanghai
LOG_LEVEL: ${LOG_LEVEL:-INFO}
SERVER_HOST: ${SERVER_HOST:-0.0.0.0}
SERVER_PORT: ${SERVER_PORT:-8000}
SERVER_WORKERS: ${SERVER_WORKERS:-1}
SERVER_STORAGE_TYPE: ${SERVER_STORAGE_TYPE:-local}
SERVER_STORAGE_URL: ${SERVER_STORAGE_URL:-}
# 启用 CF 自动刷新: 取消以下三行注释,并取消底部 flaresolverr 服务的注释
# FLARESOLVERR_URL: http://flaresolverr:8191
# CF_REFRESH_INTERVAL: "600"
# CF_TIMEOUT: "60"
# SERVER_STORAGE_TYPE: (local, redis, mysql, pgsql) default: local
# SERVER_STORAGE_URL: (local mode is empty) default: empty
# Redis: redis://localhost:6379/0 or redis://:password@localhost:6379/0
# MySQL: mysql+aiomysql://user:pass@localhost/db
# PgSQL: postgresql+asyncpg://user:pass@localhost/db
command:
- sh
- -c
- >
granian --interface asgi --host "$${SERVER_HOST:-0.0.0.0}"
--port "$${SERVER_PORT:-8000}" --workers "$${SERVER_WORKERS:-1}" main:app
volumes:
- ./data:/app/data
- ./logs:/app/logs
restart: unless-stopped
# 如果出口 IP 不干净,可取消以下注释使用 Warp 作为落地代理
# 启用后将 proxy.base_proxy_url 设为 socks5://warp:1080
# warp:
# container_name: warp
# image: caomingjun/warp:latest
# restart: unless-stopped
# ports:
# - "127.0.0.1:1080:1080"
# environment:
# - WARP_SLEEP=2
# cap_add:
# - NET_ADMIN
# 启用 CF 自动刷新时取消以下注释
# flaresolverr:
# container_name: flaresolverr
# image: ghcr.io/flaresolverr/flaresolverr:latest
# ports:
# - "127.0.0.1:8191:8191"
# environment:
# TZ: Asia/Shanghai
# LOG_LEVEL: info
# restart: unless-stoppedDATA_DIR=/tmp/data LOG_FILE_ENABLED=falseMySQL / Redis / PostgreSQL,并设置:SERVER_STORAGE_TYPE SERVER_STORAGE_URLMySQL / Redis / PostgreSQL,并设置:SERVER_STORAGE_TYPE SERVER_STORAGE_URLhttp://<host>:8000/adminhttp://<host>:8000/(管理后台开启后生效)grok2apiGROK 官方网页更新后并未真实暴露 rate-limits 接口,导致无法准确计算 Token 剩余,请耐心等待官方接口上线,目前自动刷新后会统一更新为剩余 8 次
模型名称 | 调用计次 | 可用账号 | 对话功能 | 图像功能 | 视频功能 |
|---|---|---|---|---|---|
grok-3 | 1 | Basic/Super | 支持 | 支持 | - |
grok-3-mini | 1 | Basic/Super | 支持 | 支持 | - |
grok-3-thinking | 1 | Basic/Super | 支持 | 支持 | - |
grok-4 | 1 | Basic/Super | 支持 | 支持 | - |
grok-4-mini | 1 | Basic/Super | 支持 | 支持 | - |
grok-4-thinking | 1 | Basic/Super | 支持 | 支持 | - |
grok-4-heavy | 4 | Super | 支持 | 支持 | - |
grok-4.1-mini | 1 | Basic/Super | 支持 | 支持 | - |
grok-4.1-fast | 1 | Basic/Super | 支持 | 支持 | - |
grok-4.1-expert | 4 | Basic/Super | 支持 | 支持 | - |
grok-4.1-thinking | 4 | Basic/Super | 支持 | 支持 | - |
grok-4.20-beta | 1 | Basic/Super | 支持 | 支持 | - |
grok-imagine-1.0 | - | Basic/Super | - | 支持 | - |
grok-imagine-1.0-fast | - | Basic/Super | - | 支持 | - |
grok-imagine-1.0-edit | - | Basic/Super | - | 支持 | - |
grok-imagine-1.0-video | - | Basic/Super | - | - | 支持 |
OpenAI Chat Completions API 通用接口,支持聊天对话、图像生成、图像编辑、视频生成
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":"你好"}]
}'字段 | 类型 | 说明 | 可用参数 |
|---|---|---|---|
model | string | 模型名称 | 见上方模型列表 |
messages | array | 消息列表 | 见下方消息格式 |
stream | boolean | 是否开启流式输出 | true, false |
reasoning_effort | string | 推理强度 | none, minimal, low, medium, high, xhigh |
temperature | number | 采样温度 | 0 ~ 2 |
top_p | number | nucleus 采样 | 0 ~ 1 |
tools | array | 工具定义 | OpenAI function tools |
tool_choice | string/object | 工具选择 | auto, required, none 或指定工具 |
parallel_tool_calls | boolean | 是否允许并行工具调用 | true, false |
video_config | object | 视频模型专用配置对象 | 支持: grok-imagine-1.0-video |
└─ aspect_ratio | string | 视频宽高比 | 16:9, 9:16, 1:1, 2:3, 3:2, 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024 |
└─ video_length | integer | 视频时长 (秒) | 6, 10, 15 |
└─ resolution_name | string | 分辨率 | 480p, 720p |
└─ preset | string | 风格预设 | fun, normal, spicy, custom |
image_config | object | 图片模型专用配置对象 | 支持: grok-imagine-1.0 / grok-imagine-1.0-fast / grok-imagine-1.0-edit |
└─ n | integer | 生成数量 | 1 ~ 10 |
└─ size | string | 图片尺寸 | 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024 |
└─ response_format | string | 响应格式 | url, b64_json, base64 |
字段 | 类型 | 说明 |
|---|---|---|
role | string | 角色: developer, system, user, assistant |
content | string/array | 消息内容,支持纯文本或多模态数组 |
type | 说明 | 示例 |
|---|---|---|
text | 文本内容 | {"type": "text", "text": "描述这张图片"} |
image_url | 图片 URL | {"type": "image_url", "image_url": {"url": "https://..."}} |
input_audio | 音频 | {"type": "input_audio", "input_audio": {"data": "https://..."}} |
file | 文件 | {"type": "file", "file": {"file_data": "https://..."}} |
image_url/input_audio/file 仅支持 URL 或 Data URI(data:<mime>;base64,...),裸 base64 会报错。reasoning_effort:none 表示不输出思考,其他值都会输出思考内容。<tool_call>{...}</tool_call> 输出调用请求,服务端解析为 tool_calls;不执行工具。grok-imagine-1.0-fast/v1/chat/completions 调用;其 n/size/response_format 由服务端 [imagine_fast] 统一控制。/v1/chat/completions 的流式输出仅返回最终成图,不返回中间预览图。-final 后缀)。grok-imagine-1.0-edit 必须提供图片,多图默认取最后 3 张与最后一个文本。grok-imagine-1.0-video 支持文生视频与图生视频(通过 image_url 传参考图,仅取第 1 张)。image.blocked_parallel_enabled,服务端会按 image.blocked_parallel_attempts 自动并行补偿生成,并优先使用不同 token;若仍无满足 image.final_min_bytes 的最终图则返回失败。OpenAI Responses API 兼容接口,支持聊天对话、图像生成、图像编辑、视频生成
curl http://localhost:8000/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GROK2API_API_KEY" \
-d '{
"model": "grok-4",
"input": "解释一下量子隧穿",
"stream": true
}'字段 | 类型 | 说明 |
|---|---|---|
model | string | 模型名称 |
input | string/array | 输入内容,支持字符串、消息数组或多模态内容块 |
instructions | string | 系统指令 |
stream | boolean | 是否流式输出 |
temperature | number | 采样温度 |
top_p | number | nucleus 采样 |
tools | array | 工具定义(支持 function 工具;内置工具类型见下方说明) |
tool_choice | string/object | 工具选择(auto/required/none 或指定工具) |
parallel_tool_calls | boolean | 是否允许并行工具调用 |
reasoning | object | 推理参数 |
└─ effort | string | 推理强度 |
web_search / file_search / code_interpreter 目前会映射为 function tool 触发调用,但不执行托管工具,需客户端自行执行并回填。response.output_text.* 与 response.function_call_arguments.* 事件。OpenAI Image Generations API 兼容接口,支持图像生成
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": "一只在太空漂浮的猫",
"n": 1
}'字段 | 类型 | 说明 | 可用参数 |
|---|---|---|---|
model | string | 图像模型名 | grok-imagine-1.0 |
prompt | string | 图像描述提示词 | - |
n | integer | 生成数量 | 1 - 10 (流式模式仅限 1 或 2) |
stream | boolean | 是否开启流式输出 | true, false |
size | string | 图片尺寸 | 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024 |
quality | string | 图片质量 | - (暂不支持) |
response_format | string | 响应格式 | url, b64_json, base64 |
style | string | 风格 | - (暂不支持) |
quality、style 参数为 OpenAI 兼容保留,当前版本暂不支持自定义。OpenAI Image Edits API 兼容接口,支持图像编辑(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=把图片变清晰" \
-F "image=@/path/to/image.png" \
-F "n=1"字段 | 类型 | 说明 | 可用参数 |
|---|---|---|---|
model | string | 图像模型名 | grok-imagine-1.0-edit |
prompt | string | 编辑描述 | - |
image | file | 待编辑图片 | png, jpg, webp |
n | integer | 生成数量 | 1 - 10 (流式模式仅限 1 或 2) |
stream | boolean | 是否开启流式输出 | true, false |
size | string | 图片尺寸 | 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024 |
quality | string | 图片质量 | - (暂不支持) |
response_format | string | 响应格式 | url, b64_json, base64 |
style | string | 风格 | - (暂不支持) |
quality、style 参数为 OpenAI 兼容保留,当前版本暂不支持自定义。OpenAI Videos API 兼容接口,支持视频生成(multipart/form-data)
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": "霓虹雨夜街头,慢镜头追拍",
"size": "1792x1024",
"seconds": 18,
"quality": "standard"
}'字段 | 类型 | 说明 | 可用参数 |
|---|---|---|---|
model | string | 视频模型名 | grok-imagine-1.0-video |
prompt | string | 视频提示词 | - |
size | string | 画面比例(会映射到 aspect_ratio) | 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024 |
seconds | integer | 目标时长(秒) | 6 ~ 30 |
quality | string | 视频质量(映射到 resolution) | standard, high |
image_reference | object/string | 参考图(可选) | {"image_url":"https://..."} 或 Data URI |
input_reference | file | multipart 参考图(可选) | png, jpg, webp |
/v1/video/extend。quality=standard 对应 480p;quality=high 对应 720p。720p 时会先产出 480p 再按 video.upscale_timing 执行超分。image_reference 与 input_reference 同时传入时,会按顺序作为参考图输入;视频链路只使用第 1 张。data/config.tomlv1.0 配置结构升级:旧版本用户更新后,配置会自动迁移到新结构,无需手动修改。 旧的 [grok] 配置节中的自定义值会自动映射到对应的新配置节。模块 | 字段 | 配置名 | 说明 | 默认值 |
|---|---|---|---|---|
app | app_url | 应用地址 | 当前 Grok2API 服务的外部访问 URL,用于文件链接访问。 | "" |
app_key | 后台密码 | 登录 Grok2API 管理后台的密码(必填)。 | grok2api | |
api_key | API 密钥 | 调用 Grok2API 服务的 Token(可选,支持逗号分隔或数组)。 | "" | |
function_enabled | Function 开关 | 是否启用 function 功能玩法。 | false | |
function_key | Function 密钥 | Function 调用密钥(可选)。 | "" | |
image_format | 图片格式 | 生成的图片格式(url 或 base64)。 | url | |
video_format | 视频格式 | 生成的视频格式(html 或 url,url 为处理后的链接)。 | html | |
temporary | 临时对话 | 是否启用临时对话模式。 | true | |
disable_memory | 禁用记忆 | 禁用 Grok 记忆功能,防止响应中出现不相关上下文。 | true | |
stream | 流式响应 | 是否默认启用流式输出。 | true | |
thinking | 思维链 | 是否默认启用思维链输出。 | true | |
dynamic_statsig | 动态指纹 | 是否动态生成 Statsig 指纹。 | true | |
custom_instruction | 自定义指令 | 多行文本,透传为 Grok customPersonality。 | "" | |
filter_tags | 过滤标签 | 自动过滤 Grok 响应中的特殊标签。 | ["xaiartifact","xai:tool_usage_card","grok:render"] | |
proxy | base_proxy_url | 基础代理 URL | 代理请求到 Grok 官网的基础服务地址。 | "" |
asset_proxy_url | 资源代理 URL | 代理请求到 Grok 官网的静态资源(图片/视频)地址。 | "" | |
cf_cookies | CF Cookies | FlareSolverr 刷新写入的完整 Cookie 字符串。 | "" | |
skip_proxy_ssl_verify | 跳过代理 SSL 校验 | 代理使用自签名证书时启用(仅放行代理证书,目标站点仍校验)。 | false | |
enabled | CF 自动刷新 | 是否启用 CF 自动刷新。 | false | |
flaresolverr_url | FlareSolverr 地址 | FlareSolverr 服务的 HTTP 地址。 | "" | |
refresh_interval | 刷新间隔 | 自动刷新 cf_clearance 间隔(秒)。 | 3600 | |
timeout | 挑战超时 | CF 挑战等待超时(秒)。 | 60 | |
cf_clearance | CF Clearance | Cloudflare 验证 Cookie。 | "" | |
browser | 浏览器指纹 | curl_cffi 浏览器指纹标识(如 chrome136)。 | chrome136 | |
user_agent | User-Agent | HTTP 请求的 User-Agent 字符串。 | 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 | 最大重试 | 请求 Grok 服务失败时的最大重试次数。 | 3 |
retry_status_codes | 重试状态码 | 触发重试的 HTTP 状态码列表。 | [401, 429, 403] | |
reset_session_status_codes | 重建状态码 | 触发重建 session 的 HTTP 状态码列表(用于轮换代理)。 | [403] | |
retry_backoff_base | 退避基数 | 重试退避的基础延迟(秒)。 | 0.5 | |
retry_backoff_factor | 退避倍率 | 重试退避的指数放大系数。 | 2.0 | |
retry_backoff_max | 退避上限 | 单次重试等待的最大延迟(秒)。 | 20.0 | |
retry_budget | 退避预算 | 单次请求的最大重试总耗时(秒)。 | 60.0 | |
token | auto_refresh | 自动刷新 | 是否开启 Token 自动刷新机制。 | true |
refresh_interval_hours | 刷新间隔 | 普通 Token 刷新的时间间隔(小时)。 | 8 | |
super_refresh_interval_hours | Super 刷新间隔 | Super Token 刷新的时间间隔(小时)。 | 2 | |
fail_threshold | 失败阈值 | 单个 Token 连续失败多少次后被标记为不可用。 | 5 | |
save_delay_ms | 保存延迟 | Token 变更合并写入的延迟(毫秒)。 | 500 | |
usage_flush_interval_sec | 用量落库间隔 | 用量类字段写入数据库的最小间隔(秒)。 | 5 | |
reload_interval_sec | 同步间隔 | 多 worker 场景下 Token 状态刷新间隔(秒)。 | 30 | |
cache | enable_auto_clean | 自动清理 | 是否启用缓存自动清理,开启后按上限自动回收。 | true |
limit_mb | 清理阈值 | 缓存大小阈值(MB),超过阈值会触发清理。 | 512 | |
chat | concurrent | 并发上限 | Reverse 接口并发上限。 | 50 |
timeout | 请求超时 | Reverse 接口超时时间(秒)。 | 60 | |
stream_timeout | 流空闲超时 | 流式空闲超时时间(秒)。 | 60 | |
image | timeout | 请求超时 | WebSocket 请求超时时间(秒)。 | 60 |
stream_timeout | 流空闲超时 | WebSocket 流式空闲超时时间(秒)。 | 60 | |
final_timeout | 最终图超时 | 收到中等图后等待最终图的超时秒数。 | 15 | |
blocked_grace_seconds | 审查宽限秒数 | 收到中等图后,判定疑似被审查的宽限秒数。 | 10 | |
nsfw | NSFW 模式 | WebSocket 请求是否启用 NSFW。 | true | |
medium_min_bytes | 中等图最小字节 | 判定中等质量图的最小字节数。 | 30000 | |
final_min_bytes | 最终图最小字节 | 判定最终图的最小字节数(通常 JPG > 100KB)。 | 100000 | |
blocked_parallel_attempts | 并行补偿次数 | 遇到疑似审查/拦截时的并行补偿生成次数。 | 5 | |
blocked_parallel_enabled | 并行补偿开关 | 是否启用并行补偿(启用时优先使用不同 token)。 | true | |
imagine_fast | n | 生成数量 | 仅对 grok-imagine-1.0-fast 生效。 | 1 |
size | 图片尺寸 | 1280x720 / 720x1280 / 1792x1024 / 1024x1792 / 1024x1024 | 1024x1024 | |
response_format | 响应格式 | url / b64_json / base64 | url | |
video | concurrent | 并发上限 | Reverse 接口并发上限。 | 100 |
timeout | 请求超时 | Reverse 接口超时时间(秒)。 | 60 | |
stream_timeout | 流空闲超时 | 流式空闲超时时间(秒)。 | 60 | |
upscale_timing | 超分时机 | Basic 号池 720p 超分模式: single(每轮扩展后超分)/ complete(所有扩展后超分)。 | complete | |
voice | timeout | 请求超时 | Voice 请求超时时间(秒)。 | 60 |
asset | upload_concurrent | 上传并发 | 上传接口的最大并发数。 | 100 |
upload_timeout | 上传超时 | 上传接口超时时间(秒)。 | 60 | |
download_concurrent | 下载并发 | 下载接口的最大并发数。 | 100 | |
download_timeout | 下载超时 | 下载接口超时时间(秒)。 | 60 | |
list_concurrent | 查询并发 | 资产查询接口的最大并发数。 | 100 | |
list_timeout | 查询超时 | 资产查询接口超时时间(秒)。 | 60 | |
list_batch_size | 查询批次大小 | 单次查询可处理的 Token 数量。 | 50 | |
delete_concurrent | 删除并发 | 资产删除接口的最大并发数。 | 100 | |
delete_timeout | 删除超时 | 资产删除接口超时时间(秒)。 | 60 | |
delete_batch_size | 删除批次大小 | 单次删除可处理的 Token 数量。 | 50 | |
nsfw | concurrent | 并发上限 | 批量开启 NSFW 模式时的并发请求上限。 | 60 |
batch_size | 批次大小 | 批量开启 NSFW 模式的单批处理数量。 | 30 | |
timeout | 请求超时 | NSFW 开启相关请求的超时时间(秒)。 | 60 | |
usage | concurrent | 并发上限 | 批量刷新用量时的并发请求上限。 | 100 |
batch_size | 批次大小 | 批量刷新用量的单批处理数量。 | 50 | |
timeout | 请求超时 | 用量查询接口的超时时间(秒)。 | 60 |
请登录后发表您的评论
如有任何问题,可在对应段落/文末进行提问。