README.md

---
title: Grok2API
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# 🤖 Grok2API on HuggingFace Spaces

> 基于 FastAPI 重构的 Grok 反向代理，提供 OpenAI 兼容接口。  
> 支持流式/非流式对话、图像生成/编辑、视频生成、深度推理、Token 池并发与负载均衡。

---

## 📁 仓库文件结构

部署到 HuggingFace Space 只需以下文件：

```
your-space/
├── README.md          # 本文件（含 HF metadata）
├── Dockerfile         # 容器构建配置
└── entrypoint.sh      # 启动脚本（注入环境变量生成 config.toml）
```

---

## 📄 Dockerfile

```dockerfile
FROM python:3.12-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*

# 安装 uv 包管理器
RUN pip install uv --no-cache-dir

# 克隆 grok2api 源码
RUN git clone https://github.com/chenyme/grok2api /app

WORKDIR /app

# 安装 Python 依赖
RUN uv sync

# HuggingFace 文件系统只读，所有写入必须走 /tmp
RUN mkdir -p /tmp/data /tmp/logs

# 复制启动脚本
COPY entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh

# 环境变量默认值
ENV DATA_DIR=/tmp/data
ENV LOG_FILE_ENABLED=false
ENV LOG_LEVEL=INFO
ENV SERVER_PORT=7860
ENV SERVER_HOST=0.0.0.0

# HuggingFace Spaces 固定使用 7860 端口
EXPOSE 7860

CMD ["/app/entrypoint.sh"]
```

---

## 📄 entrypoint.sh

```bash
#!/bin/sh
set -e

echo "[entrypoint] Starting grok2api on HuggingFace Space..."

# 确保 /tmp 目录存在
mkdir -p /tmp/data /tmp/logs

# 从环境变量生成 config.toml
# APP_KEY      → 管理后台密码（默认 grok2api，强烈建议修改）
# API_KEY      → 调用 API 时需携带的访问密钥（留空则不鉴权）
# APP_URL      → 对外访问的完整 URL，用于生成文件链接
#                格式: https://你的用户名-grok2api.hf.space
cat > /tmp/data/config.toml << EOF
[app]
app_key   = "${APP_KEY:-grok2api}"
api_key   = "${API_KEY:-}"
app_url   = "${APP_URL:-}"
image_format = "url"
video_format = "html"
temporary    = true
disable_memory = true
stream       = true
thinking     = true

[server]
storage_type = "${SERVER_STORAGE_TYPE:-local}"
storage_url  = "${SERVER_STORAGE_URL:-}"
EOF

echo "[entrypoint] config.toml generated."
echo "[entrypoint] admin panel: ${APP_URL:-http://localhost:7860}/admin"

# 启动 FastAPI 服务
exec uv run granian \
  --interface asgi \
  --host 0.0.0.0 \
  --port 7860 \
  --workers 1 \
  main:app
```

---

## ⚙️ 环境变量配置

在 HuggingFace Space **Settings → Variables and secrets** 中配置以下变量：

### 🔐 Secrets（敏感信息，加密存储）

| 变量名 | 必填 | 说明 | 示例 |
|--------|:----:|------|------|
| `APP_KEY` | ✅ | 管理后台登录密码，**务必修改默认值** | `my-secure-password` |
| `API_KEY` | ⬜ | 调用 `/v1/chat/completions` 时需携带的密钥，留空则不鉴权 | `sk-my-api-key` |
| `SERVER_STORAGE_URL` | ⬜ | 外部数据库 DSN（推荐 Neon PostgreSQL，见下方说明） | `postgresql+asyncpg://user:pass@host/db?sslmode=require` |

### 🌐 Variables（普通变量）

| 变量名 | 必填 | 说明 | 示例 |
|--------|:----:|------|------|
| `APP_URL` | ⬜ | Space 对外 URL，用于生成图片/视频访问链接 | `https://你的用户名-grok2api.hf.space` |
| `SERVER_STORAGE_TYPE` | ⬜ | 存储类型，使用外部数据库时填 `pgsql` | `pgsql` / `local` |
| `LOG_LEVEL` | ⬜ | 日志级别 | `INFO` |

