安装生图工具

UseGoodAI 中转站生图工具让 Codex 直接生成、修改并展示图片，适合已经完成快速开始、希望在 Codex 对话中使用图片模型的用户。

安装后，Codex 会自动调用工具并把成品图显示在当前对话中。安装器会写入 $CODEX_HOME/tools/usegoodai-imagines-tool/、$CODEX_HOME/skills/usegoodai-image-generation/ 和 $CODEX_HOME/AGENTS.md；用户不需要手动修改这些文件。

1. 创建专门画图分组的 API Key

进入 UseGoodAI 管理后台的 API 密钥 页面，额外创建一个 API Key，名称可以填写“画图专用”。

把这个 Key 的分组设置为 专门画图分组，保存后点击复制。这里使用的不是快速开始中配置 Codex 对话模型的普通 Key，两个 Key 不要复制反。

安装器无法判断 Key 是否来自正确分组，复制前必须自己核对分组名称。

2. 在终端安装生图工具

Windows 按 Win + X，点击终端或 Windows PowerShell，粘贴运行：

powershell

irm https://docs.usegoodai.com/install/usegoodai-imagines-tool/install.ps1 | iex

看到“请粘贴专门画图分组的 Key”时，粘贴第 1 步复制的 Key，然后按回车。安装器只会下载 Windows x64 程序，不需要 Python、Node 或管理员权限。

Mac 用户看这里

Apple Silicon 和 Intel Mac 使用同一条命令，安装脚本会自动识别芯片。打开终端运行：

bash

curl -fsSL https://docs.usegoodai.com/install/usegoodai-imagines-tool/install.sh | bash

看到 Key 输入提示后，粘贴第 1 步复制的专门画图分组 Key，然后按回车。安装器只下载当前 Mac 对应的一个程序。

3. 打开 Codex 开始生图

安装完成后打开 Codex，新建一个任务。Codex 已经打开时不用退出应用，直接新建任务即可；不要沿用安装前的旧对话。

先发送下面这句话了解入口和可用模型：

text

介绍一下中转站生图工具怎么使用，有哪些模型。

随后直接描述要画的内容：

text

画一张白底红苹果。

生成成功后，图片会直接显示在当前 Codex 对话中，不会只返回文件路径。

查看常用说法

直接生图：

text

画一张雨后城市街道的人物照片，电影感，自然光影，不要文字和水印。

指定模型：

text

使用 nano-banana-pro 画一张中式庭院夜景。

使用参考图或修改图片：

text

参考当前文件夹里的产品照片，生成一张白底电商主图。

text

把这张图片的背景改成浅灰色，保留主体不变。

一次生成多张：

text

按同一个要求生成 3 张图片，并全部显示在对话中。

对比模型：

text

用同一个要求分别调用 gpt-image-2 和 nano-banana-pro，各生成一张并显示出来。

查看支持的模型、尺寸和参数

模型	接口	尺寸或比例参数	其它参数和能力
`gpt-image-2`	Images	`size`、`quality`、`output_format`	支持参考图、修图、多图
`gpt-image-1k-th`	Images	固定 `1024x1024`	`quality=low/high`，支持参考图、修图、多图
`gpt-image-2-adobe`	Images	`1024x1536`、`1536x2304`、`2304x3456`	固定 `quality=low`，只支持生图和多图
`grok-imagine-image`	Images	`resolution=1k/2k`、7 种 `aspect_ratio`	`quality=low/medium/high`，支持参考图、修图、多图
`nano-banana-2`	Responses	`resolution=512/1k/2k/4k`、15 种 `aspect_ratio`	不使用 `size`、`quality`、`output_format`，支持参考图、修图、多图
`nano-banana-pro`	Responses	`resolution=1k/2k/4k`、工具支持的 15 种 `aspect_ratio`	不使用 `size`、`quality`、`output_format`，支持参考图、修图、多图

Codex 会按照用户明确提出的模型、数量、尺寸和画面要求调用工具，不会替用户决定创作内容。价格见模型价格。

查看更新、安装位置和卸载方式

需要更新时，直接对 Codex 说：

text

更新生图工具。

已经保存专门画图分组 Key 时，更新不会要求再次输入。

默认安装位置：

内容	位置
工具和专门画图 Key	`$CODEX_HOME/tools/usegoodai-imagines-tool/`
生图 Skill	`$CODEX_HOME/skills/usegoodai-image-generation/`
Codex 全局调用规则	`$CODEX_HOME/AGENTS.md`

未设置 CODEX_HOME 时，Windows 使用 C:\Users\你的用户名\.codex\，Mac 使用 ~/.codex/。生成图片保存在当前项目的 images 文件夹；没有打开项目时保存在桌面的 images 文件夹。

