> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkBuddy-生图

> WorkBuddy 多模型生图配置：通过自定义连接器接入 GravitexAI 文生图与图生图模型

> 适用于 macOS 与 Windows，操作步骤一致（仅完全退出的快捷键不同）。本指南介绍如何通过「自定义连接器」将 GravitexAI 旗下的多款图像生成模型接入 WorkBuddy，实现一句话文生图 / 图生图，并支持多模型同主题对比。

## 一、能力简介

通过一次 JSON 配置，即可在 WorkBuddy 中调用 GravitexAI 的全系列图像模型，无需分别为每个模型注册账号：

| 能力 | 说明 |
| - | - |
| 一把密钥全模型 | 一个 GravitexAI 密钥即可调用 GPT 系列、Gemini 系列等多款图像模型 |
| 密钥本地保存 | 配置（含 API Key）仅保存在本机连接器配置中，不上传云端 |
| 短名快捷调用 | 为每个模型起一个易记的短名（如 `gemini-pro`），对话里直接说「用 flash 画」即可切换 |
| 多模型对比 | 一句话让多个模型画同主题图，直观对比效果 |
| 按量自主付费 | 图像生成费用由你直接向 GravitexAI 结算，不占用 WorkBuddy 自身积分 / 套餐额度 |

## 二、环境要求

* Windows 10 及以上，不支持 Windows 7 / 8 / 8.1
* macOS 12 (Monterey) 及以上

> [!TIP]
>
> 不满足上述要求的系统将无法启动 WorkBuddy。

## 三、前置条件

