# Grok Canvas

**简体中文** | [English](README.en.md)

**把 Grok 的图片和视频生成，放进一张无限画布。**

登录自己的 Grok 账号，连接参考图、生成图片，再把图片变成视频。在同一张画布里保留素材和不同版本，继续尝试新的方向。

我一直想做一个自己的无限画布。借着 Grok 的图片与视频生成能力，把这个想法做成了一个可以实际创作的小工具，也希望让已有 Grok 订阅的朋友更方便地使用自己的可用额度。

> 个人开发的非官方项目，与 xAI / Grok 无隶属关系。当前为早期版本，供个人在电脑本地运行。作者已使用 Grok 订阅完成图片和视频生成；具体套餐覆盖范围尚未逐一验证。

## 可以做什么

- **图片生成与迭代**：文字生图、多图参考、提示词 `@` 引用，一次生成 1 / 2 / 4 张候选图。
- **图片接着做视频**：文字生视频、首帧、尾帧和参考图，支持 6 / 10 / 15 秒及声音开关。
- **把过程留在画布上**：拖动、缩放、连线、多画布管理；已有图片再次生成时保留原图，在新节点继续。
- **结果保存在本机**：素材、画布和生成记录落盘，可以查看生成参数并下载结果；视频任务保存状态以便恢复查询。

## 先了解账号与额度

项目通过 xAI OAuth 登录，不需要在项目里填写 API Key。目前使用 Grok Build 的 OAuth 客户端，**授权页会显示 Grok Build**，这是当前接入方式，并非 Grok Canvas 的独立官方授权客户端。该第三方接入的长期可用性与分发许可尚未获得单独确认，按实验性接入提供。

使用你自己的 Grok 账号额度，作者已通过 Grok 订阅验证图片和视频生成。具体可用功能与额度以账号实际情况为准，详情见 [Grok 官方说明](https://docs.x.ai/grok/faq)。

## 快速开始

需要 **Git、Node.js 22.18+ 和 pnpm 10.33.2**。仓库用 `.nvmrc` 固定了已验证的 Node.js 22.22.2；使用 nvm 时可先运行 `nvm install` 和 `nvm use`。

如果尚未安装 pnpm：

```sh
npm install -g pnpm@10.33.2
```

下载、安装并启动：

```sh
git clone https://github.com/wangxiaosu/grok-canvas.git
cd grok-canvas
pnpm install --frozen-lockfile
pnpm dev
```

在电脑浏览器访问 **[http://127.0.0.1:3210](http://127.0.0.1:3210)**。默认无需 `.env` 配置。

1. 点击右上角登录，在 xAI 授权页登录自己的账号并完成授权。
2. 返回画布，确认右上角显示已登录。若未自动返回，可通过登录浮层粘贴授权码完成；登录等待超过 10 分钟需重新发起。
3. 添加图片节点，输入提示词并生成第一张图。
4. 将图片节点连到另一个图片或视频节点，用作后续生成的素材；视频素材可指定首帧、尾帧或参考图。
5. 下载喜欢的结果。画布自动保存，下次启动同一份本地数据可继续使用。

停止服务时在终端按 `Ctrl+C`。日常使用也可以构建后启动：

```sh
pnpm build
pnpm start
```

`dev` 和 `start` 都使用本机 3210 端口，只运行其中一个。不要同时启动两个实例，也不要在已有开发服务运行时原地构建；检查生产构建可使用独立工作目录。

## 使用边界与常见问题

| 情况 | 说明 |
| --- | --- |
| 手机无法编辑 | 当前只提供电脑画布，最低窗口为 1100 × 640，推荐 1440 × 900。 |
| 登录后仍无法生成 | 登录成功不等于拥有模型权限。检查账号用量、套餐权限和服务端错误；认证过期时重新登录。 |
| 提示额度不足或限流 | 以 Grok 账号页面为准，等待额度恢复或按官方提示处理。重试生成可能再次消耗额度。 |
| 在哪里查看剩余额度 | 当前不展示剩余额度或费用预估，请到 Grok 账号的用量页面查看。 |
| 端口占用 / 页面 403 | 使用 `127.0.0.1:3210` 或 `localhost:3210`；当前访问校验与 OAuth 回调固定使用此端口，不支持任意换端口或域名。 |
| 图片上传失败 | 支持 PNG / JPEG / WebP，单张最多 20 MB；图片生成最多使用 5 张参考图。 |
| 视频不能选择 1080p | 带尾帧或参考图时最高 720p；仅首帧时比例跟随首帧。视频参考图最多 7 张。 |
| 视频完成但下载失败 | 保留任务记录，可重试保存；若上游临时链接已失效，需要重新生成。 |
| 关闭页面或服务 | 已保存的画布和素材保留；视频已保存的任务可恢复查询。图片生成期间建议保持页面和本地服务开启。 |
| 想部署到服务器 | 当前是单用户本机服务，没有多用户隔离，不支持直接公开部署或通过隧道开放给他人。 |

## 数据与隐私

默认存储位置（`~` 表示当前用户目录）：

```text
~/.grok-canvas/
  auth.json              # OAuth 登录凭据
  data/
    app-state.json       # 最近使用的画布
    canvases/            # 画布、节点和连线
    assets/              # 上传及生成的图片、视频
    generations/         # 与素材绑定的生成记录
    video-tasks/         # 视频请求和任务状态
```

生成记录保存原始提示词、实际提交提示词、模型、参数及参考图顺序，不会被后续编辑画布覆盖。上传素材和没有记录的旧素材不会凭空补出生成历史。删除画布不会同时删除素材文件。

生成请求由本机服务发送到 xAI，包含提示词和参与生成的参考图；生成结果从上游下载到本机。本地保存不等于离线生成。

需要备份作品时，停止服务后复制整个 `data` 目录。`auth.json` 包含敏感登录凭据，不要上传到 GitHub、发到 Issue 或作为作品备份分享。退出登录会清除本项目本地凭据，不等同于撤销账号侧的授权，也不会删除作品。

需要自定义存储位置时，把 [`.env.example`](.env.example) 复制为 `.env.local`，按注释设置绝对路径并重启服务。已有数据不会自动迁移到新路径。

## 开发与反馈

技术栈：Next.js、React、TypeScript、React Flow、Tailwind CSS。

```sh
pnpm typecheck
pnpm test
pnpm build
```

`pnpm check` 按顺序执行以上检查。自动化测试使用模拟请求，不需要登录或消耗 Grok 额度。欢迎通过 Issue 或 Pull Request 参与改进。

第一次体验时，欢迎在 [Issues](https://github.com/wangxiaosu/grok-canvas/issues) 反馈：安装是否顺利、图片与视频是否可用、创作过程中最卡在哪一步。请提供系统、Node.js 版本、操作步骤及脱敏后的报错；不要粘贴登录凭据。涉及安全问题时，请先联系维护者获取私密反馈渠道，不要在公开 Issue 发布漏洞细节。

## License

[MIT](LICENSE) © 2026 KyroWang。第三方依赖保留各自许可证；此许可证不授予 xAI 服务访问权限，也不替代其服务规则。