From 4f174253e677f47cfc917aefe183adad9a7b798f Mon Sep 17 00:00:00 2001 From: Chenyme <118253778+chenyme@users.noreply.github.com> Date: Sat, 7 Feb 2026 22:36:36 +0800 Subject: [PATCH] docs: update README files to include one-click deploy instructions for Render and enhance clarity in API documentation --- docs/README.en.md | 10 +++ readme.md | 189 ++++++++++++++++++++++++---------------------- render.yaml | 21 ++++++ 3 files changed, 131 insertions(+), 89 deletions(-) create mode 100644 render.yaml diff --git a/docs/README.en.md b/docs/README.en.md index 66d5c0f..12a6e25 100644 --- a/docs/README.en.md +++ b/docs/README.en.md @@ -31,6 +31,14 @@ git clone https://github.com/chenyme/grok2api docker compose up -d ``` +### One-click deploy (Render) + +[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/chenyme/grok2api) + +> Render free instances spin down after 15 minutes of inactivity; data is lost on resume/restart/redeploy. +> +> For persistence, use MySQL / Redis / PostgreSQL, on Render set: SERVER_STORAGE_TYPE (mysql/redis/pgsql) and SERVER_STORAGE_URL. + ### Admin panel URL: `http://:8000/admin` @@ -110,6 +118,8 @@ Note: any other parameters will be discarded and ignored. +
+ ### `POST /v1/images/generations` > Image generation endpoint diff --git a/readme.md b/readme.md index bf8ea55..85b3549 100644 --- a/readme.md +++ b/readme.md @@ -31,12 +31,21 @@ git clone https://github.com/chenyme/grok2api docker compose up -d ``` +### 一键部署（Render） + +[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/chenyme/grok2api) + +> Render 免费实例 15 分钟无访问会休眠，恢复/重启/重新部署会丢失。 +> +> 持久化请使用 MySQL / Redis / PostgreSQL，在 Render 环境变量中设置：SERVER_STORAGE_TYPE（mysql/redis/pgsql）与 SERVER_STORAGE_URL。 + ### 管理面板 访问地址：`http://:8000/admin` 默认登录密码：`grok2api`（对应配置项 `app.app_key`，建议修改）。 **功能说明**： + - **Token 管理**：导入/添加/删除 Token，查看状态和配额 - **状态筛选**：按状态（正常/限流/失效）或 NSFW 状态筛选 - **批量操作**：批量刷新、导出、删除、开启 NSFW @@ -103,32 +112,32 @@ curl http://localhost:8000/v1/chat/completions \
-| 字段 | 类型 | 说明 | 可用参数 | -| :------------------- | :------ | :----------------------------- | :------------------------------------------------- | -| `model` | string | 模型名称 | 见上方模型列表 | -| `messages` | array | 消息列表 | 见下方消息格式 | -| `stream` | boolean | 是否开启流式输出 | `true`, `false` | -| `thinking` | string | 思维链模式 | `enabled`, `disabled`, `null` | -| `video_config` | object | **视频模型专用配置对象** | - | -| └─`aspect_ratio` | string | 视频宽高比 | `16:9`, `9:16`, `1:1`, `2:3`, `3:2` | -| └─`video_length` | integer | 视频时长 (秒) | `6`, `10`, `15` | -| └─`resolution_name` | string | 分辨率 | `480p`, `720p` | -| └─`preset` | string | 风格预设 | `fun`, `normal`, `spicy`, `custom` | +| 字段 | 类型 | 说明 | 可用参数 | +| :---------------------- | :------ | :----------------------------- | :-------------------------------------------- | +| `model` | string | 模型名称 | 见上方模型列表 | +| `messages` | array | 消息列表 | 见下方消息格式 | +| `stream` | boolean | 是否开启流式输出 | `true`, `false` | +| `thinking` | string | 思维链模式 | `enabled`, `disabled`, `null` | +| `video_config` | object | **视频模型专用配置对象** | - | +| └─`aspect_ratio` | string | 视频宽高比 | `16:9`, `9:16`, `1:1`, `2:3`, `3:2` | +| └─`video_length` | integer | 视频时长 (秒) | `6`, `10`, `15` | +| └─`resolution_name` | string | 分辨率 | `480p`, `720p` | +| └─`preset` | string | 风格预设 | `fun`, `normal`, `spicy`, `custom` | **消息格式 (messages)**： -| 字段 | 类型 | 说明 | -| :-------- | :------------ | :----------------------------------------------------------- | -| `role` | string | 角色：`developer`, `system`, `user`, `assistant` | -| `content` | string/array | 消息内容，支持纯文本或多模态数组 | +| 字段 | 类型 | 说明 | +| :---------- | :----------- | :------------------------------------------------------- | +| `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://..."}}` | -| `file` | 文件 | `{"type": "file", "file": {"url": "https://..."}}` | +| type | 说明 | 示例 | +| :------------ | :------- | :------------------------------------------------------------- | +| `text` | 文本内容 | `{"type": "text", "text": "描述这张图片"}` | +| `image_url` | 图片 URL | `{"type": "image_url", "image_url": {"url": "https://..."}}` | +| `file` | 文件 | `{"type": "file", "file": {"url": "https://..."}}` | 注：除上述外的其他参数将自动丢弃并忽略 @@ -136,6 +145,8 @@ curl http://localhost:8000/v1/chat/completions \ +
+ ### `POST /v1/images/generations` > 图像生成接口 @@ -156,19 +167,19 @@ curl http://localhost:8000/v1/images/generations \
-| 字段 | 类型 | 说明 | 可用参数 | -| :---------------- | :------ | :--------------- | :------------------------------------------- | -| `model` | string | 图像模型名 | `grok-imagine-1.0` | +| 字段 | 类型 | 说明 | 可用参数 | +| :------------------ | :------ | :--------------- | :------------------------------------------- | +| `model` | string | 图像模型名 | `grok-imagine-1.0` | | `prompt` | string | 图像描述提示词 | - | -| `n` | integer | 生成数量 | `1` - `10` (流式模式仅限 `1` 或 `2`) | -| `stream` | boolean | 是否开启流式输出 | `true`, `false` | -| `size` | string | 图片尺寸 | `1024x1024` (WS 模式支持映射到比例) | -| `quality` | string | 图片质量 | `standard` (暂不支持自定义) | -| `response_format` | string | 响应格式 | `url`, `b64_json` | +| `n` | integer | 生成数量 | `1` - `10` (流式模式仅限 `1` 或 `2`) | +| `stream` | boolean | 是否开启流式输出 | `true`, `false` | +| `size` | string | 图片尺寸 | `1024x1024` (WS 模式支持映射到比例) | +| `quality` | string | 图片质量 | `standard` (暂不支持自定义) | +| `response_format` | string | 响应格式 | `url`, `b64_json` | | `style` | string | 风格 | - (暂不支持) | 注：`quality`、`style` 参数为 OpenAI 兼容保留，当前版本暂不支持自定义。 -当开启 `grok.image_ws=true` 时，`size` 将映射为宽高比（仅支持 5 种：`16:9`、`9:16`、`1:1`、`2:3`、`3:2`），也可以直接传以上比例字符串： +当开启 `grok.image_ws=true` 时，`size` 将映射为宽高比（仅支持 5 种：`16:9`、`9:16`、`1:1`、`2:3`、`3:2`），也可以直接传以上比例字符串： `1024x576/1280x720/1536x864 -> 16:9`，`576x1024/720x1280/864x1536 -> 9:16`，`1024x1024/512x512 -> 1:1`，`1024x1536/512x768/768x1024 -> 2:3`，`1536x1024/768x512/1024x768 -> 3:2`，其他值默认 `2:3`。
@@ -195,16 +206,16 @@ curl http://localhost:8000/v1/images/edits \
-| 字段 | 类型 | 说明 | 可用参数 | -| :---------------- | :------ | :--------------- | :------------------------------------------- | -| `model` | string | 图像模型名 | `grok-imagine-1.0-edit` | +| 字段 | 类型 | 说明 | 可用参数 | +| :------------------ | :------ | :--------------- | :------------------------------------------- | +| `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 | 图片尺寸 | `1024x1024` (暂不支持自定义) | -| `quality` | string | 图片质量 | `standard` (暂不支持自定义) | -| `response_format` | string | 响应格式 | `url`, `b64_json` | +| `image` | file | 待编辑图片 | `png`, `jpg`, `webp` | +| `n` | integer | 生成数量 | `1` - `10` (流式模式仅限 `1` 或 `2`) | +| `stream` | boolean | 是否开启流式输出 | `true`, `false` | +| `size` | string | 图片尺寸 | `1024x1024` (暂不支持自定义) | +| `quality` | string | 图片质量 | `standard` (暂不支持自定义) | +| `response_format` | string | 响应格式 | `url`, `b64_json` | | `style` | string | 风格 | - (暂不支持) | 注：`size`、`quality`、`style` 参数为 OpenAI 兼容保留，当前版本暂不支持自定义 @@ -227,57 +238,57 @@ curl http://localhost:8000/v1/images/edits \ > **v2.0 配置结构升级**：旧版本用户更新后，配置会**自动迁移**到新结构，无需手动修改。 > 旧的 `[grok]` 配置节中的自定义值会自动映射到对应的新配置节。 -| 模块 | 字段 | 配置名 | 说明 | 默认值 | -| :-------------------- | :--------------------------- | :----------- | :--------------------------------------------------- | :-------------------------------------------------------- | -| **app** | `app_url` | 应用地址 | 当前 Grok2API 服务的外部访问 URL，用于文件链接访问。 | `http://127.0.0.1:8000` | -| | `app_key` | 后台密码 | 登录 Grok2API 管理后台的密码（必填）。 | `grok2api` | -| | `api_key` | API 密钥 | 调用 Grok2API 服务的 Token（可选）。 | `""` | -| | `image_format` | 图片格式 | 生成的图片格式（url 或 base64）。 | `url` | -| | `video_format` | 视频格式 | 生成的视频格式（html 或 url，url 为处理后的链接）。 | `html` | -| **network** | `timeout` | 请求超时 | 请求 Grok 服务的超时时间（秒）。 | `120` | -| | `base_proxy_url` | 基础代理 URL | 代理请求到 Grok 官网的基础服务地址。 | `""` | -| | `asset_proxy_url` | 资源代理 URL | 代理请求到 Grok 官网的静态资源（图片/视频）地址。 | `""` | -| **security** | `cf_clearance` | CF Clearance | Cloudflare 验证 Cookie，用于绕过反爬虫验证。 | `""` | -| | `browser` | 浏览器指纹 | curl_cffi 浏览器指纹标识（如 chrome136）。 | `chrome136` | -| | `user_agent` | User-Agent | HTTP 请求的 User-Agent 字符串。 | `Mozilla/5.0 (Macintosh; ...)` | -| **chat** | `temporary` | 临时对话 | 是否启用临时对话模式。 | `true` | -| | `disable_memory` | 禁用记忆 | 禁用 Grok 记忆功能，防止响应中出现不相关上下文。 | `true` | -| | `stream` | 流式响应 | 是否默认启用流式输出。 | `true` | -| | `thinking` | 思维链 | 是否启用模型思维链输出。 | `true` | -| | `dynamic_statsig` | 动态指纹 | 是否启用动态生成 Statsig 值。 | `true` | -| | `filter_tags` | 过滤标签 | 自动过滤 Grok 响应中的特殊标签。 | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | -| **retry** | `max_retry` | 最大重试 | 请求 Grok 服务失败时的最大重试次数。 | `3` | -| | `retry_status_codes` | 重试状态码 | 触发重试的 HTTP 状态码列表。 | `[401, 429, 403]` | -| | `retry_backoff_base` | 退避基数 | 重试退避的基础延迟（秒）。 | `0.5` | -| | `retry_backoff_factor` | 退避倍率 | 重试退避的指数放大系数。 | `2.0` | -| | `retry_backoff_max` | 退避上限 | 单次重试等待的最大延迟（秒）。 | `30.0` | -| | `retry_budget` | 退避预算 | 单次请求的最大重试总耗时（秒）。 | `90.0` | -| **timeout** | `stream_idle_timeout` | 流空闲超时 | 流式响应空闲超时（秒），超过将断开。 | `120.0` | -| | `video_idle_timeout` | 视频空闲超时 | 视频生成空闲超时（秒），超过将断开。 | `90.0` | -| **image** | `image_ws` | WebSocket 生成 | 启用后 `/v1/images/generations` 走 WebSocket 直连。| `true` | -| | `image_ws_nsfw` | NSFW 模式 | WebSocket 请求是否启用 NSFW。 | `true` | -| | `image_ws_blocked_seconds` | Blocked 阈值 | 收到中等图后超过该秒数仍无最终图则判定 blocked。 | `15` | -| | `image_ws_final_min_bytes` | 最终图最小字节 | 判定最终图的最小字节数（通常 JPG > 100KB）。 | `100000` | -| | `image_ws_medium_min_bytes`| 中等图最小字节 | 判定中等质量图的最小字节数。 | `30000` | -| **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` | -| | `reload_interval_sec` | 同步间隔 | 多 worker 场景下 Token 状态刷新间隔（秒）。 | `30` | -| **cache** | `enable_auto_clean` | 自动清理 | 是否启用缓存自动清理，开启后按上限自动回收。 | `true` | -| | `limit_mb` | 清理阈值 | 缓存大小阈值（MB），超过阈值会触发清理。 | `1024` | -| **performance** | `media_max_concurrent` | Media 并发上限 | 视频/媒体生成请求的并发上限。推荐 50。 | `50` | -| | `assets_max_concurrent` | Assets 并发上限 | 批量查找/删除资产时的并发请求上限。推荐 25。 | `25` | -| | `assets_batch_size` | Assets 批次大小 | 批量查找/删除资产时的单批处理数量。推荐 10。 | `10` | -| | `assets_max_tokens` | Assets 最大数量 | 单次批量查找/删除资产时的处理数量上限。推荐 1000。 | `1000` | -| | `assets_delete_batch_size` | Assets 删除批量 | 单账号批量删除资产时的单批并发数量。推荐 10。 | `10` | -| | `usage_max_concurrent` | Token 刷新并发上限 | 批量刷新 Token 用量时的并发请求上限。推荐 25。 | `25` | -| | `usage_batch_size` | Token 刷新批次大小 | 批量刷新 Token 用量的单批处理数量。推荐 50。 | `50` | -| | `usage_max_tokens` | Token 刷新最大数量 | 单次批量刷新 Token 用量时的处理数量上限。推荐 1000。| `1000` | -| | `nsfw_max_concurrent` | NSFW 开启并发上限 | 批量开启 NSFW 模式时的并发请求上限。推荐 10。 | `10` | -| | `nsfw_batch_size` | NSFW 开启批次大小 | 批量开启 NSFW 模式的单批处理数量。推荐 50。 | `50` | -| | `nsfw_max_tokens` | NSFW 开启最大数量 | 单次批量开启 NSFW 的 Token 数量上限。推荐 1000。 | `1000` | +| 模块 | 字段 | 配置名 | 说明 | 默认值 | +| :-------------------- | :------------------------------- | :----------------- | :---------------------------------------------------- | :-------------------------------------------------------- | +| **app** | `app_url` | 应用地址 | 当前 Grok2API 服务的外部访问 URL，用于文件链接访问。 | `http://127.0.0.1:8000` | +| | `app_key` | 后台密码 | 登录 Grok2API 管理后台的密码（必填）。 | `grok2api` | +| | `api_key` | API 密钥 | 调用 Grok2API 服务的 Token（可选）。 | `""` | +| | `image_format` | 图片格式 | 生成的图片格式（url 或 base64）。 | `url` | +| | `video_format` | 视频格式 | 生成的视频格式（html 或 url，url 为处理后的链接）。 | `html` | +| **network** | `timeout` | 请求超时 | 请求 Grok 服务的超时时间（秒）。 | `120` | +| | `base_proxy_url` | 基础代理 URL | 代理请求到 Grok 官网的基础服务地址。 | `""` | +| | `asset_proxy_url` | 资源代理 URL | 代理请求到 Grok 官网的静态资源（图片/视频）地址。 | `""` | +| **security** | `cf_clearance` | CF Clearance | Cloudflare 验证 Cookie，用于绕过反爬虫验证。 | `""` | +| | `browser` | 浏览器指纹 | curl_cffi 浏览器指纹标识（如 chrome136）。 | `chrome136` | +| | `user_agent` | User-Agent | HTTP 请求的 User-Agent 字符串。 | `Mozilla/5.0 (Macintosh; ...)` | +| **chat** | `temporary` | 临时对话 | 是否启用临时对话模式。 | `true` | +| | `disable_memory` | 禁用记忆 | 禁用 Grok 记忆功能，防止响应中出现不相关上下文。 | `true` | +| | `stream` | 流式响应 | 是否默认启用流式输出。 | `true` | +| | `thinking` | 思维链 | 是否启用模型思维链输出。 | `true` | +| | `dynamic_statsig` | 动态指纹 | 是否启用动态生成 Statsig 值。 | `true` | +| | `filter_tags` | 过滤标签 | 自动过滤 Grok 响应中的特殊标签。 | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | +| **retry** | `max_retry` | 最大重试 | 请求 Grok 服务失败时的最大重试次数。 | `3` | +| | `retry_status_codes` | 重试状态码 | 触发重试的 HTTP 状态码列表。 | `[401, 429, 403]` | +| | `retry_backoff_base` | 退避基数 | 重试退避的基础延迟（秒）。 | `0.5` | +| | `retry_backoff_factor` | 退避倍率 | 重试退避的指数放大系数。 | `2.0` | +| | `retry_backoff_max` | 退避上限 | 单次重试等待的最大延迟（秒）。 | `30.0` | +| | `retry_budget` | 退避预算 | 单次请求的最大重试总耗时（秒）。 | `90.0` | +| **timeout** | `stream_idle_timeout` | 流空闲超时 | 流式响应空闲超时（秒），超过将断开。 | `120.0` | +| | `video_idle_timeout` | 视频空闲超时 | 视频生成空闲超时（秒），超过将断开。 | `90.0` | +| **image** | `image_ws` | WebSocket 生成 | 启用后 `/v1/images/generations` 走 WebSocket 直连。 | `true` | +| | `image_ws_nsfw` | NSFW 模式 | WebSocket 请求是否启用 NSFW。 | `true` | +| | `image_ws_blocked_seconds` | Blocked 阈值 | 收到中等图后超过该秒数仍无最终图则判定 blocked。 | `15` | +| | `image_ws_final_min_bytes` | 最终图最小字节 | 判定最终图的最小字节数（通常 JPG > 100KB）。 | `100000` | +| | `image_ws_medium_min_bytes` | 中等图最小字节 | 判定中等质量图的最小字节数。 | `30000` | +| **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` | +| | `reload_interval_sec` | 同步间隔 | 多 worker 场景下 Token 状态刷新间隔（秒）。 | `30` | +| **cache** | `enable_auto_clean` | 自动清理 | 是否启用缓存自动清理，开启后按上限自动回收。 | `true` | +| | `limit_mb` | 清理阈值 | 缓存大小阈值（MB），超过阈值会触发清理。 | `1024` | +| **performance** | `media_max_concurrent` | Media 并发上限 | 视频/媒体生成请求的并发上限。推荐 50。 | `50` | +| | `assets_max_concurrent` | Assets 并发上限 | 批量查找/删除资产时的并发请求上限。推荐 25。 | `25` | +| | `assets_batch_size` | Assets 批次大小 | 批量查找/删除资产时的单批处理数量。推荐 10。 | `10` | +| | `assets_max_tokens` | Assets 最大数量 | 单次批量查找/删除资产时的处理数量上限。推荐 1000。 | `1000` | +| | `assets_delete_batch_size` | Assets 删除批量 | 单账号批量删除资产时的单批并发数量。推荐 10。 | `10` | +| | `usage_max_concurrent` | Token 刷新并发上限 | 批量刷新 Token 用量时的并发请求上限。推荐 25。 | `25` | +| | `usage_batch_size` | Token 刷新批次大小 | 批量刷新 Token 用量的单批处理数量。推荐 50。 | `50` | +| | `usage_max_tokens` | Token 刷新最大数量 | 单次批量刷新 Token 用量时的处理数量上限。推荐 1000。 | `1000` | +| | `nsfw_max_concurrent` | NSFW 开启并发上限 | 批量开启 NSFW 模式时的并发请求上限。推荐 10。 | `10` | +| | `nsfw_batch_size` | NSFW 开启批次大小 | 批量开启 NSFW 模式的单批处理数量。推荐 50。 | `50` | +| | `nsfw_max_tokens` | NSFW 开启最大数量 | 单次批量开启 NSFW 的 Token 数量上限。推荐 1000。 | `1000` |
diff --git a/render.yaml b/render.yaml new file mode 100644 index 0000000..454d965 --- /dev/null +++ b/render.yaml @@ -0,0 +1,21 @@ +services: + - type: web + name: grok2api + env: docker + plan: free + autoDeploy: false + dockerfilePath: ./Dockerfile + dockerContext: . + envVars: + - key: TZ + value: Asia/Shanghai + - key: LOG_LEVEL + value: INFO + - key: SERVER_STORAGE_TYPE + value: local + - key: SERVER_STORAGE_URL + value: "" + - key: SERVER_HOST + value: 0.0.0.0 + - key: SERVER_PORT + value: "8000"