# 用 Codex 生成图片（gpt-image-2.5）

Codex 支持通过安装 **tokenflows-image-gen** 技能来使用 `gpt-image-2.5` 系列模型生成或编辑图片（默认 `gpt-image-2.5-flare`，也可选择 `gpt-image-2.5-sunburst`）。安装后在 Codex 里输入 `/tokenflows-image-gen` 即可调用，支持文生图（按文字描述出图）和图生图（改一张已有的图）。

> tokenflows-image-gen 是跨客户端的通用技能：同一技能包也可解压到 Claude Code 的 `~/.claude/skills/`、Qoder 等 Agent 的技能目录使用，配置支持环境变量 `TOKENFLOWS_API_KEY` 或 `~/.tokenflows.env`（本教程以 Codex 的 `~/.codex/.env` 为例）。

## 前置条件

- **Codex**：已安装 Codex App 或 Codex CLI。
- **API Key**：在 [TokenFlows 控制台](https://dash.tokenflows.org/) 获取一个 API Key。

## 费用说明

通过 TokenFlows 使用 `gpt-image-2.5-flare`，每生成一张图片计费 **$0.3**，按次从额度中扣除。

> ⚠️ **风险提示**：Agent 在生成图片后会自行检查结果，如果觉得不合适，可能会自动发起多次请求来重新生成。所以你可能会看到使用记录中有多条调用。如果你需要严格控制每次只调用一次，建议直接通过 TokenFlows API `/images/generations` 接口手动调用，或通过 prompt 增强控制。

## 快速安装（AI 自动配置）

不想手动操作？把下面这句话复制给 Codex，它会读取本教程并自动完成安装：

```text
请完成 tokenflows-image-gen 技能的安装：
1. 从 https://tokenflows.org/skills/tokenflows-image-gen.zip 下载压缩包，解压到 ~/.codex/skills/ 目录，确保解压后得到 ~/.codex/skills/tokenflows-image-gen/SKILL.md 和 ~/.codex/skills/tokenflows-image-gen/scripts/ 下的 tokenflows-image-gen.sh 和 tokenflows-image-gen.ps1
2. 在 ~/.codex/.env 中写入：
   base_url=https://api-us.tokenflows.org/v1
   api_key=sk-xxx
3. api_key 先留占位 sk-xxx，最后提醒我换成自己的密钥
```

## 手动安装

### 1. 下载并解压技能包

从以下地址下载技能压缩包：

- **下载地址**：[https://tokenflows.org/skills/tokenflows-image-gen.zip](https://tokenflows.org/skills/tokenflows-image-gen.zip)

下载后将其解压到 `~/.codex/skills/` 目录。完成后目录结构如下：

```
~/.codex/skills/tokenflows-image-gen/
├── SKILL.md                        # 技能说明
└── scripts/
    ├── tokenflows-image-gen.sh     # macOS / Linux 脚本
    └── tokenflows-image-gen.ps1    # Windows 脚本
```

> `~` 代表你的用户主目录，`.codex` 是隐藏文件夹。Mac 可在访达按 `Command + Shift + G` 输入 `~/.codex` 进入；Windows 在资源管理器地址栏输入 `%USERPROFILE%\.codex` 进入。

### 2. 配置接口地址和密钥

在 `~/.codex/.env` 中写入：

```
base_url=https://api-us.tokenflows.org/v1
api_key=sk-你的密钥
```

将 `sk-你的密钥` 替换为你在 [TokenFlows 控制台](https://dash.tokenflows.org/) 创建的 API Key。如果文件里已有 `http_proxy` 等代理设置，保留即可。

## 使用

在 Codex 中输入 `/tokenflows-image-gen`（或输入 `/` 后选择 **tokenflows-image-gen** 技能），然后描述你想要的图片，例如：

> 画一只戴贝雷帽、坐在木桌上的小水獭，柔和光线

### 调用方式

技能内置的脚本支持四种模式（`check` / `api` / `generate` / `edit`），生图常用的是后两种：

**文生图（generate）：** 根据文字描述直接生成图片。

```bash
bash ~/.codex/skills/tokenflows-image-gen/scripts/tokenflows-image-gen.sh generate \
  --prompt "一只戴贝雷帽、坐在木桌上的小水獭，柔和光线" \
  --size 1024x1024 --out ./otter.png
```

**图生图 / 编辑（edit）：** 传入已有图片进行修改。

```bash
bash ~/.codex/skills/tokenflows-image-gen/scripts/tokenflows-image-gen.sh edit \
  --prompt "把背景换成下雪的雪山" \
  --image ./otter.png --out ./otter-snow.png
```

**配置自检（check）与接口透传（api）：**

```bash
# 检查密钥是否配置、来自哪个文件（不输出密钥值）
bash ~/.codex/skills/tokenflows-image-gen/scripts/tokenflows-image-gen.sh check

# GET 透传其它 OpenAI 兼容接口（自动附加密钥）
bash ~/.codex/skills/tokenflows-image-gen/scripts/tokenflows-image-gen.sh api /models
```

常用参数：

| 参数 | 说明 |
| --- | --- |
| `--prompt` | 图像描述（必填） |
| `--model` | 默认 `gpt-image-2.5-flare`，可选 `gpt-image-2.5-sunburst` |
| `--size` | 分辨率：`1024x1024`、`1536x1024`（横）、`1024x1536`（竖）、`auto` |
| `--n` | 生成数量，默认 1 |
| `--out` | 保存路径，默认 `image-时间戳.png` |

## 接口参考

| 接口 | 方法 | 用途 | 关键参数 |
| --- | --- | --- | --- |
| `/images/generations` | POST (JSON) | 文生图 | `model` `prompt` `n` `size` `quality` |
| `/images/edits` | POST (multipart) | 图生图 / 编辑 | `image[]`（必填，可多张）`prompt` `mask` `n` `size` |

要点：

- `gpt-image-2.5-flare` 返回 Base64 格式，脚本自动解码为图片文件。
- `mask` 是可选掩码 PNG（透明区域表示重绘位置），仅用于局部修改。

## 常见问题

- **报错"未找到 api_key"** → 运行脚本的 `check` 模式查看配置来源；确认 `~/.codex/.env`（或 `~/.tokenflows.env`、环境变量 `TOKENFLOWS_API_KEY`）里有有效密钥。`base_url` 不配置时默认走 `https://api-us.tokenflows.org/v1`。
- **接口报错（余额不足 / 鉴权失败）** → 检查 API Key 是否有效、账户余额是否充足。
- **保存出 0B 文件** → 确认接口地址正确，网络连接正常。
- **换模型** → 加 `--model 模型名`。