waoo/GROK2_SETUP.md

Grok2 API 集成说明

概述

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

配置步骤

1. 启动服务

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

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. 使用以下模板配置：

{
  "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 视频接口