Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

availableservices/grok2api

Open more actions menu
 
 

Repository files navigation

Grok2API

中文 | English | 文档

Note

本项目仅供学习与研究,使用者必须在遵循 Grok 的 使用条款 以及 法律法规 的情况下使用,不得用于非法用途。

Note

开源项目欢迎大家支持二开和PR,但请保留原作者标识和前端标识,尊重他人劳动成果~!

Note

没错,我又来重构了,目前不接受所有 PR~

基于 FastAPI 重构的 Grok2API,全面适配最新 Web 调用格式,支持流/非流式对话、工具调用、图像生成/编辑、视频生成/超分(文生视频 / 图生视频)、深度思考,号池并发与自动负载均衡一体化。

image

快速开始

文档

本地开发

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 端口变量:

  • SERVER_PORT:容器内应用监听端口
  • HOST_PORT:宿主机映射端口(仅 Docker Compose 使用)

小贴士:端口映射规则是 HOST_PORT:SERVER_PORT,你访问的是 HOST_PORT,容器内服务实际监听的是 SERVER_PORT

示例:HOST_PORT=9000 SERVER_PORT=8011 docker compose up -d,访问 http://localhost:9000

Vercel 部署

Deploy with Vercel

请务必设置 DATA_DIR=/tmp/data 并关闭文件日志 LOG_FILE_ENABLED=false

持久化请使用 MySQL / Redis / PostgreSQL,并设置:SERVER_STORAGE_TYPESERVER_STORAGE_URL

Render 部署

Deploy to Render

Render 免费实例 15 分钟无访问会休眠;重启/重新部署会丢失数据。

持久化请使用 MySQL / Redis / PostgreSQL,并设置:SERVER_STORAGE_TYPESERVER_STORAGE_URL


管理面板

  • 访问地址:http://<host>:<port>/admin(本地运行使用 SERVER_PORT,Docker Compose 使用 HOST_PORT,默认均为 8000
  • 默认密码:grok2api(配置项 app.app_key,建议修改)

