README.md

---
title: Grok2API
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
app_port: 8000
---

# Grok2API - Hugging Face Spaces 部署版

这是 [chenyme/grok2api](https://github.com/chenyme/grok2api) 的 Hugging Face Spaces 适配版本。

## 功能特性

- ✅ OpenAI 兼容 API 接口
- ✅ 支持流式和非流式对话
- ✅ 支持图像生成和编辑
- ✅ 支持视频生成
- ✅ 多账号池管理
- ✅ 自动负载均衡
- ✅ 持久化存储（配合 Spaces Persistent Storage）

## 部署步骤

### 1. 创建 Space

1. 前往 [Hugging Face Spaces](https://huggingface.co/spaces)
2. 点击 "Create new Space"
3. 选择 **Docker SDK**
4. 选择硬件：建议 CPU basic（免费）或更高配置

### 2. 配置环境变量

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

**必需配置：**
```
APP_KEY=your_admin_password_here
API_KEY=your_api_key_here
APP_URL=https://your-space-name.hf.space
```

**可选配置：**
```
LOG_LEVEL=INFO
SERVER_WORKERS=1
ACCOUNT_STORAGE=local
DATA_DIR=/data
```

**代理配置（如需要）：**
```
GROK_PROXY_EGRESS_MODE=url
GROK_PROXY_EGRESS_PROXY_URL=http://your-proxy:port
```

### 3. 启用 Persistent Storage（重要！）

为了保持账号数据和配置不丢失：

1. 在 Space Settings 中启用 **Persistent Storage**
2. 这将在 `/data` 目录下保存所有数据
3. 配合 [hf-keepalive](https://github.com/wankuzidi/hf-keepalive) 防止休眠

### 4. 配置保活（推荐）

使用 hf-keepalive 项目防止 Space 休眠：

1. Fork [wankuzidi/hf-keepalive](https://github.com/wankuzidi/hf-keepalive)
2. 在你的 fork 仓库中配置：
   - Variables: `HF_SPACES=https://your-space-name.hf.space`
   - Secrets: `HF_TOKEN=your_hf_token`（如果是私有 Space）
3. 启用 GitHub Actions
4. 建议设置为每 12 小时运行一次（cron: `0 */12 * * *`）

## 使用方法

### 访问管理后台

```
https://your-space-name.hf.space/admin/login
```

默认密码是你设置的 `APP_KEY`

### API 调用示例

```python
import openai

client = openai.OpenAI(
    api_key="your_api_key_here",
    base_url="https://your-space-name.hf.space/v1"
)

response = client.chat.completions.create(
    model="grok-4.20-auto",
    messages=[
        {"role": "user", "content": "Hello, Grok!"}
    ]
)

print(response.choices[0].message.content)
```

### 添加账号

1. 登录管理后台
2. 进入 "账号管理" 页面
3. 点击 "导入账号"
4. 输入 X (Twitter) 账号的 Token

## 注意事项

⚠️ **重要提示：**

1. **必须启用 Persistent Storage**，否则每次重启都会丢失数据
2. **配置保活项目**，防止 Space 因长时间无访问被暂停
3. **保护你的 API Key**，不要在公开场合泄露
4. 遵守 Grok 和 Hugging Face 的使用条款

## 数据持久化说明

启用 Persistent Storage 后，以下数据会被保存：

- `/data/accounts.db` - 账号数据库
- `/data/config.toml` - 运行时配置
- `/data/images/` - 缓存的图片
- `/data/videos/` - 缓存的视频
- `/data/cache/` - 其他缓存文件

## 故障排查

### Space 频繁重启
- 检查是否启用了 Persistent Storage
- 检查日志查看是否有错误信息

### 账号数据丢失
- 确认 Persistent Storage 已启用
- 检查 `DATA_DIR` 是否设置为 `/data`
- 使用保活项目防止 Space 休眠

### API 调用失败
- 检查 `APP_URL` 是否正确设置
- 检查 API Key 是否正确配置
- 查看后台日志排查具体错误

## 许可证

MIT License - 详见原项目 [chenyme/grok2api](https://github.com/chenyme/grok2api)

---

**免责声明：** 本项目仅供学习交流使用，请遵守相关服务的使用条款。