From 7b093288dc13dd4163378da7d403ba53d5a9dd8d Mon Sep 17 00:00:00 2001 From: Chenyme <118253778+chenyme@users.noreply.github.com> Date: Sun, 15 Feb 2026 18:01:34 +0800 Subject: [PATCH] docs: update README and documentation to reflect new features, including video generation and improved deployment instructions --- docs/README.en.md | 350 ++++++++++++++++++++++++---------------------- readme.md | 324 +++++++++++++++++++++--------------------- 2 files changed, 349 insertions(+), 325 deletions(-) diff --git a/docs/README.en.md b/docs/README.en.md index ed43399..e92283a 100644 --- a/docs/README.en.md +++ b/docs/README.en.md @@ -5,102 +5,108 @@ > [!NOTE] > This project is for learning and research only. You must comply with Grok **Terms of Use** and **local laws and regulations**. Do not use for illegal purposes. -Grok2API rebuilt with **FastAPI**, fully aligned with the latest web call format. Supports streaming/non-streaming chat, image generation/editing, deep reasoning, token pool concurrency, and automatic load balancing. +Grok2API rebuilt with **FastAPI**, fully aligned with the latest web call format. Supports streaming/non-streaming chat, image generation/editing, video generation/upscale, deep reasoning, token pool concurrency, and automatic load balancing. -### NOTE: The project is no longer accepting PRs and feature updates; this is the last structure optimization. +> [!IMPORTANT] +> The project is no longer accepting PRs or new features; this is the last structure optimization. -image +image
-## Usage +## Quick Start -### How to Start +### Local -- Local development - -``` +```bash uv sync - uv run main.py ``` -### How to Deploy +### Docker Compose -#### docker compose -``` +```bash git clone https://github.com/chenyme/grok2api +cd grok2api docker compose up -d ``` -#### Vercel +### Vercel [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/chenyme/grok2api&env=LOG_LEVEL,LOG_FILE_ENABLED,DATA_DIR,SERVER_STORAGE_TYPE,SERVER_STORAGE_URL&envDefaults=%7B%22DATA_DIR%22%3A%22/tmp/data%22%2C%22LOG_FILE_ENABLED%22%3A%22false%22%2C%22LOG_LEVEL%22%3A%22INFO%22%2C%22SERVER_STORAGE_TYPE%22%3A%22local%22%2C%22SERVER_STORAGE_URL%22%3A%22%22%7D) -> Make sure to set `DATA_DIR=/tmp/data` and disable file logging with `LOG_FILE_ENABLED=false`. +> Set `DATA_DIR=/tmp/data` and disable file logs with `LOG_FILE_ENABLED=false`. > -> For persistence, use MySQL / Redis / PostgreSQL and set `SERVER_STORAGE_TYPE` (mysql/redis/pgsql) and `SERVER_STORAGE_URL` in Vercel env vars. +> For persistence, use MySQL / Redis / PostgreSQL and set `SERVER_STORAGE_TYPE` and `SERVER_STORAGE_URL`. -#### Render +### 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 sleep after 15 minutes of inactivity; restart/redeploy will lose data. +> Render free instances sleep after 15 minutes of inactivity; redeploy/restart will lose data. > -> For persistence, use MySQL / Redis / PostgreSQL and set `SERVER_STORAGE_TYPE` (mysql/redis/pgsql) and `SERVER_STORAGE_URL` in Render env vars. +> For persistence, use MySQL / Redis / PostgreSQL and set `SERVER_STORAGE_TYPE` and `SERVER_STORAGE_URL`. -### Admin Panel +
-Access: `http://:8000/admin` -Default password: `grok2api` (config `app.app_key`, recommended to change). +## Admin Panel + +- Access: `http://:8000/admin` +- Default password: `grok2api` (config `app.app_key`, recommended to change) **Features**: - **Token Management**: import/add/delete tokens, view status and quota - **Status Filter**: filter by status (active/limited/expired) or NSFW status - **Batch Ops**: batch refresh/export/delete/enable NSFW -- **NSFW Enable**: one-click Unhinged for tokens (proxy or cf_clearance required) +- **NSFW Enable**: one-click Unhinged for tokens (proxy or `cf_clearance` required) - **Config Management**: update system config online - **Cache Management**: view and clear media cache -### Environment Variables +
+ +## Environment Variables > Configure `.env` -| Name | Description | Default | Example | -| :--------------------- | :-------------------------------------------------- | :---------- | :---------------------------------------------------- | -| `LOG_LEVEL` | Log level | `INFO` | `DEBUG` | -| `LOG_FILE_ENABLED` | Enable file logging | `true` | `false` | -| `DATA_DIR` | Data dir (config/tokens/locks) | `./data` | `/data` | -| `SERVER_HOST` | Bind address | `0.0.0.0` | `0.0.0.0` | -| `SERVER_PORT` | Server port | `8000` | `8000` | -| `SERVER_WORKERS` | Uvicorn worker count | `1` | `2` | -| `SERVER_STORAGE_TYPE` | Storage type (`local`/`redis`/`mysql`/`pgsql`) | `local` | `pgsql` | -| `SERVER_STORAGE_URL` | Storage DSN (optional for local) | `""` | `postgresql+asyncpg://user:password@host:5432/db` | +| Name | Description | Default | Example | +| :-- | :-- | :-- | :-- | +| `LOG_LEVEL` | Log level | `INFO` | `DEBUG` | +| `LOG_FILE_ENABLED` | Enable file logging | `true` | `false` | +| `DATA_DIR` | Data dir (config/tokens/locks) | `./data` | `/data` | +| `SERVER_HOST` | Bind address | `0.0.0.0` | `0.0.0.0` | +| `SERVER_PORT` | Server port | `8000` | `8000` | +| `SERVER_WORKERS` | Uvicorn worker count | `1` | `2` | +| `SERVER_STORAGE_TYPE` | Storage type (`local`/`redis`/`mysql`/`pgsql`) | `local` | `pgsql` | +| `SERVER_STORAGE_URL` | Storage DSN (optional for local) | `""` | `postgresql+asyncpg://user:password@host:5432/db` | -> MySQL example: `mysql+aiomysql://user:password@host:3306/db` (if you provide `mysql://`, it will be converted to `mysql+aiomysql://`) +> MySQL example: `mysql+aiomysql://user:password@host:3306/db` (if you provide `mysql://`, it will be converted to `mysql+aiomysql://`). -### Quotas +
+ +## Quotas - Basic account: 80 requests / 20h - Super account: 140 requests / 2h -### Models +
-| Model | Cost | Account | Chat | Image | Video | -| :---------------------- | :--: | :---------- | :--: | :---: | :---: | -| `grok-3` | 1 | Basic/Super | Yes | Yes | - | -| `grok-3-fast` | 1 | Basic/Super | Yes | Yes | - | -| `grok-4` | 1 | Basic/Super | Yes | Yes | - | -| `grok-4-mini` | 1 | Basic/Super | Yes | Yes | - | -| `grok-4-fast` | 1 | Basic/Super | Yes | Yes | - | -| `grok-4-heavy` | 4 | Super | Yes | Yes | - | -| `grok-4.1` | 1 | Basic/Super | Yes | Yes | - | -| `grok-4.1-thinking` | 4 | Basic/Super | Yes | Yes | - | -| `grok-imagine-1.0` | 4 | Basic/Super | - | Yes | - | -| `grok-imagine-1.0-edit` | 4 | Basic/Super | - | Yes | - | -| `grok-imagine-1.0-video`| - | Basic/Super | - | - | Yes | +## Models + +| Model | Cost | Account | Chat | Image | Video | +| :-- | :--: | :-- | :--: | :--: | :--: | +| `grok-3` | 1 | Basic/Super | Yes | Yes | - | +| `grok-3-fast` | 1 | Basic/Super | Yes | Yes | - | +| `grok-4` | 1 | Basic/Super | Yes | Yes | - | +| `grok-4-mini` | 1 | Basic/Super | Yes | Yes | - | +| `grok-4-fast` | 1 | Basic/Super | Yes | Yes | - | +| `grok-4-heavy` | 4 | Super | Yes | Yes | - | +| `grok-4.1` | 1 | Basic/Super | Yes | Yes | - | +| `grok-4.1-thinking` | 4 | Basic/Super | Yes | Yes | - | +| `grok-imagine-1.0` | 4 | Basic/Super | - | Yes | - | +| `grok-imagine-1.0-edit` | 4 | Basic/Super | - | Yes | - | +| `grok-imagine-1.0-video` | - | Basic/Super | - | - | Yes |
@@ -111,7 +117,10 @@ Default password: `grok2api` (config `app.app_key`, recommended to change). > Generic endpoint: chat, image generation, image editing, video generation, video upscaling ```bash -curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer $GROK2API_API_KEY" -d '{ +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":"Hello"}] }' @@ -122,41 +131,42 @@ curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/j
-| Field | Type | Description | Allowed values | -| :--------------------- | :------ | :-------------------------- | :--------------------------------------------------------------------------------------------------------------- | -| `model` | string | Model ID | See model list above | -| `messages` | array | Message list | See message format below | -| `stream` | boolean | Enable streaming | `true`, `false` | -| `reasoning_effort` | string | Reasoning effort | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | -| `temperature` | number | Sampling temperature | `0` ~ `2` | -| `top_p` | number | Nucleus sampling | `0` ~ `1` | -| `video_config` | object | **Video model only** | Supported: `grok-imagine-1.0-video` | -| └─ `aspect_ratio` | string | Video aspect ratio | `16:9`, `9:16`, `1:1`, `2:3`, `3:2`, `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | -| └─ `video_length` | integer | Video length (seconds) | `6`, `10`, `15` | -| └─ `resolution_name` | string | Resolution | `480p`, `720p` | -| └─ `preset` | string | Style preset | `fun`, `normal`, `spicy`, `custom` | -| `image_config` | object | **Image models only** | Supported: `grok-imagine-1.0` / `grok-imagine-1.0-edit` | -| └─ `n` | integer | Number of images | `1` ~ `10` | -| └─ `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | -| └─ `response_format` | string | Response format | `url`, `b64_json`, `base64` | +| Field | Type | Description | Allowed values | +| :-- | :-- | :-- | :-- | +| `model` | string | Model ID | See model list above | +| `messages` | array | Message list | See message format below | +| `stream` | boolean | Enable streaming | `true`, `false` | +| `reasoning_effort` | string | Reasoning effort | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | +| `temperature` | number | Sampling temperature | `0` ~ `2` | +| `top_p` | number | Nucleus sampling | `0` ~ `1` | +| `video_config` | object | **Video model only** | Supported: `grok-imagine-1.0-video` | +| └─ `aspect_ratio` | string | Video aspect ratio | `16:9`, `9:16`, `1:1`, `2:3`, `3:2`, `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | +| └─ `video_length` | integer | Video length (seconds) | `6`, `10`, `15` | +| └─ `resolution_name` | string | Resolution | `480p`, `720p` | +| └─ `preset` | string | Style preset | `fun`, `normal`, `spicy`, `custom` | +| `image_config` | object | **Image models only** | Supported: `grok-imagine-1.0` / `grok-imagine-1.0-edit` | +| └─ `n` | integer | Number of images | `1` ~ `10` | +| └─ `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | +| └─ `response_format` | string | Response format | `url`, `b64_json`, `base64` | **Message format (messages)**: -| Field | Type | Description | -| :-------- | :----------- | :-------------------------------------------------- | -| `role` | string | `developer`, `system`, `user`, `assistant` | -| `content` | string/array | Message content (plain text or multimodal array) | +| Field | Type | Description | +| :-- | :-- | :-- | +| `role` | string | `developer`, `system`, `user`, `assistant` | +| `content` | string/array | Plain text or multimodal array | **Multimodal content block types (content array)**: -| type | Description | Example | -| :------------ | :---------- | :----------------------------------------------------------------------- | -| `text` | Text | `{"type": "text", "text": "Describe this image"}` | -| `image_url` | Image URL | `{"type": "image_url", "image_url": {"url": "https://..."}}` | -| `input_audio` | Audio | `{"type": "input_audio", "input_audio": {"data": "https://..."}}` | -| `file` | File | `{"type": "file", "file": {"file_data": "https://..."}}` | +| type | Description | Example | +| :-- | :-- | :-- | +| `text` | Text | `{"type": "text", "text": "Describe this image"}` | +| `image_url` | Image URL | `{"type": "image_url", "image_url": {"url": "https://..."}}` | +| `input_audio` | Audio | `{"type": "input_audio", "input_audio": {"data": "https://..."}}` | +| `file` | File | `{"type": "file", "file": {"file_data": "https://..."}}` | **Notes**: + - `image_url/input_audio/file` only supports URL or Data URI (`data:;base64,...`); raw base64 will be rejected. - `reasoning_effort`: `none` disables thinking output; any other value enables it. - `grok-imagine-1.0-edit` requires an image; if multiple are provided, the last image and last text are used. @@ -173,7 +183,10 @@ curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/j > Image generation endpoint ```bash -curl http://localhost:8000/v1/images/generations -H "Content-Type: application/json" -H "Authorization: Bearer $GROK2API_API_KEY" -d '{ +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": "A cat floating in space", "n": 1 @@ -185,18 +198,19 @@ curl http://localhost:8000/v1/images/generations -H "Content-Type: application
-| Field | Type | Description | Allowed values | -| :----------------- | :------ | :--------------- | :----------------------------------------------------------------- | -| `model` | string | Image model ID | `grok-imagine-1.0` | -| `prompt` | string | Prompt | - | -| `n` | integer | Number of images | `1` - `10` (streaming: `1` or `2` only) | -| `stream` | boolean | Enable streaming | `true`, `false` | -| `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | -| `quality` | string | Image quality | - (not supported) | -| `response_format` | string | Response format | `url`, `b64_json`, `base64` | -| `style` | string | Style | - | +| Field | Type | Description | Allowed values | +| :-- | :-- | :-- | :-- | +| `model` | string | Image model ID | `grok-imagine-1.0` | +| `prompt` | string | Prompt | - | +| `n` | integer | Number of images | `1` - `10` (streaming: `1` or `2` only) | +| `stream` | boolean | Enable streaming | `true`, `false` | +| `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | +| `quality` | string | Image quality | - (not supported) | +| `response_format` | string | Response format | `url`, `b64_json`, `base64` | +| `style` | string | Style | - (not supported) | **Notes**: + - `quality` and `style` are OpenAI compatibility placeholders and are not customizable yet.
@@ -210,7 +224,12 @@ curl http://localhost:8000/v1/images/generations -H "Content-Type: application > Image edit endpoint (multipart/form-data) ```bash -curl http://localhost:8000/v1/images/edits -H "Authorization: Bearer $GROK2API_API_KEY" -F "model=grok-imagine-1.0-edit" -F "prompt=Make it sharper" -F "image=@/path/to/image.png" -F "n=1" +curl http://localhost:8000/v1/images/edits \ + -H "Authorization: Bearer $GROK2API_API_KEY" \ + -F "model=grok-imagine-1.0-edit" \ + -F "prompt=Make the image clearer" \ + -F "image=@/path/to/image.png" \ + -F "n=1" ```
@@ -218,19 +237,20 @@ curl http://localhost:8000/v1/images/edits -H "Authorization: Bearer $GROK2API
-| Field | Type | Description | Allowed values | -| :----------------- | :------ | :--------------- | :----------------------------------------------------------------- | -| `model` | string | Image model ID | `grok-imagine-1.0-edit` | -| `prompt` | string | Edit prompt | - | -| `image` | file | Image file | `png`, `jpg`, `webp` | -| `n` | integer | Number of images | `1` - `10` (streaming: `1` or `2` only) | -| `stream` | boolean | Enable streaming | `true`, `false` | -| `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | -| `quality` | string | Image quality | - (not supported) | -| `response_format` | string | Response format | `url`, `b64_json`, `base64` | -| `style` | string | Style | - (not supported) | +| Field | Type | Description | Allowed values | +| :-- | :-- | :-- | :-- | +| `model` | string | Image model ID | `grok-imagine-1.0-edit` | +| `prompt` | string | Edit prompt | - | +| `image` | file | Source image | `png`, `jpg`, `webp` | +| `n` | integer | Number of images | `1` - `10` (streaming: `1` or `2` only) | +| `stream` | boolean | Enable streaming | `true`, `false` | +| `size` | string | Image size | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | +| `quality` | string | Image quality | - (not supported) | +| `response_format` | string | Response format | `url`, `b64_json`, `base64` | +| `style` | string | Style | - (not supported) | **Notes**: + - `quality` and `style` are OpenAI compatibility placeholders and are not customizable yet.
@@ -244,74 +264,74 @@ curl http://localhost:8000/v1/images/edits -H "Authorization: Bearer $GROK2API Config file: `data/config.toml` > [!NOTE] -> In production or reverse proxy environments, set `app.app_url` to a publicly accessible URL, -> otherwise file links may be incorrect or return 403. +> In production or behind a reverse proxy, make sure `app.app_url` is a publicly accessible URL, +> otherwise file links may be incorrect or result in 403. > [!TIP] -> **v2.0 config structure upgrade**: legacy config will be **automatically migrated** to the new structure. -> Custom values under the old `[grok]` section are mapped to the new sections. +> **v2.0 config migration**: old configs are automatically migrated. The old `[grok]` section +> is mapped into the new config structure. -| Module | Field | Name | Description | Default | -| :------------------- | :----------------------------- | :--------------------- | :----------------------------------------------------------------- | :---------------------------------------------------------- | -| **app** | `app_url` | App URL | External access URL for Grok2API (used for file links). | `http://127.0.0.1:8000` | -| | `app_key` | Admin password | Password for Grok2API admin panel (required). | `grok2api` | -| | `api_key` | API key | Token for calling Grok2API (optional). | `""` | -| | `image_format` | Image format | Output image format (url or base64). | `url` | -| | `video_format` | Video format | Output video format (html or url, url is processed). | `html` | -| | `temporary` | Temporary chat | Enable temporary conversation mode. | `true` | -| | `disable_memory` | Disable memory | Disable Grok memory to prevent irrelevant context. | `true` | -| | `stream` | Streaming | Enable streaming by default. | `true` | -| | `thinking` | Thinking chain | Enable model thinking output. | `true` | -| | `dynamic_statsig` | Dynamic fingerprint | Enable dynamic Statsig generation. | `true` | -| | `filter_tags` | Filter tags | Auto-filter special tags in Grok responses. | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | -| **proxy** | `base_proxy_url` | Base proxy URL | Base service address proxying Grok official site. | `""` | -| | `asset_proxy_url` | Asset proxy URL | Proxy URL for Grok static assets (images/videos). | `""` | -| | `cf_clearance` | CF Clearance | Cloudflare clearance cookie for anti-bot. | `""` | -| | `browser` | Browser fingerprint | curl_cffi browser fingerprint (e.g. chrome136). | `chrome136` | -| | `user_agent` | User-Agent | HTTP User-Agent string. | `Mozilla/5.0 (Macintosh; ...)` | -| **voice** | `timeout` | Request timeout | Voice request timeout (seconds). | `120` | -| **chat** | `concurrent` | Concurrency | Reverse interface concurrency limit. | `10` | -| | `timeout` | Request timeout | Reverse interface timeout (seconds). | `60` | -| | `stream_timeout` | Stream idle timeout | Stream idle timeout (seconds). | `60` | -| **video** | `concurrent` | Concurrency | Reverse interface concurrency limit. | `10` | -| | `timeout` | Request timeout | Reverse interface timeout (seconds). | `60` | -| | `stream_timeout` | Stream idle timeout | Stream idle timeout (seconds). | `60` | -| **retry** | `max_retry` | Max retries | Max retries on Grok request failure. | `3` | -| | `retry_status_codes` | Retry status codes | HTTP status codes that trigger retry. | `[401, 429, 403]` | -| | `retry_backoff_base` | Backoff base | Base delay for retry backoff (seconds). | `0.5` | -| | `retry_backoff_factor` | Backoff factor | Exponential multiplier for retry backoff. | `2.0` | -| | `retry_backoff_max` | Backoff max | Max wait per retry (seconds). | `30.0` | -| | `retry_budget` | Backoff budget | Max total retry time per request (seconds). | `90.0` | -| **image** | `timeout` | Request timeout | WebSocket request timeout (seconds). | `120` | -| | `stream_timeout` | Stream idle timeout | WebSocket stream idle timeout (seconds). | `120` | -| | `final_timeout` | Final image timeout | Timeout after medium image before final (seconds). | `15` | -| | `nsfw` | NSFW mode | Enable NSFW in WebSocket requests. | `true` | -| | `medium_min_bytes` | Medium min bytes | Minimum bytes for medium quality image. | `30000` | -| | `final_min_bytes` | Final min bytes | Minimum bytes to treat an image as final (JPG usually > 100KB). | `100000` | -| **token** | `auto_refresh` | Auto refresh | Enable automatic token refresh. | `true` | -| | `refresh_interval_hours` | Refresh interval | Regular token refresh interval (hours). | `8` | -| | `super_refresh_interval_hours` | Super refresh interval | Super token refresh interval (hours). | `2` | -| | `fail_threshold` | Failure threshold | Consecutive failures before a token is disabled. | `5` | -| | `save_delay_ms` | Save delay | Debounced save delay for token changes (ms). | `500` | -| | `reload_interval_sec` | Sync interval | Token state refresh interval in multi-worker setups (sec). | `30` | -| **cache** | `enable_auto_clean` | Auto clean | Enable cache auto clean; cleanup when exceeding limit. | `true` | -| | `limit_mb` | Cleanup threshold | Cache size threshold (MB) that triggers cleanup. | `1024` | -| **asset** | `upload_concurrent` | Upload concurrency | Max concurrency for upload. Recommended 30. | `30` | -| | `upload_timeout` | Upload timeout | Upload timeout (seconds). Recommended 60. | `60` | -| | `download_concurrent` | Download concurrency | Max concurrency for download. Recommended 30. | `30` | -| | `download_timeout` | Download timeout | Download timeout (seconds). Recommended 60. | `60` | -| | `list_concurrent` | List concurrency | Max concurrency for asset listing. Recommended 10. | `10` | -| | `list_timeout` | List timeout | List timeout (seconds). Recommended 60. | `60` | -| | `list_batch_size` | List batch size | Batch size per list request. Recommended 10. | `10` | -| | `delete_concurrent` | Delete concurrency | Max concurrency for asset delete. Recommended 10. | `10` | -| | `delete_timeout` | Delete timeout | Delete timeout (seconds). Recommended 60. | `60` | -| | `delete_batch_size` | Delete batch size | Batch size per delete request. Recommended 10. | `10` | -| **nsfw** | `concurrent` | Concurrency | Max concurrency for enabling NSFW. Recommended 10. | `10` | -| | `batch_size` | Batch size | Batch size for enabling NSFW. Recommended 50. | `50` | -| | `timeout` | Request timeout | NSFW enable request timeout (seconds). Recommended 60. | `60` | -| **usage** | `concurrent` | Concurrency | Max concurrency for usage refresh. Recommended 10. | `10` | -| | `batch_size` | Batch size | Batch size for usage refresh. Recommended 50. | `50` | -| | `timeout` | Request timeout | Usage query timeout (seconds). Recommended 60. | `60` | +| Module | Field | Key | Description | Default | +| :-- | :-- | :-- | :-- | :-- | +| **app** | `app_url` | App URL | External base URL used for file links. | `http://127.0.0.1:8000` | +| | `app_key` | Admin password | Login password for admin panel. | `grok2api` | +| | `api_key` | API key | Optional API key for access. | `""` | +| | `image_format` | Image format | `url` or `base64`. | `url` | +| | `video_format` | Video format | `html` or `url` (processed link). | `html` | +| | `temporary` | Temporary chat | Enable temporary chat mode. | `true` | +| | `disable_memory` | Disable memory | Disable Grok memory. | `true` | +| | `stream` | Stream | Enable streaming by default. | `true` | +| | `thinking` | Thinking | Enable reasoning output. | `true` | +| | `dynamic_statsig` | Dynamic statsig | Generate dynamic Statsig values. | `true` | +| | `filter_tags` | Filter tags | Filter special tags in responses. | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | +| **proxy** | `base_proxy_url` | Base proxy URL | Proxy to Grok web. | `""` | +| | `asset_proxy_url` | Asset proxy URL | Proxy to Grok assets (img/video). | `""` | +| | `cf_clearance` | CF Clearance | Cloudflare clearance cookie. | `""` | +| | `browser` | Browser fingerprint | curl_cffi fingerprint (e.g. chrome136). | `chrome136` | +| | `user_agent` | User-Agent | HTTP User-Agent string. | `Mozilla/5.0 (Macintosh; ...)` | +| **voice** | `timeout` | Timeout | Voice request timeout (seconds). | `120` | +| **chat** | `concurrent` | Concurrency | Reverse interface concurrency limit. | `10` | +| | `timeout` | Timeout | Reverse request timeout (seconds). | `60` | +| | `stream_timeout` | Stream idle timeout | Stream idle timeout (seconds). | `60` | +| **video** | `concurrent` | Concurrency | Reverse interface concurrency limit. | `10` | +| | `timeout` | Timeout | Reverse request timeout (seconds). | `60` | +| | `stream_timeout` | Stream idle timeout | Stream idle timeout (seconds). | `60` | +| **retry** | `max_retry` | Max retry | Max retries for upstream failures. | `3` | +| | `retry_status_codes` | Retry codes | HTTP status codes that trigger retry. | `[401, 429, 403]` | +| | `retry_backoff_base` | Backoff base | Retry backoff base seconds. | `0.5` | +| | `retry_backoff_factor` | Backoff factor | Exponential backoff factor. | `2.0` | +| | `retry_backoff_max` | Backoff max | Max delay per retry (seconds). | `30.0` | +| | `retry_budget` | Retry budget | Max total retry time (seconds). | `90.0` | +| **image** | `timeout` | Timeout | WebSocket timeout (seconds). | `120` | +| | `stream_timeout` | Stream idle timeout | WS stream idle timeout (seconds). | `120` | +| | `final_timeout` | Final timeout | Wait time after medium image (seconds). | `15` | +| | `nsfw` | NSFW | Enable NSFW. | `true` | +| | `medium_min_bytes` | Medium min bytes | Minimum size for medium image. | `30000` | +| | `final_min_bytes` | Final min bytes | Minimum size for final image (JPG > 100KB typical). | `100000` | +| **token** | `auto_refresh` | Auto refresh | Enable token auto refresh. | `true` | +| | `refresh_interval_hours` | Refresh interval | Basic token refresh interval (hours). | `8` | +| | `super_refresh_interval_hours` | Super refresh interval | Super token refresh interval (hours). | `2` | +| | `fail_threshold` | Fail threshold | Consecutive failures to disable. | `5` | +| | `save_delay_ms` | Save delay | Merge write delay (ms). | `500` | +| | `reload_interval_sec` | Reload interval | Multi-worker token reload interval (seconds). | `30` | +| **cache** | `enable_auto_clean` | Auto clean | Enable cache auto cleanup. | `true` | +| | `limit_mb` | Size limit | Cleanup threshold (MB). | `1024` | +| **asset** | `upload_concurrent` | Upload concurrency | Max upload concurrency (recommended 30). | `30` | +| | `upload_timeout` | Upload timeout | Upload timeout (seconds). | `60` | +| | `download_concurrent` | Download concurrency | Max download concurrency (recommended 30). | `30` | +| | `download_timeout` | Download timeout | Download timeout (seconds). | `60` | +| | `list_concurrent` | List concurrency | Max list concurrency (recommended 10). | `10` | +| | `list_timeout` | List timeout | List timeout (seconds). | `60` | +| | `list_batch_size` | List batch size | Tokens per list batch (recommended 10). | `10` | +| | `delete_concurrent` | Delete concurrency | Max delete concurrency (recommended 10). | `10` | +| | `delete_timeout` | Delete timeout | Delete timeout (seconds). | `60` | +| | `delete_batch_size` | Delete batch size | Tokens per delete batch (recommended 10). | `10` | +| **nsfw** | `concurrent` | Concurrency | NSFW batch enable concurrency (recommended 10). | `10` | +| | `batch_size` | Batch size | NSFW batch size (recommended 50). | `50` | +| | `timeout` | Timeout | NSFW request timeout (seconds). | `60` | +| **usage** | `concurrent` | Concurrency | Usage refresh concurrency (recommended 10). | `10` | +| | `batch_size` | Batch size | Usage batch size (recommended 50). | `50` | +| | `timeout` | Timeout | Usage request timeout (seconds). | `60` |
diff --git a/readme.md b/readme.md index 3850d65..8fce25c 100644 --- a/readme.md +++ b/readme.md @@ -5,103 +5,105 @@ > [!NOTE] > 本项目仅供学习与研究，使用者必须在遵循 Grok 的 **使用条款** 以及 **法律法规** 的情况下使用，不得用于非法用途。 -基于 **FastAPI** 重构的 Grok2API，全面适配最新 Web 调用格式，支持流/非流式对话、图像生成/编辑、深度思考，号池并发与自动负载均衡一体化。 +基于 **FastAPI** 重构的 Grok2API，全面适配最新 Web 调用格式，支持流/非流式对话、图像生成/编辑、视频生成/超分、深度思考，号池并发与自动负载均衡一体化。 -### NOTE：项目近期停止接受 PR 和 暂停功能更新，最后优化一次项目结构～ - -image +image
-## 使用说明 +## 快速开始 -### 如何启动 +### 本地开发 -- 本地开发 - -``` +```bash uv sync - uv run main.py ``` -### 如何部署 +### Docker Compose - -#### docker compose 部署 -``` +```bash git clone https://github.com/chenyme/grok2api +cd grok2api docker compose up -d ``` -#### Vercel 部署 +### Vercel 部署 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/chenyme/grok2api&env=LOG_LEVEL,LOG_FILE_ENABLED,DATA_DIR,SERVER_STORAGE_TYPE,SERVER_STORAGE_URL&envDefaults=%7B%22DATA_DIR%22%3A%22/tmp/data%22%2C%22LOG_FILE_ENABLED%22%3A%22false%22%2C%22LOG_LEVEL%22%3A%22INFO%22%2C%22SERVER_STORAGE_TYPE%22%3A%22local%22%2C%22SERVER_STORAGE_URL%22%3A%22%22%7D) -> 请务必设置 DATA_DIR=/tmp/data，并关闭文件日志 LOG_FILE_ENABLED=false。 +> 请务必设置 `DATA_DIR=/tmp/data` 并关闭文件日志 `LOG_FILE_ENABLED=false`。 > -> 持久化请使用 MySQL / Redis / PostgreSQL，在 Vercel 环境变量中设置：SERVER_STORAGE_TYPE（mysql/redis/pgsql）与 SERVER_STORAGE_URL。 +> 持久化请使用 MySQL / Redis / PostgreSQL，并设置：`SERVER_STORAGE_TYPE` 与 `SERVER_STORAGE_URL`。 -#### Render 部署 +### 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 分钟无访问会休眠，恢复/重启/重新部署会丢失。 +> Render 免费实例 15 分钟无访问会休眠；重启/重新部署会丢失数据。 > -> 持久化请使用 MySQL / Redis / PostgreSQL，在 Render 环境变量中设置：SERVER_STORAGE_TYPE（mysql/redis/pgsql）与 SERVER_STORAGE_URL。 +> 持久化请使用 MySQL / Redis / PostgreSQL，并设置：`SERVER_STORAGE_TYPE` 与 `SERVER_STORAGE_URL`。 -### 管理面板 +
-访问地址：`http://:8000/admin` -默认登录密码：`grok2api`（对应配置项 `app.app_key`，建议修改）。 +## 管理面板 + +- 访问地址：`http://:8000/admin` +- 默认密码：`grok2api`（配置项 `app.app_key`，建议修改） **功能说明**： - **Token 管理**：导入/添加/删除 Token，查看状态和配额 - **状态筛选**：按状态（正常/限流/失效）或 NSFW 状态筛选 - **批量操作**：批量刷新、导出、删除、开启 NSFW -- **NSFW 开启**：一键为 Token 开启 Unhinged 模式（需代理或 cf_clearance） +- **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` | -| `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` | +| 变量名 | 说明 | 默认值 | 示例 | +| :-- | :-- | :-- | :-- | +| `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` | +| `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` | > MySQL 示例：`mysql+aiomysql://user:password@host:3306/db`（若填 `mysql://` 会自动转为 `mysql+aiomysql://`） -### 可用次数 +
+ +## 可用次数 - Basic 账号：80 次 / 20h - Super 账号：140 次 / 2h -### 可用模型 +
-| 模型名 | 计次 | 可用账号 | 对话功能 | 图像功能 | 视频功能 | -| :------------------------- | :--: | :---------- | :------: | :------: | :------: | -| `grok-3` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-3-fast` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-4` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-4-mini` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-4-fast` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-4-heavy` | 4 | Super | 支持 | 支持 | - | -| `grok-4.1` | 1 | Basic/Super | 支持 | 支持 | - | -| `grok-4.1-thinking` | 4 | Basic/Super | 支持 | 支持 | - | -| `grok-imagine-1.0` | 4 | Basic/Super | - | 支持 | - | -| `grok-imagine-1.0-edit` | 4 | Basic/Super | - | 支持 | - | -| `grok-imagine-1.0-video` | - | Basic/Super | - | - | 支持 | +## 可用模型 + +| 模型名 | 计次 | 可用账号 | 对话功能 | 图像功能 | 视频功能 | +| :-- | :--: | :-- | :--: | :--: | :--: | +| `grok-3` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-3-fast` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-4` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-4-mini` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-4-fast` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-4-heavy` | 4 | Super | 支持 | 支持 | - | +| `grok-4.1` | 1 | Basic/Super | 支持 | 支持 | - | +| `grok-4.1-thinking` | 4 | Basic/Super | 支持 | 支持 | - | +| `grok-imagine-1.0` | 4 | Basic/Super | - | 支持 | - | +| `grok-imagine-1.0-edit` | 4 | Basic/Super | - | 支持 | - | +| `grok-imagine-1.0-video` | - | Basic/Super | - | - | 支持 |
@@ -126,44 +128,44 @@ curl http://localhost:8000/v1/chat/completions \
-| 字段 | 类型 | 说明 | 可用参数 | -| :---------------------- | :------ | :----------------------------- | :------------------------------------------------------------------------------------------------- | -| `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` | -| `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-edit` | -| └─`n` | integer | 生成数量 | `1` ~ `10` | -| └─`size` | string | 图片尺寸 | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` | -| └─`response_format` | string | 响应格式 | `url`, `b64_json`, `base64` | +| 字段 | 类型 | 说明 | 可用参数 | +| :-- | :-- | :-- | :-- | +| `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` | +| `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-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 | 消息内容，支持纯文本或多模态数组 | +| 字段 | 类型 | 说明 | +| :-- | :-- | :-- | +| `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://..."}}` | +| 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:;base64,...`），裸 base64 会报错。 -- `reasoning_effort`：`none` 表示不输出思考，其他值都会输出思考内容。 +- `reasoning_effort`：`none` 表示不输出思考，其他值都会输出思考内容。 - `grok-imagine-1.0-edit` 必须提供图片，多图默认取最后一张与最后一个文本。 - 除上述外的其他参数将自动丢弃并忽略。 @@ -193,18 +195,19 @@ curl http://localhost:8000/v1/images/generations \
-| 字段 | 类型 | 说明 | 可用参数 | -| :------------------ | :------ | :--------------- | :------------------------------------------------------------ | -| `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 | 风格 | - | +| 字段 | 类型 | 说明 | 可用参数 | +| :-- | :-- | :-- | :-- | +| `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 兼容保留，当前版本暂不支持自定义。
@@ -231,19 +234,20 @@ curl http://localhost:8000/v1/images/edits \
-| 字段 | 类型 | 说明 | 可用参数 | -| :------------------ | :------ | :--------------- | :------------------------------------------------------------ | -| `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 | 风格 | - (暂不支持) | +| 字段 | 类型 | 说明 | 可用参数 | +| :-- | :-- | :-- | :-- | +| `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 兼容保留，当前版本暂不支持自定义。
@@ -264,67 +268,67 @@ 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` | -| | `temporary` | 临时对话 | 是否启用临时对话模式。 | `true` | -| | `disable_memory` | 禁用记忆 | 禁用 Grok 记忆功能，防止响应中出现不相关上下文。 | `true` | -| | `stream` | 流式响应 | 是否默认启用流式输出。 | `true` | -| | `thinking` | 思维链 | 是否启用模型思维链输出。 | `true` | -| | `dynamic_statsig` | 动态指纹 | 是否启用动态生成 Statsig 值。 | `true` | -| | `filter_tags` | 过滤标签 | 自动过滤 Grok 响应中的特殊标签。 | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | -| **proxy** | `base_proxy_url` | 基础代理 URL | 代理请求到 Grok 官网的基础服务地址。 | `""` | -| | `asset_proxy_url` | 资源代理 URL | 代理请求到 Grok 官网的静态资源（图片/视频）地址。 | `""` | -| | `cf_clearance` | CF Clearance | Cloudflare 验证 Cookie，用于绕过反爬虫验证。 | `""` | -| | `browser` | 浏览器指纹 | curl_cffi 浏览器指纹标识（如 chrome136）。 | `chrome136` | -| | `user_agent` | User-Agent | HTTP 请求的 User-Agent 字符串。 | `Mozilla/5.0 (Macintosh; ...)` | -| **voice** | `timeout` | 请求超时 | Voice 请求超时时间（秒）。 | `120` | -| **chat** | `concurrent` | 并发上限 | Reverse 接口并发上限。 | `10` | -| | `timeout` | 请求超时 | Reverse 接口超时时间（秒）。 | `60` | -| | `stream_timeout` | 流空闲超时 | 流式空闲超时时间（秒）。 | `60` | -| **video** | `concurrent` | 并发上限 | Reverse 接口并发上限。 | `10` | -| | `timeout` | 请求超时 | Reverse 接口超时时间（秒）。 | `60` | -| | `stream_timeout` | 流空闲超时 | 流式空闲超时时间（秒）。 | `60` | -| **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` | -| **image** | `timeout` | 请求超时 | WebSocket 请求超时时间（秒）。 | `120` | -| | `stream_timeout` | 流空闲超时 | WebSocket 流式空闲超时时间（秒）。 | `120` | -| | `final_timeout` | 最终图超时 | 收到中等图后等待最终图的超时秒数。 | `15` | -| | `nsfw` | NSFW 模式 | WebSocket 请求是否启用 NSFW。 | `true` | -| | `medium_min_bytes` | 中等图最小字节 | 判定中等质量图的最小字节数。 | `30000` | -| | `final_min_bytes` | 最终图最小字节 | 判定最终图的最小字节数（通常 JPG > 100KB）。 | `100000` | -| **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` | -| **asset** | `upload_concurrent` | 上传并发 | 上传接口的最大并发数。推荐 30。 | `30` | -| | `upload_timeout` | 上传超时 | 上传接口超时时间（秒）。推荐 60。 | `60` | -| | `download_concurrent` | 下载并发 | 下载接口的最大并发数。推荐 30。 | `30` | -| | `download_timeout` | 下载超时 | 下载接口超时时间（秒）。推荐 60。 | `60` | -| | `list_concurrent` | 查询并发 | 资产查询接口的最大并发数。推荐 10。 | `10` | -| | `list_timeout` | 查询超时 | 资产查询接口超时时间（秒）。推荐 60。 | `60` | -| | `list_batch_size` | 查询批次大小 | 单次查询可处理的 Token 数量。推荐 10。 | `10` | -| | `delete_concurrent` | 删除并发 | 资产删除接口的最大并发数。推荐 10。 | `10` | -| | `delete_timeout` | 删除超时 | 资产删除接口超时时间（秒）。推荐 60。 | `60` | -| | `delete_batch_size` | 删除批次大小 | 单次删除可处理的 Token 数量。推荐 10。 | `10` | -| **nsfw** | `concurrent` | 并发上限 | 批量开启 NSFW 模式时的并发请求上限。推荐 10。 | `10` | -| | `batch_size` | 批次大小 | 批量开启 NSFW 模式的单批处理数量。推荐 50。 | `50` | -| | `timeout` | 请求超时 | NSFW 开启相关请求的超时时间（秒）。推荐 60。 | `60` | -| **usage** | `concurrent` | 并发上限 | 批量刷新用量时的并发请求上限。推荐 10。 | `10` | -| | `batch_size` | 批次大小 | 批量刷新用量的单批处理数量。推荐 50。 | `50` | -| | `timeout` | 请求超时 | 用量查询接口的超时时间（秒）。推荐 60。 | `60` | +| 模块 | 字段 | 配置名 | 说明 | 默认值 | +| :-- | :-- | :-- | :-- | :-- | +| **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` | +| | `temporary` | 临时对话 | 是否启用临时对话模式。 | `true` | +| | `disable_memory` | 禁用记忆 | 禁用 Grok 记忆功能，防止响应中出现不相关上下文。 | `true` | +| | `stream` | 流式响应 | 是否默认启用流式输出。 | `true` | +| | `thinking` | 思维链 | 是否启用模型思维链输出。 | `true` | +| | `dynamic_statsig` | 动态指纹 | 是否启用动态生成 Statsig 值。 | `true` | +| | `filter_tags` | 过滤标签 | 自动过滤 Grok 响应中的特殊标签。 | `["xaiartifact", "xai:tool_usage_card", "grok:render"]` | +| **proxy** | `base_proxy_url` | 基础代理 URL | 代理请求到 Grok 官网的基础服务地址。 | `""` | +| | `asset_proxy_url` | 资源代理 URL | 代理请求到 Grok 官网的静态资源（图片/视频）地址。 | `""` | +| | `cf_clearance` | CF Clearance | Cloudflare 验证 Cookie，用于绕过反爬虫验证。 | `""` | +| | `browser` | 浏览器指纹 | curl_cffi 浏览器指纹标识（如 chrome136）。 | `chrome136` | +| | `user_agent` | User-Agent | HTTP 请求的 User-Agent 字符串。 | `Mozilla/5.0 (Macintosh; ...)` | +| **voice** | `timeout` | 请求超时 | Voice 请求超时时间（秒）。 | `120` | +| **chat** | `concurrent` | 并发上限 | Reverse 接口并发上限。 | `10` | +| | `timeout` | 请求超时 | Reverse 接口超时时间（秒）。 | `60` | +| | `stream_timeout` | 流空闲超时 | 流式空闲超时时间（秒）。 | `60` | +| **video** | `concurrent` | 并发上限 | Reverse 接口并发上限。 | `10` | +| | `timeout` | 请求超时 | Reverse 接口超时时间（秒）。 | `60` | +| | `stream_timeout` | 流空闲超时 | 流式空闲超时时间（秒）。 | `60` | +| **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` | +| **image** | `timeout` | 请求超时 | WebSocket 请求超时时间（秒）。 | `120` | +| | `stream_timeout` | 流空闲超时 | WebSocket 流式空闲超时时间（秒）。 | `120` | +| | `final_timeout` | 最终图超时 | 收到中等图后等待最终图的超时秒数。 | `15` | +| | `nsfw` | NSFW 模式 | WebSocket 请求是否启用 NSFW。 | `true` | +| | `medium_min_bytes` | 中等图最小字节 | 判定中等质量图的最小字节数。 | `30000` | +| | `final_min_bytes` | 最终图最小字节 | 判定最终图的最小字节数（通常 JPG > 100KB）。 | `100000` | +| **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` | +| **asset** | `upload_concurrent` | 上传并发 | 上传接口的最大并发数。推荐 30。 | `30` | +| | `upload_timeout` | 上传超时 | 上传接口超时时间（秒）。推荐 60。 | `60` | +| | `download_concurrent` | 下载并发 | 下载接口的最大并发数。推荐 30。 | `30` | +| | `download_timeout` | 下载超时 | 下载接口超时时间（秒）。推荐 60。 | `60` | +| | `list_concurrent` | 查询并发 | 资产查询接口的最大并发数。推荐 10。 | `10` | +| | `list_timeout` | 查询超时 | 资产查询接口超时时间（秒）。推荐 60。 | `60` | +| | `list_batch_size` | 查询批次大小 | 单次查询可处理的 Token 数量。推荐 10。 | `10` | +| | `delete_concurrent` | 删除并发 | 资产删除接口的最大并发数。推荐 10。 | `10` | +| | `delete_timeout` | 删除超时 | 资产删除接口超时时间（秒）。推荐 60。 | `60` | +| | `delete_batch_size` | 删除批次大小 | 单次删除可处理的 Token 数量。推荐 10。 | `10` | +| **nsfw** | `concurrent` | 并发上限 | 批量开启 NSFW 模式时的并发请求上限。推荐 10。 | `10` | +| | `batch_size` | 批次大小 | 批量开启 NSFW 模式的单批处理数量。推荐 50。 | `50` | +| | `timeout` | 请求超时 | NSFW 开启相关请求的超时时间（秒）。推荐 60。 | `60` | +| **usage** | `concurrent` | 并发上限 | 批量刷新用量时的并发请求上限。推荐 10。 | `10` | +| | `batch_size` | 批次大小 | 批量刷新用量的单批处理数量。推荐 50。 | `50` | +| | `timeout` | 请求超时 | 用量查询接口的超时时间（秒）。推荐 60。 | `60` |