README.md

metadata

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

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

#!/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 注册，创建一个数据库
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
2. 点击右上角头像 → New Space
3. 填写：
   • Space name: grok2api
   • SDK: Docker（必须选这个）
   • Hardware: CPU Basic（免费）
4. 点击 Create Space

第二步：上传文件

# 克隆 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

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）

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 源码
• Neon 免费 PostgreSQL
• HuggingFace Spaces 文档