在 Codex 中调用图像生成

让 Codex CLI 在对话里直接生成图片：用 gpt-image-2 模型，通过一个自定义 slash command /imagegen 触发。生成是异步的（提交任务 → 轮询结果），整个流程由 Codex 的 bash 工具完成，不需要额外软件。

前置条件

  1. 已经按 Codex 快速开始 完成 Codex 安装和 ~/.codex/config.toml 配置（base_url = "https://relay.upthos.com"）。
  2. 你的 API Key 属于 Codex / OpenAI 系列分组（Codex Lite / Codex Pro / Codex Max 任意一个）。Claude / Gemini 分组的 Key 无法调用图像 API。
  3. ~/.codex/config.toml 中需要 sandbox_mode = "danger-full-access"（快速开始的模板不再预置这一行，需自行加上），否则 Codex 不能执行 curl。

1. 暴露 API Key 给 Codex 的 bash 工具

~/.codex/auth.json 里的 Key 默认只用于 Codex 与上游通信，不会注入到 bash 子进程，所以 curl 命令拿不到。两种做法选其一：

方式 A：写到 shell 环境变量（推荐）

# macOS / Linux —— 写入 ~/.zshrc 或 ~/.bashrc
echo 'export OPENAI_API_KEY="sk-relay-你的Key"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-relay-你的Key", "User")

方式 B：每次启动 Codex 时注入

OPENAI_API_KEY=$(jq -r .OPENAI_API_KEY ~/.codex/auth.json) codex

验证：在 Codex 里输入 运行 echo $OPENAI_API_KEY，能看到密钥前缀就说明 OK。

2. 创建 slash command

在 ~/.codex/prompts/ 目录下（不存在就 mkdir -p ~/.codex/prompts）新建文件 imagegen.md：

---
description: 用 Upthos Relay 生成图片（gpt-image-2）
---

用户想生成一张图片，描述：{{args}}

请使用 bash 工具按以下流程执行（**严格按字段路径解析返回，不要凭空猜结构**）：

### 步骤 1：提交任务

curl -sS -X POST https://relay.upthos.com/v1/images/tasks \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "<把用户描述填进来，注意转义双引号>",
    "size": "1:1",
    "resolution": "1k"
  }'

返回：`{"code":0,"data":[{"status":"submitted","task_id":"task_xxx"}]}`
从 `data[0].task_id` 取出任务 ID。

### 步骤 2：轮询结果

每 3 秒调用一次（最多 60 次，约 3 分钟）：

curl -sS https://relay.upthos.com/v1/images/tasks/<task_id> \
  -H "Authorization: Bearer $OPENAI_API_KEY"

判断 `data.status`：
- `processing` → 继续等
- `completed` → 从 `data.result.images[0].url[0]` 取出图片 URL，输出给用户
- `failed` → 把 `data.error.message` 报给用户，结束

### 步骤 3：输出格式

最终用 markdown 图片语法呈现：

![generated](图片URL)

紧跟一行注明：分辨率、用时、过期时间（unix 时间戳转可读格式）。

### 参数说明（用户没指定就用默认）

- `size`：`1:1` / `16:9` / `9:16` / `3:2` / `2:3` / `auto`
- `resolution`：`1k`（默认）/ `2k` / `4k`
- 多张图：`n` 支持 1..4，单任务可一次生成多张（也可以并发提交多任务）

### 错误处理

- HTTP 402 / `INSUFFICIENT_BALANCE` → 提示用户余额不足，前往 https://relay.upthos.com/dashboard 充值
- HTTP 403 → 当前 Key 所在分组不支持图像 API，请使用 Codex 系列分组的 Key
- HTTP 429 → 提示触发限速，稍后重试

{{args}} 会被替换成用户在 /imagegen 后面输入的全部文本。

3. 试用

进入任意项目目录运行 codex，然后输入：

/imagegen 一只赛博朋克风格的猫，霓虹背光

或者带参数：

/imagegen 一只猫，2k，16:9

Codex 会调用 bash 提交任务、轮询、最后用 markdown 把图片 URL 渲染出来。图片 URL 默认有效期较长，请在过期前下载保存。

4. 价格

gpt-image-2 按张计费，与 Codex 订阅档位无关（订阅折扣只作用于代码模型，不作用于图像）。从余额扣费，订阅用户也是从余额扣，不占用订阅额度。

分辨率 单张价格 适用场景
1k ¥0.041 草图、缩略图、快速迭代
2k ¥0.082 主流插图、社媒配图
4k ¥0.123 高清出图、印刷物料

low / medium / high quality 三档同价，可放心切换。

把请求里的 model 换成 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst 即可用 GPT Image 2.5，价格与上表完全一致；不填 model 时默认仍是 gpt-image-2。

5. 进阶：图生图（参考图）

把 image_urls 字段加到提交请求里，传 1～N 张参考图的 URL（公网可访问的图片地址）：

{
  "model": "gpt-image-2",
  "prompt": "把这张图改成水彩风格",
  "size": "1:1",
  "resolution": "1k",
  "image_urls": ["https://example.com/source.png"]
}

如果你需要先把本地图片上传成临时 URL，可以先调用 POST /v1/images/uploads（multipart 上传单个文件）拿到一个短期公开 URL，再传给 image_urls。把这一步也写进 imagegen.md 让 Codex 自动完成即可。

常见问题（FAQ）

Q：返回 404 / "Images API is not supported for this platform"？
A：当前 Key 不在 OpenAI / Codex 系列分组下。在 控制台 创建一个新 Key，分组选 Codex Lite / Codex Pro / Codex Max 任一即可。

Q：返回 402 INSUFFICIENT_BALANCE？
A：图像生成始终从余额扣费，不消耗订阅额度。请前往 充值页面 补足余额。

Q：Codex 提示 OPENAI_API_KEY: unbound variable？
A：环境变量没有传到 Codex 启动的 bash。检查第 1 步是否完成，并 echo $OPENAI_API_KEY 验证当前 shell 能取到。

Q：能不能让 Codex 在普通对话里自动画图（不用敲 /imagegen）？
A：可以。把上面 prompt 文件里的指令直接写进 ~/.codex/AGENTS.md（Codex 的全局系统提示），告诉它"用户提到画图、生图、image 等关键词时，按以下流程执行..."，模型就会主动触发，无需 slash command。

Q：图片 URL 多久过期？
A：返回中包含 expires_at（unix 时间戳），通常为数天。请在过期前下载到本地或转存到自己的对象存储。

Q：能用 Python / Node SDK 调用吗？
A：可以。这套 API 走标准 HTTP，任何能发 POST 的客户端都能用。Slash command 只是为了让 Codex 内置流程化调用，不是必需。