* 已在机器上安装 WorkBuddy
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`）
* **Windows 用户额外需要**：安装 [Node.js](https://nodejs.org/) LTS 版本（安装时一路默认即可），否则 `npx` 命令无法运行

## 四、快速开始

### 第一步：获取 GravitexAI API Key

1. 访问 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)
2. 点击「新建令牌」，命名并保存
3. 复制以 `sk-` 开头的密钥备用

### 第二步：打开「自定义连接器」入口

左侧边栏点击「专家 · 技能 · 连接器」→ 切换到「连接器」页签 → 点击右上角「自定义连接器」。

![WorkBuddy 自定义连接器入口](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/workbuddy-image-generation-1.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=51602bc7ae5132f1a9b2c39f57e38e69)

### 第三步：贴入 JSON 配置

将下方完整 JSON 粘贴进配置框，然后**把 `sk-你的key` 替换成你自己的密钥**，其余内容照抄：

```json theme={null}
{
  "mcpServers": {
    "gpt-image-2": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gpt-image-2"
      }
    },
    "gpt-flare": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gpt-image-2.5-flare"
      }
    },
    "gpt-sunburst": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gpt-image-2.5-sunburst"
      }
    },
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gpt-image-1"
      }
    },
    "gemini-pro": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gemini-3-pro-image"
      }
    },
    "gemini-flash": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gemini-3.1-flash-image"
      }
    },
    "gemini-2.5-flash": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gemini-2.5-flash-image"
      }
    },
    "gemini-flash-lite": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-你的key",
        "IMAGE_MODEL": "gemini-3.1-flash-lite-image"
      }
    }
  }
}
```

> [!NOTE]
>
> * 条目名（如 `gpt-flare`）可自定义，它就是 WorkBuddy 中显示的连接器名称。
> * **Windows 注意**：需先安装 Node.js（官网下载 LTS 版，安装时一路默认）；`command` 填 `npx` 即可，不要写成 `npx.cmd`。

### 第四步：重启并信任

**完全退出再重开 WorkBuddy：**

* macOS：`Cmd + Q`（仅关闭窗口不算退出）
* Windows：右键任务栏图标 →「关闭窗口并退出」，或 `Ctrl + Shift + Esc` 打开任务管理器确认 WorkBuddy 进程已结束，再重新打开

**然后逐一点击信任：**

1. 回到「连接器」页签 →「自定义连接器」列表
2. 对每个连接器点击**信任（Trust）** —— 建议只信任常用的 2～3 个（每个连接器 = 一个 npx 进程），其余想用再信任

> [!WARNING]
>
> 只关掉窗口不算退出；未完全重启会导致新添加的连接器不生效。务必通过 `Cmd + Q` / 任务管理器确认进程已结束后再重开。

### 第五步：开始使用

回到任务界面，通过「+ → 连接器」勾选需要的模型即可开始生图。详见下文的「日常使用」与「对话示例」。

## 五、模型速查表

| 连接器名（短名） | 实际模型 ID | 定位 |
| - | - | - |
| `gpt-image-2` | gpt-image-2 | GPT 通用主力 |
| `gpt-flare` | gpt-image-2.5-flare | GPT 新版 |
| `gpt-sunburst` | gpt-image-2.5-sunburst | GPT 新版另一风格 |
| `gpt-image-1` | gpt-image-1 | GPT 上代 |
| `gemini-pro` | gemini-3-pro-image | Gemini 最强 |
| `gemini-flash` | gemini-3.1-flash-image | 快速档 |
| `gemini-2.5-flash` | gemini-2.5-flash-image | 上代快速档 |
| `gemini-flash-lite` | gemini-3.1-flash-lite-image | 最便宜 |

> [!NOTE]
>
> 模型 ID 以 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 公布为准；如需接入表中未列出的模型（如 `seedream-5-0-260128`），无需改动配置，直接在对话中说模型全称即可临时调用。

## 六、日常使用

**连接器名 = 快捷指定**，不用记模型全称。三种用法：

* **定默认**：任务里「+」→「连接器」→ 勾选某个连接器，即为本次任务默认生图模型
* **快速指定**：对话里说「用 flash 画」「换 pro 再来一张」，用短名即可切换
* **临时用未配置的模型**：对话里直接说模型全称（如 `seedream-5-0-260128`），调用时覆盖默认值，无需改配置

**改默认模型**：自定义连接器不支持原地编辑 → 删除该连接器后重新添加（贴入把 `IMAGE_MODEL` 改好的 JSON）→ 完全重启 WorkBuddy 生效。

**生图方式：**

* 文生图：直接描述需求
* 图生图：提供参考图 + 描述改动

## 七、对话使用示例

**1. 普通文生图（用勾选的默认模型）**

> 帮我画一张 1024x1024 的扁平风格红色苹果图标

**2. 指定模型（说短名即可）**

> 用 gemini-pro 画一座雪山日出
> 换 flash 再来一张一样的
> 用 gpt-flare 把这张图改成水彩风

**3. 图生图（改已有图片）**

> 参考桌面这张「小羊吃草.png」，把背景改成红色
> 把这张图的白天改成夜晚，其他都不变

**4. 指定尺寸和画质**

> 画一张 1536x1024 的横版风景图，画质用 low（快出图）
> 帮我生成竖版 1024x1536 的手机壁纸，质量 high

尺寸可选：`1024x1024`（方）、`1536x1024`（横）、`1024x1536`（竖）
画质可选：`low`（快 / 省）、`auto`（默认）、`high`（精细，耗时 1～2 分钟）

**5. 批量出图对比**

> 用 gpt-image-2 和 gemini-pro 各画一张同主题的图，对比一下效果

## 八、常见问题

> [accordion] 列表里看不到我配置的连接器？
>
> 通常是以下原因之一：① JSON 中的 `sk-你的key` 仍是占位符未替换；② WorkBuddy 没有完全重启（仅关窗口不算，需 `Cmd + Q` 或任务管理器结束进程后再重开）。请确认密钥已替换、进程已彻底退出并重启。

> [accordion] 调用返回 401 是什么原因？
>
> ① 确认 API 密钥以 `sk-` 开头且没有粘贴多余的空格；② 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 检查令牌是否启用、余额是否充足。余额不足也会返回 401。

> [accordion] 图生图时返回 404？
>
> 部分站点图像编辑接口路径不同，需要为该连接器额外配置 `editPath` 参数（指向对应的 edits 路径）。请确认你的中转站该模型的图生图端点路径，并在 JSON 的 `env` 中补充对应配置。

> [accordion] Windows 提示“npx 不是内部或外部命令”？
>
> Node.js 未安装或未加入系统 PATH。请到 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本，安装时一路默认，安装完成后重启 WorkBuddy 再试。

> [accordion] 通过 GravitexAI 生图的费用怎么算？是否消耗 WorkBuddy 积分？
>
> 不会消耗 WorkBuddy 自身的积分或套餐额度。图像生成产生的全部费用由你直接向 GravitexAI 结算，请自行关注 GravitexAI 账户中的余额与用量，避免产生超出预期的支出。

> [accordion] 想换默认模型，能直接编辑连接器吗？
>
> 自定义连接器不支持原地编辑。需要：删除该连接器 → 重新添加（贴入把 `IMAGE_MODEL` 改好的 JSON）→ 完全重启 WorkBuddy 生效。

## 九、相关资源

* WorkBuddy 官网：[www.workbuddy.cn](https://www.workbuddy.cn)
* GravitexAI 密钥管理：[https://maas.gravitex.ai/#/api-keys](https://maas.gravitex.ai/#/api-keys)
* GravitexAI 模型广场：[https://maas.gravitex.ai/#/api-models](https://maas.gravitex.ai/#/api-models)
* 对话类模型接入指南（自定义模型 · OpenAI 兼容协议）：参见 [WorkBuddy 客户端集成指南](https://docs.gravitex.ai/cn/integrations/workbuddy.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.