需要卸载时，直接对 Codex 说“卸载中转站生图工具”。专门画图 Key 默认保留，永久删除前需要单独确认。

安装或生图失败先看这里

遇到的问题	检查动作
安装器提示 Key 无效或生图返回鉴权错误	回到 API 密钥页面，确认复制的是专门画图分组的 Key，再重新安装
安装后 Codex 不知道生图工具	新建一个 Codex 任务，不要继续使用安装前的旧对话
Codex 只回复图片路径或图片只出现在折叠的中间过程	确认当前任务已经读取生图 Skill；最终回复必须用绝对路径 Markdown 图片语法再次嵌入图片
生图接口返回错误	本次请求会直接停止，不会自动重试或更换模型；稍后重新发起一次新请求
图片无法写入	打开一个有写入权限的项目后再试，或让 Codex 使用桌面 `images` 文件夹

不用一键安装：让 Codex 创建 Python 脚本

这个方法适合不使用一键安装器、希望把生图脚本和规则只放在当前项目中的用户。脚本和规则只对当前项目生效，不会安装全局 Skill。

把下面整段提示词发给 Codex：

text

请完整阅读并严格按照这个页面操作：
https://docs.usegoodai.com/image-video-group-image.html

根据页面中的“自建 Python 脚本的通用规则”和各模型参数折叠，完成以下任务：
1. 在当前文件夹创建一个可运行的单文件生图脚本，文件名为“生成图片.py”。
2. 创建或更新当前项目根目录的 AGENTS.md，保留原有内容，并写入页面规定的“项目生图规则”。
3. 除“生成图片.py”和 AGENTS.md 外，不创建其它工程文件，也不自动安装依赖。
4. 为 UseGoodAI API Key 保留一个明显的配置项，创建完成后只让我填写这个值。
5. 脚本是给 Codex 调用的，不要让我手工修改图片描述、模型或运行命令。
6. 脚本必须接收 Codex 每次传入的完整图片描述、模型、数量、规格和可选原图文件，不能把图片描述写死在脚本里。
7. 默认使用 gpt-image-2；用户指定其它已支持模型时，按页面中的模型和接口映射发送请求。
8. 每个模型请求只发送一次，禁止自动重试或静默更换模型。
9. 成功后只保存最终图片，并立即使用 view_image 打开每张图片，确认图片能够正常显示。
10. view_image 成功后，最终回复仍必须用绝对路径 Markdown 图片语法再次嵌入每张图片，例如：`![生成结果](/absolute/path/image.png)`。不得只依赖中间工具输出，也不得只回复普通文件路径或普通 Markdown 文件链接。失败时显示脱敏错误，不创建空图片或运行记录。

以后在这个项目中直接对 Codex 说“画一张……”即可。需要比较模型时，明确说出模型名；Codex 应使用同一要求逐个调用，每个模型只请求一次。

GPT Image 2：尺寸、质量、比例和接口

gpt-image-2 是默认模型，支持文生图、参考图、修图和多图。它使用 Images 接口，使用 size、quality 和 output_format，不能使用 Banana 的 --aspect-ratio。

参数	写法
`model`	固定为 `gpt-image-2`
`prompt`	必填，写完整图片描述或修改指令
文生图接口	`POST /v1/images/generations`
参考图和修图接口	`POST /v1/images/edits`
`size`	`auto` 或 `WIDTHxHEIGHT`；宽高为 16 的倍数，单边不超过 3840，长短边比例不超过 3:1，总像素 655360 至 8294400
`quality`	`low`、`medium`、`high`、`auto`；默认 `high`
`output_format`	当前工具使用 `png`
`n`	`1` 至 `10`；工具把多图拆成独立单张请求
参考图	使用 `edit`，每张图片重复传入 `--image`

用户说“3:4”时转换为 --size 768x1024，不要把 3:4 直接填进 size。下面是本站已验证的尺寸示例：

比例	`size` 示例
1:1	`1024x1024`
3:2	`1152x768`
2:3	`768x1152`
3:4	`768x1024`
4:3	`1024x768`
4:5	`768x960`
5:4	`960x768`
9:16	`720x1280`
16:9	`1280x720`
21:9	`1344x576`
9:21	`576x1344`
3:1	`1536x512`
1:3	`512x1536`

比例超过 3:1 的 4:1、1:4、8:1、1:8 不支持。--aspect-ratio 3:4 也不支持。

GPT Image 1K TH：固定尺寸、质量和接口

