# Grok2 API 集成说明

## 概述

本项目已集成 Grok2 API 支持，可以使用 Grok2 进行图像和视频生成。

## 配置步骤

### 1. 启动服务

确保 Docker 镜像已构建并启动：

```bash
cd /opt/stacks/waoo
docker-compose up -d
```

### 2. 配置 Grok2 Provider

1. 访问 http://localhost:13000
2. 登录后进入 **个人设置 > API 配置**
3. 找到 **Grok2 API** 提供商
4. 点击 **配置** 按钮
5. 填写以下信息：
   - **Base URL**: `http://45.128.210.183:8048`
   - **API Key**: （如果需要的话填写你的 API Key）

### 3. 配置模型

在 Grok2 API 提供商下，已预置以下模型：

#### 图像生成模型
- **模型 ID**: `grok-imagine-1.0`
- **名称**: Grok Imagine 1.0
- **支持尺寸**:
  - 1280x720
  - 720x1280
  - 1792x1024
  - 1024x1792
  - 1024x1024

#### 视频生成模型
- **模型 ID**: `grok-imagine-1.0-video`
- **名称**: Grok Imagine 1.0 Video
- **支持时长**: 6-30 秒
- **支持质量**: standard (480p), high (720p)

### 4. 配置视频模型模板（重要）

由于 Grok2 的视频接口与标准 OpenAI 格式不同，需要为视频模型配置模板：

1. 在 **Grok Imagine 1.0 Video** 模型卡片中，点击 **高级设置**
2. 找到 **兼容媒体模板** 选项
3. 点击 **AI 助手** 或 **手动配置**
4. 使用以下模板配置：

```json
{
  "version": 1,
  "mediaType": "video",
  "mode": "sync",
  "create": {
    "method": "POST",
    "path": "/v1/videos",
    "contentType": "application/json",
    "bodyTemplate": {
      "model": "{{model}}",
      "prompt": "{{prompt}}",
      "image_reference": "{{image}}",
      "seconds": "{{duration}}",
      "quality": "{{quality}}",
      "size": "{{size}}"
    }
  },
  "response": {
    "outputUrlPath": "data[0].url"
  }
}
```

5. 点击 **验证模板** 确保配置正确
6. 保存配置

### 5. 设置默认模型（可选）

在 **默认模型配置** 区域，可以将 Grok2 模型设置为默认：

- **角色模型**: Grok Imagine 1.0
- **场景模型**: Grok Imagine 1.0
- **分镜模型**: Grok Imagine 1.0
- **视频模型**: Grok Imagine 1.0 Video

## 使用说明

### 图像生成

1. 进入项目的资产库或分镜页面
2. 选择使用 Grok2 图像模型
3. 输入提示词
4. 选择尺寸（支持 Grok2 特有的 1280x720 和 720x1280）
5. 点击生成

### 视频生成

1. 准备一张起始图片
2. 在视频生成界面选择 Grok Imagine 1.0 Video 模型
3. 输入提示词（可选）
4. 设置时长（6-30 秒）
5. 选择质量（standard 或 high）
6. 点击生成

## 注意事项

1. **图像生成**：Grok2 图像生成使用标准 OpenAI 兼容接口，可以直接使用
2. **视频生成**：必须配置模板才能正常工作，因为 Grok2 的视频接口路径和参数与标准格式不同
3. **API 地址**：确保 `http://45.128.210.183:8048` 可以从 Docker 容器内访问
4. **网络问题**：如果遇到连接问题，检查防火墙和网络配置

## 故障排查

### 图像生成失败

1. 检查 Base URL 是否正确
2. 检查 API Key 是否有效（如果需要）
3. 查看浏览器控制台或服务器日志

### 视频生成失败

1. 确认已正确配置视频模型模板
2. 检查模板中的字段映射是否正确
3. 确认 Grok2 API 服务正常运行
4. 查看详细错误信息

### 测试连接

在配置 Provider 后，可以点击 **测试连接** 按钮验证配置是否正确。

## 技术细节

### 实现方式

- Grok2 被实现为一个预设 Provider，使用 OpenAI 兼容网关
- 图像生成通过扩展尺寸白名单支持 Grok2 特有尺寸
- 视频生成通过模板系统映射 Grok2 的自定义接口格式

### 路由配置

- Provider Key: `grok2`
- Gateway Route: `openai-compat`
- API Mode: `openai-official`

### 字段映射

视频生成字段映射：
- `duration` → `seconds`
- `image` → `image_reference`
- `quality` → `quality` (standard/high)
- `size` → `size` (宽高比)

## 更新日志

- 2026-03-11: 初始集成 Grok2 API 支持
  - 添加图像生成支持（1280x720, 720x1280 尺寸）
  - 添加视频生成支持（6-30 秒，standard/high 质量）
  - 配置模板系统适配 Grok2 视频接口