# Codex 生图

Codex 支持在对话里直接生成图片。用法是触发 `$imagegen`,把你的画面描述交给它。

---

## 一、配置环境变量

生图走的是 OpenAI 的图像接口,需要在环境变量里按**标准字段名**配好地址和密钥:

| 变量 | 值 |
|------|-----|
| `OPENAI_BASE_URL` | `https://api.clomio.ai/v1` |
| `OPENAI_API_KEY` | 你的密钥 |

**macOS / Linux(写进 `~/.zshrc` 或 `~/.bashrc` 永久生效):**

```bash
export OPENAI_BASE_URL="https://api.clomio.ai/v1"
export OPENAI_API_KEY="你的密钥"
```

**Windows(PowerShell,永久):**

```powershell
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.clomio.ai/v1", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的密钥", "User")
```

> 地址可换成另外两条[线路](#/gateway-lines)的 `/v1`,如 `https://crs.qazwc.com/v1`。改完**重开终端**再启动 Codex 生效。

---

## 二、使用

在 Codex 对话里触发 `$imagegen`,描述你要的画面,例如:

```text
$imagegen 一只在钢琴上弹奏的橘猫,扁平插画风格,浅色背景
```

它会调用图像模型生成图片。

---

## 二点五、两条生图路径别混淆

Codex 生图在网关里可能走两条不同路径,排障时先确认是哪一条:

| 路径 | 典型入口 | 选模型方式 | 适合场景 |
|------|----------|------------|----------|
| Images API 原生路径 | `POST /v1/images/generations`、`POST /v1/images/edits` | 请求里的 `model` 是 GPT Image 模型,如 `gpt-image-2` | 单次生成/编辑、兼容 OpenAI Images API 的客户端 |
| Responses image tool | `POST /v1/responses` + `tools:[{"type":"image_generation"}]` | `model` 是文本/主线模型,图像由内置 `image_generation` tool 执行 | Codex 对话内生图、多轮编辑、和工具调用同一轮完成 |

所以:

- `/v1/images/*` 不是永远同一条上游路径：OpenAI **API-key** 账号通常走原生 Images API；OpenAI **OAuth/Codex** 账号会桥到 `/v1/responses` 的 `image_generation` tool；Grok OAuth 图片走 xAI/Grok images 兼容路径，不是 OpenAI Responses bridge。
- 用 `/v1/images/*` 时,`model` 要是图像模型;如果账号模型映射把 `gpt-image-2` 改成文本模型,上游会按 Images 端点报错。
- 用 `/v1/responses` 的 `image_generation` tool 时,`model` 不应写 `gpt-image-2`;应写支持工具的主线文本/多模态模型,让工具自己调用 GPT Image 能力。分组的 `openai_image_main_model` / image route 会影响 OAuth bridge 用哪个主模型；默认常见主模型不是 inbound 的 `gpt-image-*`。
- Clomio 的 OpenAI 图像能力只写 Images / Responses;不要把 Grok-only 的 `/v1/videos/*` 当成 OpenAI/Codex 能力写进这里。
- `OPENAI_BASE_URL` 仍然写带 `/v1` 的根地址,客户端或工具会自己拼 `/responses` 或 `/images/*`。

### Images API 原生 curl

文生图:

```bash
curl https://api.clomio.ai/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张白底产品海报,主体是一只橘猫咖啡杯",
    "size": "1024x1024"
  }'
```

图片编辑 multipart:

```bash
curl https://api.clomio.ai/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F model=gpt-image-2 \
  -F prompt="把背景换成浅灰色摄影棚" \
  -F image=@input.png
```

### Responses image tool 示例

```json
{
  "model": "gpt-5.4",
  "input": "生成一张白底产品海报,主体是一只橘猫咖啡杯",
  "tools": [{ "type": "image_generation", "size": "1024x1024" }],
  "tool_choice": { "type": "image_generation" }
}
```

`image_generation_call` 的结果通常包含 base64 图片;多轮编辑可以继续带 `previous_response_id`。

注意三件事不要混淆:

- `tools:[{"type":"image_generation"}]` 是能力声明;真正要求本轮生图通常要加 `tool_choice:{"type":"image_generation"}` 或让请求模型/意图明确进入图片路径。
- Codex bridge 开启时,普通 Responses/Codex 请求可能自动注入 image tool 和 instructions;如果分组未开图像或当前账号不支持,仅声明的 tool 可能被剥离后走文本账号,显式生图意图则会被 403 拒绝。
- 网关会规范化旧字段,并可能把顶层 image-only model 改成主文本模型、把图片模型放入 tool;排查时看 request_id 下的实际上游模型,不要只看客户端原始 body。

---

## 平台能力边界

| 能力 | OpenAI/Codex 分组 | Grok 分组 | Claude 分组 |
|------|-------------------|-----------|-------------|
| `POST /v1/images/generations` / `edits` | 支持(取决于账号/模型/分组开关) | 支持 Grok 图像兼容路径 | 不支持 OpenAI Images |
| `POST /v1/responses` + `image_generation` tool | 支持 Codex/Responses 生图 | 不作为 Grok Messages/Responses 能力 | 不支持 |
| `/v1/videos*` | 不支持 | 仅 Grok/xAI-compatible 视频 | 不支持 |

因此本文只讲 OpenAI Images API 与 Responses `image_generation` tool。视频生成请放在 Grok 文档里,不要写成 Codex/OpenAI 能力。

### 图片常见错误

| 报错 | 多半原因 | 处理 |
|------|----------|------|
| `Images API is not supported for this platform` | Key 不在 OpenAI/Grok 图片分组 | 换 OpenAI 或 Grok 图片分组 |
| `model_not_found` / 图片模型不可用 | 模型名、分组模型列表或图片能力不匹配 | 以控制台模型列表和用量里的上游模型为准；持续异常时带 `x-request-id`、模型名和端点提交工单 |
| `images endpoint requires an image model` | 把主线文本模型写到了 Images 端点 | `/v1/images/*` 用 `gpt-image-*` 或 `grok-imagine-*` |
| Responses 主模型写成 `gpt-image-*` | 把 Images API 模型当成 Responses 对话模型 | Responses image tool 的 `model` 用主线文本/多模态模型,图像由 tool 执行 |
| `Videos API is not supported for this platform` | 把 OpenAI/Codex 生图配置拿去调 videos | Videos 仅 Grok 分组,见 [Videos](#/api-videos) |

## 三、提示"工具不可用"怎么办

如果触发后提示生图工具不可用,可以安装开源的 **[codex-image](https://github.com/IanShaw027/codex-image)** skill 来补上这个能力。它面向"真正保存文件、精确路径、多图编辑、批量任务"的本地生图工作流。

### 安装

用 Codex 自带的 skill 安装器(任选一种):

```bash
# 方式一:按仓库 + 路径安装
python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo IanShaw027/codex-image \
  --path skills/codex-image
```

```bash
# 方式二:按 GitHub URL 安装
python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --url https://github.com/IanShaw027/codex-image/tree/main/skills/codex-image
```

```bash
# 方式三:手动克隆复制
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/IanShaw027/codex-image.git /tmp/codex-image
cp -r /tmp/codex-image/skills/codex-image "${CODEX_HOME:-$HOME/.codex}/skills/"
```

装完**重启 Codex**。需要 Python 3.11+。

### 它需要的环境变量

和上面一致——`OPENAI_API_KEY` 与 `OPENAI_BASE_URL`(API key 模式下 `OPENAI_BASE_URL` 必填)。它也会从 `$CODEX_HOME/auth.json`、`config.toml` 里读取凭证。

### 它的命令

这个 skill 不是 `$imagegen`,而是通过自己的脚本调用,子命令包括:

| 子命令 | 作用 |
|--------|------|
| `generate` | 生成新图 |
| `edit` | 编辑/合成输入图(带 `--image` 时自动用) |
| `generate-batch` | 按 JSONL 批量生成 |

示例:

```bash
bash "${CODEX_HOME:-$HOME/.codex}/skills/codex-image/scripts/codex-image" \
  generate --model gpt-image-2 --size 3840x2160 "一只弹钢琴的橘猫"
```

Windows 用 `codex-image.cmd`。生成的图默认保存到 `${CODEX_HOME:-~/.codex}/generated_images/`,也可用 `--out` / `--out-dir` / `--name` 指定路径。

可选的调节变量:`CODEX_IMAGE_MODEL`、`CODEX_IMAGE_SIZE`、`CODEX_IMAGE_QUALITY`、`CODEX_IMAGE_OUTPUT_DIR`、`CODEX_IMAGE_FORMAT` 等。

---

## 常见问题

**报 401 / 鉴权失败?** 检查 `OPENAI_BASE_URL` 是否为 `https://api.clomio.ai/v1`(注意带 `/v1`)、`OPENAI_API_KEY` 是否正确未过期、密钥分组是否支持图像模型。

**改了环境变量没生效?** 环境变量在进程启动时只读一次,改完要**重开终端**再启动 Codex。

> 其余报错见 [故障排查](#/troubleshooting);Codex 其他配置见 [Codex 配置详解](#/codex-config)。