参数	写法
`model`	固定为 `gpt-image-1k-th`
`prompt`	必填，写完整图片描述或修改指令
文生图接口	`POST /v1/images/generations`
参考图和修图接口	`POST /v1/images/edits`
`size`	只使用 `1024x1024`
`quality`	`low` 或 `high`；默认 `high`
`output_format`	当前工具使用 `png`
`n`	`1` 至 `10`；多图由工具拆成独立单张请求
参考图	使用 `edit`，每张图片重复传入 `--image`

这个模型不使用 --aspect-ratio、--resolution 或 2K/4K 尺寸。需要横图、竖图或其它比例时，使用 gpt-image-2。

GPT Image 2 Adobe：竖图尺寸、质量和接口

参数	写法
`model`	固定为 `gpt-image-2-adobe`
`prompt`	必填，写完整图片描述
文生图接口	`POST /v1/images/generations`
`size`	`1024x1536`、`1536x2304`、`2304x3456`
`quality`	只使用 `low`
`output_format`	当前工具使用 `png`
`n`	`1` 至 `10`；多图由工具拆成独立单张请求
参考图和修图	不开放；需要参考图或修图时使用 `gpt-image-2`

Adobe 的三个尺寸都是 2:3 竖图，不使用 --aspect-ratio 或 --resolution。

Grok Imagine：分辨率、比例、质量和接口

grok-imagine-image 使用 Images 接口，尺寸通过 resolution 和 aspect_ratio 表达，不能发送 GPT Image 的 size。