---

## 🗄️ 持久化存储（强烈推荐）

HuggingFace Space **重启后 `/tmp` 数据会丢失**，导致已导入的 Grok Token 全部清空。  
推荐使用 **Neon PostgreSQL 免费版** 做持久化：

1. 前往 [neon.tech](https://neon.tech) 注册，创建一个数据库
2. 复制 Connection String，格式如下：
   ```
   postgresql+asyncpg://user:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
   ```
3. 在 HF Space Secrets 中设置：
   - `SERVER_STORAGE_TYPE` = `pgsql`
   - `SERVER_STORAGE_URL` = 上方连接字符串

> **为什么选 Neon 而非 Supabase？**  
> Supabase 免费项目 7 天无活动会自动暂停，Neon 不会，更适合低频使用场景。

---

## 🚀 部署步骤

### 第一步：创建 Space

1. 登录 [huggingface.co](https://huggingface.co)
2. 点击右上角头像 → **New Space**
3. 填写：
   - Space name: `grok2api`
   - SDK: **Docker**（必须选这个）
   - Hardware: CPU Basic（免费）
4. 点击 **Create Space**

### 第二步：上传文件

```bash
# 克隆 Space 仓库
git clone https://huggingface.co/spaces/你的用户名/grok2api
cd grok2api

# 创建 README.md、Dockerfile、entrypoint.sh（内容见上方）

# 推送
git add .
git commit -m "deploy grok2api"
git push
```

推送后 HuggingFace 自动构建镜像，约 3~5 分钟后服务启动。

### 第三步：配置 Secrets

在 Space 页面 → **Settings → Variables and secrets** 中添加上方表格中的变量。

> 修改 Secrets 后需点击 **Restart Space** 使配置生效。

### 第四步：访问管理后台

```
https://你的用户名-grok2api.hf.space/admin
```

默认密码为 `grok2api`，首次登录后请立即在 Secrets 中设置 `APP_KEY` 修改密码。

---

## 🔑 导入 Grok Token

服务启动后，在管理后台 `/admin` 中：

1. 点击 **Token Management**
2. 点击 **Add Token**，粘贴你的 Grok SSO Token
3. 等待状态变为 **Active** 即可使用

---

## 📡 API 使用示例

将你客户端的 Base URL 替换为 Space 地址即可：

### cURL

```bash
curl https://你的用户名-grok2api.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-3",
    "stream": true,
    "messages": [{"role": "user", "content": "你好！"}]
  }'
```

### Python（OpenAI SDK）

```python
from openai import OpenAI

client = OpenAI(
    api_key="你的 API_KEY",  # 未设置则填任意字符串
    base_url="https://你的用户名-grok2api.hf.space/v1",
)

response = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "你好！"}],
    stream=True,
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")
```

---

## 📊 支持的模型

| 模型 | 类型 | 账号要求 |
|------|------|---------|
| `grok-3` | 对话 / 图像 | Basic / Super |
| `grok-3-mini` | 对话 / 图像 | Basic / Super |
| `grok-3-thinking` | 深度推理 | Basic / Super |
| `grok-imagine-1.0` | 图像生成 | Basic / Super |
| `grok-imagine-1.0-edit` | 图像编辑 | Basic / Super |
| `grok-imagine-1.0-video` | 视频生成 | Basic / Super |

---

## ⚠️ 注意事项

| 限制 | 说明 |
|------|------|
| **端口** | HF Space 固定使用 `7860`，不可更改 |
| **休眠** | 免费版 48 小时无访问后自动休眠，首次访问需约 30 秒唤醒 |
| **数据持久化** | 不接外部数据库则重启丢失所有 Token，强烈建议配置 Neon |
| **文件系统只读** | 所有配置/日志必须写入 `/tmp`，entrypoint 已处理 |
| **免责声明** | 本项目仅供学习研究，请遵守 Grok 使用条款及当地法律法规 |

---

## 🔗 相关链接

- [grok2api 源码](https://github.com/chenyme/grok2api)
- [Neon 免费 PostgreSQL](https://neon.tech)
- [HuggingFace Spaces 文档](https://huggingface.co/docs/hub/spaces)