# image-generate

这是一个基于 `gpt-image-2` 的图片生成小项目，支持 OpenAI-compatible / apicodex-compatible 接口。

## 安装

```bash
python3 -m pip install -r requirements.txt
```

## 入口

- `gpt_image2_generate.py`：单参考图 / 文生图 / 图生图入口
- `gpt_image2_generate_multi.py`：多参考图、多输出入口
- `scripts/*.sh`：常用启动脚本

## 快速开始

单参考图：

```bash
bash scripts/run_openai_gpt_image2_edit.sh
```

多参考图、多输出：

```bash
bash scripts/run_openai_gpt_image2_multi.sh
```

这两个 OpenAI 脚本会强制 `IMAGE_REQUEST_STYLE=openai`，不会沿用 `.env` 里的 `apicodex`。

## 配置

复制 `.env.example` 为 `.env`，按需填写：

- `OPENAI_API_KEY`
- `OPENAI_BASE_URL`
- `IMAGE_PROMPT`
- `IMAGE_SIZE`
- `REFERENCE_IMAGE` 或 `REFERENCE_IMAGES`
- `IMAGE_STREAM`
- `IMAGE_PARTIAL_IMAGES`
- `IMAGE_MODERATION`

`IMAGE_SIZE` 可选值：

- 比例值：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`5:4`、`4:5`、`2:1`、`1:2`、`21:9`、`9:21`
- 像素值：`宽x高` 格式，只要满足官方约束即可。OpenAI 官方 `gpt-image-2` 的常用尺寸示例是 `1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2048x1152`、`3840x2160`、`2160x3840`，以及 `auto`

官方约束：

- 最大边长 `<= 3840px`
- 宽高都必须是 `16px` 的倍数
- 长边 / 短边比值不能超过 `3:1`
- 总像素数必须在 `655,360` 到 `8,294,400` 之间

建议：

- `IMAGE_REQUEST_STYLE=openai` 时，比例值会自动映射成兼容像素尺寸。
- 需要更稳定的输出尺寸时，优先直接写像素值。
- `4096x2304`、`4096x4096` 这类超过 `3840px` 边长上限的尺寸，不属于 OpenAI 官方 `gpt-image-2` 的可选值。

## Stream 与 Moderation

- `IMAGE_STREAM=true` 时，请求里会发送 `stream=true`。
- `IMAGE_PARTIAL_IMAGES=1` 时，请求里会额外发送 `partial_images=1`，要求先返回 1 张中间图。
- `IMAGE_MODERATION` 目前只支持 `auto` 和 `low`，其他值会在本地校验阶段直接报错。
- 如果上游真的返回 `text/event-stream`，脚本会逐条处理 SSE 事件，并在运行目录里保存：
  - `post-response.json`
  - `stream-events.jsonl`
  - `partials/*.png`
- 如果上游没有返回 `EventStream`，脚本会自动回退到原来的 JSON / 轮询处理逻辑。

常用示例：

```bash
IMAGE_STREAM=true \
IMAGE_PARTIAL_IMAGES=1 \
IMAGE_MODERATION=low \
bash scripts/run_openai_gpt_image2_edit.sh
```

详细说明见 [docs/usage.md](docs/usage.md)。

## 仓库约定

- `outputs/` 是运行产物目录，默认不纳入版本控制。
- `references/` 是本地参考图目录，默认不纳入版本控制。