Chenyme's Blog
主页文章项目
Chenyme's BlogChenyme's Blog

我是 Chenyme,专注于把AI、交互和技术融合在一起,用更克制的设计和稳定的工程交付长期可用的产品。

  • Telegram

网站

  • 首页
  • 博客
  • 项目
  • 关于

资源

  • 关于我
  • Github 仓库
  • 服务条款
  • 隐私政策

友链

  • Cheny Blog
  • YouTube
  • LINUX DO
  • Google 学术

© 2026 Chenyme's Blog. All rights reserved.

  1. Blog
  2. Grok2API 部署教程

Grok2API 部署教程

CChenyme发布于 2026年03月03日
Grok · 2API
grok2api

基于 FastAPI 构建的 Grok2API,支持将 Grok.com 的 Web 端服务一键转换为 OpenAI API 兼容的调用格式。项目支持原生流式对话、非流式对话、图像生成、图像编辑、视频生成、工具调用、语音聊天、一键NSFW、号池并发与自动负载均衡一体化,且提供后台管理、功能玩法等 WebUI,方便小白快速上手。

本项目仅供学习、研究和技术交流之用。请务必遵循 Grok 的 使用条款 以及 法律法规,不得用于非法用途,使用者须自行承担一切风险,本项目作者概不负责。

项目介绍

项目地址:https://github.com/chenyme/grok2api
基于 FastAPI 构建的 Grok2API,支持将 Grok.com 的 Web 端服务一键转换为 OpenAI API 兼容的调用格式。项目支持原生流式对话、非流式对话、图像生成、图像编辑、视频生成、工具调用、语音聊天、一键NSFW、号池并发与自动负载均衡一体化,且提供后台管理、功能玩法等 WebUI,方便小白快速上手。

快速开始

环境变量

修改 .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

部署方式

1. 本地部署

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

uv sync

uv run granian --interface asgi main:app

2. Docker Compose

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

cd grok2api

docker compose up -d
docker-compose.yml
docker-compose.ymldockerfile
services:
  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-stopped

3. Vercel 部署

vercel-deploy
  • 设置存储路径 DATA_DIR=/tmp/data
  • 关闭文件日志 LOG_FILE_ENABLED=false
  • 推荐使用 MySQL / Redis / PostgreSQL,并设置:
    • SERVER_STORAGE_TYPE
    • B
      SERVER_STORAGE_URL

4. Render 部署

render-deploy
  • Render 免费实例 15 分钟无访问会自动休眠,且非持久化时重启/重新部署会丢失数据。
  • 持久化请使用 MySQL / Redis / PostgreSQL,并设置:
    • SERVER_STORAGE_TYPE
    • B
      SERVER_STORAGE_URL

使用教程

基础信息

1. 项目地址

  • 管理后台:http://<host>:8000/admin
  • 功能玩法:http://<host>:8000/(管理后台开启后生效)
  • 默认密码:grok2api

2. 账号配额

GROK 官方网页更新后并未真实暴露 rate-limits 接口,导致无法准确计算 Token 剩余,请耐心等待官方接口上线,目前自动刷新后会统一更新为剩余 8 次
  • Basic 账号:80 次 / 20h
  • Super 账号:140 次 / 2h

3. 模型支持

模型名称
调用计次
可用账号
对话功能
图像功能
视频功能
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
-
-
支持

接口信息

1. POST /v1/chat/completions

OpenAI Chat Completions API 通用接口,支持聊天对话、图像生成、图像编辑、视频生成
curlpowershell
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
消息格式 (messages):
字段
类型
说明
role
string
角色:developer, system, user, assistant
content
string/array
消息内容,支持纯文本或多模态数组
多模态内容块类型 (content 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
    •  与瀑布流 imagine 生成链路一致,可直接通过 /v1/chat/completions 调用;其 n/size/response_format 由服务端 [imagine_fast] 统一控制。
    • 在 /v1/chat/completions 的流式输出仅返回最终成图,不返回中间预览图。
    • 流式 URL 出图会保持原始图片名(不追加 -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 的最终图则返回失败。
  • 除上述外的其他参数将自动丢弃并忽略。

2. POST /v1/responses

OpenAI Responses API 兼容接口,支持聊天对话、图像生成、图像编辑、视频生成
curlpowershell
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.* 事件。

3. POST /v1/images/generations

OpenAI Image Generations API 兼容接口,支持图像生成
curlpowershell
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 兼容保留,当前版本暂不支持自定义。
  • 多图编辑若传入超过 3 张,仅取最后 3 张作为参考。

4. POST /v1/images/edits

OpenAI Image Edits API 兼容接口,支持图像编辑(multipart/form-data)
curlpowershell
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 兼容保留,当前版本暂不支持自定义。

5. POST /v1/videos

OpenAI Videos API 兼容接口,支持视频生成(multipart/form-data)
curlpowershell
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
注意事项:
  • 服务端已支持 6~30 秒自动链式扩展,无需使用 /v1/video/extend。
  • quality=standard 对应 480p;quality=high 对应 720p。
  • 基础号池请求 720p 时会先产出 480p 再按 video.upscale_timing 执行超分。
  • image_reference 与 input_reference 同时传入时,会按顺序作为参考图输入;视频链路只使用第 1 张。

参数配置

  • 配置文件路径:data/config.toml
v1.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
文章不错?点赞鼓励一下吧

7 条评论

参与讨论

请登录后发表您的评论

1
[email protected]

不支持多参生成视频了吗?我记得第一个版本都可以

2026/04/15 21:13:15
C
Chenyme

如有任何问题,可在对应段落/文末进行提问。

2026/03/04 23:24:44

目录

项目介绍快速开始环境变量部署方式1. 本地部署2. Docker Compose3. Vercel 部署4. Render 部署使用教程基础信息1. 项目地址2. 账号配额3. 模型支持接口信息1. POST /v1/chat/completions2. POST /v1/responses3. POST /v1/images/generations4. POST /v1/images/edits5. POST /v1/videos参数配置

数据

阅读量

9484

点赞数

130

转发数

43

阅读时长

9 分钟

发布时间

2026/03/03

最近更新

2026/03/07

分享