功能说明

  • Token 管理:导入/添加/删除 Token,查看状态和配额
  • 状态筛选:按状态(正常/限流/失效)或 NSFW 状态筛选
  • 批量操作:批量刷新、导出、删除、开启 NSFW
  • NSFW 开启:一键为 Token 开启 Unhinged 模式(需代理或 cf_clearance
  • 配置管理:在线修改系统配置
  • 缓存管理:查看和清理媒体缓存

环境变量

配置 .env 文件

变量名 说明 默认值 示例
LOG_LEVEL 日志级别 INFO DEBUG
LOG_FILE_ENABLED 是否启用文件日志 true false
DATA_DIR 数据目录(配置/Token/锁) ./data /data
SERVER_HOST 服务监听地址 0.0.0.0 0.0.0.0
SERVER_PORT 服务端口 8000 8000
HOST_PORT Docker Compose 宿主机映射端口 8000 9000
SERVER_WORKERS 服务进程数量 1 2
SERVER_STORAGE_TYPE 存储类型(local/redis/mysql/pgsql local pgsql
SERVER_STORAGE_URL 存储连接串(local 时可为空) "" postgresql+asyncpg://user:password@host:5432/db

MySQL 示例:mysql+aiomysql://user:password@host:3306/db(若填 mysql:// 会自动转为 mysql+aiomysql://


可用次数

  • Basic 账号:80 次 / 20h
  • Super 账号:140 次 / 2h

可用模型

模型名 计次 可用账号 对话功能 图像功能 视频功能
grok-3 1 Basic/Super 支持 支持 -
grok-3-mini 1 Basic/Super 支持 支持 -
grok-3-thinking 1 Basic/Super 支持 支持 -
grok-4 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 - - 支持

接口说明

以下示例默认使用 localhost:8000;若 Docker Compose 设置了 HOST_PORT,请替换为对应端口。

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",
    "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 ~ 30
└─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_effortnone 表示不输出思考,其他值都会输出思考内容。
  • 工具调用为提示词模拟 + 客户端执行回填:模型通过 <tool_call>{...}</tool_call> 输出调用请求,服务端解析为 tool_calls;不执行工具。
  • grok-imagine-1.0-fast 与瀑布流 imagine 生成链路一致,可直接通过 /v1/chat/completions 调用;其 n/size/response_format 由服务端 [imagine_fast] 统一控制。
  • grok-imagine-1.0-fast/v1/chat/completions 的流式输出仅返回最终成图,不返回中间预览图。
  • grok-imagine-1.0-fast 流式 URL 出图会保持原始图片名(不追加 -final 后缀)。
  • 当图片疑似被审查拦截导致无最终图时,若开启 image.blocked_parallel_enabled,服务端会按 image.blocked_parallel_attempts 自动并行补偿生成,并优先使用不同 token;若仍无满足 image.final_min_bytes 的最终图则返回失败。
  • grok-imagine-1.0-edit 必须提供图片,多图默认取最后 3 张与最后一个文本。
  • grok-imagine-1.0-video 支持文生视频与多图参考视频:可通过多个 image_url 传最多 7 张参考图,并在文本中使用 @图1@图2 这类占位符;服务端会自动替换为对应 assetId
  • @图Nimage_url 的顺序一一对应;若引用了不存在的图片序号,会直接报错。
  • 除上述外的其他参数将自动丢弃并忽略。


POST /v1/responses

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.* 事件。


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-1.0",
    "prompt": "一只在太空漂浮的猫",
    "n": 1
  }'
支持的请求参数
字段 类型 说明 可用参数
model string 图像模型名 grok-imagine-1.0
prompt string 图像描述提示词 -
n integer 生成数量 1 - 10 (流式模式仅限 12)
stream boolean 是否开启流式输出 true, false
size string 图片尺寸 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
quality string 图片质量 - (暂不支持)
response_format string 响应格式 url, b64_json, base64
style string 风格 - (暂不支持)

注意事项

  • qualitystyle 参数为 OpenAI 兼容保留,当前版本暂不支持自定义。
  • 多图编辑若传入超过 3 张,仅取最后 3 张作为参考。


POST /v1/images/edits

图像编辑接口(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 (流式模式仅限 12)
stream boolean 是否开启流式输出 true, false
size string 图片尺寸 1280x720, 720x1280, 1792x1024, 1024x1792, 1024x1024
quality string 图片质量 - (暂不支持)
response_format string 响应格式 url, b64_json, base64
style string 风格 - (暂不支持)

注意事项

  • qualitystyle 参数为 OpenAI 兼容保留,当前版本暂不支持自定义。


POST /v1/videos

视频生成接口(OpenAI videos.create 兼容)

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 array 参考图(可选) 兼容 OpenAI content block 数组格式 ([{"type":"image_url"...}]) 或纯 URL 字符串数组;单图也请传单元素数组
input_reference file multipart 参考图(可选) png, jpg, webp

注意事项

  • 服务端已支持 6~30 秒自动链式扩展,无需使用 /v1/video/extend
  • quality=standard 对应 480pquality=high 对应 720p
  • 基础号池请求 720p 时会先产出 480p 再按 video.upscale_timing 执行超分。
  • image_reference 统一使用数组格式,最多可传 7 张参考图;单图场景也请传单元素数组。input_reference 主要以表单上传参考图;若两者同时传入,会按顺序作为参考图合并输入;可在提示词中使用 @图1@图2


参数配置

配置文件:data/config.toml

Note

生产环境或反向代理部署时,请确保 app.app_url 配置为对外可访问的完整 URL, 否则可能出现文件访问链接不正确或 403 等问题。

Tip

v2.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

Star History

Star History Chart

About

基于 FastAPI 构建的 Grok2API,全面适配 OpenAI 兼容的调用格式,支持流式/非流式对话、图像生成、图像编辑、视频生成、工具调用、语音聊天、一键NSFW、号池并发与自动负载均衡一体化。

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Morty Proxy This is a proxified and sanitized view of the page, visit original site.