参数	写法
`model`	固定为 `grok-imagine-image`
`prompt`	必填，写完整图片描述或修改指令
文生图接口	`POST /v1/images/generations`
参考图和修图接口	`POST /v1/images/edits`
`resolution`	`1k`、`2k`；默认 `1k`
`aspect_ratio`	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`
`quality`	可选 `low`、`medium`、`high`；未指定时使用模型默认值
`n`	`1` 至 `9`；工具把多图拆成独立单张请求
请求体输出字段	`response_format: "b64_json"`；保存扩展名按返回图片实际格式判断
参考图和修图	使用 `edit` 和重复的 `--image`；直接使用原图规格，不传 `resolution`、`aspect_ratio` 或 `quality`

已验证的尺寸示例：

规格	返回尺寸
`1k` + `1:1`	`1024x1024`
`2k` + `1:1`	`2048x2048`
`2k` + `16:9`	`2816x1584`
`1k` + `16:9`	`1280x720`
`1k` + `9:16`	`720x1280`
`1k` + `4:3`	`1152x864`
`1k` + `3:4`	`864x1152`
`1k` + `3:2`	`1248x832`
`1k` + `2:3`	`832x1248`

命令示例：

bash

usegoodai-imagines-tool generate \
  --model grok-imagine-image \
  --prompt "用户给出的完整图片描述" \
  --resolution 2k \
  --aspect-ratio 16:9 \
  --quality high \
  --n 1

Nano Banana 2：分辨率、比例、参考图和接口

nano-banana-2 使用 Responses 接口。文生图、参考图和修图都使用同一个请求入口，不使用 Images 接口。

请求地址是 POST https://api.usegoodai.com/v1/responses，请求头使用 Authorization: Bearer <API_KEY> 和 Content-Type: application/json。

参数	写法
`model`	固定为 `nano-banana-2`
`prompt`	放在 `input[0].content` 的 `input_text.text`
接口	`POST /v1/responses`
`input`	数组；文本放在 `input_text.text`，图片放在 `input_image.image_url`
`stream`	固定为 `false`
`response_format.type`	固定为 `image`
`response_format.mime_type`	当前固定为 `image/png`
`resolution`	工具参数为 `512`、`1k`、`2k`、`4k`；请求体字段为 `image_size`
`aspect_ratio`	工具参数和请求体字段都使用比例字符串
`quality`、`size`、`output_format`	不使用
多图数量	工具内部拆成多个单张 Responses 请求，不发送顶层 `n`；同一画面要求 3 张时发送 3 个单张请求
参考图和修图	使用 `edit` 并重复传入 `--image`；PNG、JPEG、WebP 各 1 张以及 2 张、4 张不同图片已验证
参考图数量	本地工具最多 14 张；14 张远端请求尚未形成支持结论

已验证的 image_size：512、1K、2K、4K。

已验证的 aspect_ratio：

text

1:1、3:2、2:3、3:4、1:4、4:1、4:3、4:5、
5:4、1:8、8:1、9:16、16:9、21:9、9:21

最小请求体：

json

{
  "model": "nano-banana-2",
  "input": [{
    "role": "user",
    "content": [{
      "type": "input_text",
      "text": "一只红苹果放在白色桌面上"
    }]
  }],
  "stream": false,
  "response_format": {
    "type": "image",
    "mime_type": "image/png",
    "aspect_ratio": "1:1",
    "image_size": "1K"
  }
}

参考图或改图时，在同一个 content 数组中增加：

json

{
  "type": "input_image",
  "image_url": "data:image/png;base64,<图片的Base64内容>"
}

image_url 必须是 PNG、JPEG 或 WebP 的 Data URL，例如 data:image/png;base64,<...>。文本、参考图和修改指令都放在 input[0].content，不能写成顶层 prompt 或 images 字段。

Nano Banana Pro：分辨率、比例、参考图和接口

nano-banana-pro 使用与 Nano Banana 2 相同的 Responses 请求结构，但分辨率从 1k 开始，不支持 512。

参数	写法
`model`	固定为 `nano-banana-pro`
`prompt`	放在 `input[0].content` 的 `input_text.text`
接口	`POST /v1/responses`
`input`	数组；文本使用 `input_text`，图片使用 `input_image`
`stream`	固定为 `false`
`response_format.type`	固定为 `image`
`response_format.mime_type`	当前固定为 `image/png`
`resolution`	`1k`、`2k`、`4k`；请求体字段为 `image_size`
`aspect_ratio`	`1:1`、`3:2`、`2:3`、`3:4`、`1:4`、`4:1`、`4:3`、`4:5`、`5:4`、`1:8`、`8:1`、`9:16`、`16:9`、`21:9`、`9:21`
`quality`、`size`、`output_format`	不使用
多图数量	工具内部拆成多个单张 Responses 请求，不发送顶层 `n`
参考图和修图	使用 `edit` 并重复传入 `--image`；最多 14 张由本地参数校验限制

已远端验证的 Pro 规格包括 1K + 1:1 -> 1024x1024 和 1K + 16:9 -> 1408x768。其它比例沿用工具参数表，但本轮没有把 Nano Banana 2 的远端结果直接套用到 Pro。

请求体的关键字段：

json

{
  "model": "nano-banana-pro",
  "input": [{
    "role": "user",
    "content": [{
      "type": "input_text",
      "text": "用户给出的完整图片描述"
    }]
  }],
  "stream": false,
  "response_format": {
    "type": "image",
    "mime_type": "image/png",
    "aspect_ratio": "16:9",
    "image_size": "1K"
  }
}

自建 Python 脚本的通用规则

统一接口和鉴权

模型	生成接口	参考图和修图
`gpt-image-2`	`/v1/images/generations`	`/v1/images/edits`
`gpt-image-1k-th`	`/v1/images/generations`	`/v1/images/edits`
`gpt-image-2-adobe`	`/v1/images/generations`	不开放
`grok-imagine-image`	`/v1/images/generations`	`/v1/images/edits`
`nano-banana-2`	`/v1/responses`	`/v1/responses`
`nano-banana-pro`	`/v1/responses`	`/v1/responses`

API 根地址固定为 https://api.usegoodai.com，鉴权使用 Authorization: Bearer <API_KEY>。脚本不得读取或覆盖 Codex 的 auth.json，也不得把 Key 写入请求记录、错误信息或生成图片目录。

解析和保存

Images 响应检查 data[].b64_json 和 data[].url；URL 只下载一次。
Responses 只扫描 output，解析结构化图片、Markdown Data URL 或 HTTPS 图片链接。
只有图片字节非空且文件签名有效时才算成功，扩展名按照实际 PNG 或 JPEG 内容决定。
输出目录使用当前项目的 images；没有项目时使用桌面的 images。
只保留最终图片，不创建请求、响应、摘要或图片专属子目录。
单图向 Codex 返回 output_file，多图返回 output_files；Codex 必须逐张调用 view_image。
view_image 成功后，最终回复必须用每张图片的绝对路径和 Markdown 图片语法再次嵌入全部图片；普通路径和普通文件链接不能代替图片嵌入。
HTTP 非 2xx、解码失败或保存失败时立即停止，不自动重试、不更换模型。

写入当前项目 AGENTS.md 的规则必须包含：固定使用本项目的 生成图片.py；模型只能从“查看支持的模型、尺寸和参数”表中选择；每次调用前说明模型；不读取或显示 Key；失败不重试；成功后逐张调用 view_image，并在最终回复中用绝对路径 Markdown 图片语法再次嵌入所有成功图片。

安装生图工具 ​

1. 创建专门画图分组的 API Key ​

2. 在终端安装生图工具 ​

3. 打开 Codex 开始生图 ​

统一接口和鉴权 ​

解析和保存 ​

安装生图工具

1. 创建专门画图分组的 API Key

2. 在终端安装生图工具

3. 打开 Codex 开始生图

统一接口和鉴权

解析和保存