366 lines
10 KiB
Markdown
366 lines
10 KiB
Markdown
# GPT Image 2 API 调用文档
|
||
|
||
本文档面向 sub2api/OpenAI-compatible 网关调用 `gpt-image-2`。示例默认使用：
|
||
|
||
```text
|
||
BASE_URL=https://claude.omniclaw.store/v1
|
||
API_KEY=<从 /keys 页面生成的 sub2api key>
|
||
```
|
||
|
||
不要把 `.codex/auth.json` 里的 ChatGPT OAuth token 当 API key 使用。
|
||
|
||
## 快速结论
|
||
|
||
- 直接生成图片：使用 `POST /v1/images/generations`，`model` 传 `gpt-image-2`。
|
||
- 编辑图片：使用 `POST /v1/images/edits`，multipart 上传 `image[]`、可选 `mask`。
|
||
- Agent/Codex 场景：主模型仍用 `gpt-5.5`，通过 Responses API 的 `image_generation` tool 调图像能力；不要把 Codex 主模型设成 `gpt-image-2`。
|
||
- `gpt-image-2` 返回 base64 图片数据，通常是 `data[0].b64_json`。
|
||
- `3840x2160` 4K 可用，但属于高像素、长耗时场景；生产调用应设置 180-300 秒超时。
|
||
|
||
## 官方能力摘要
|
||
|
||
`gpt-image-2` 是图片生成和编辑模型，支持文本输入、图片输入、图片输出。模型别名和快照：
|
||
|
||
```text
|
||
gpt-image-2
|
||
gpt-image-2-2026-04-21
|
||
```
|
||
|
||
支持端点：
|
||
|
||
```text
|
||
/v1/images/generations
|
||
/v1/images/edits
|
||
/v1/responses # 通过 image_generation tool
|
||
```
|
||
|
||
官方参考：
|
||
|
||
- https://developers.openai.com/api/docs/models/gpt-image-2
|
||
- https://developers.openai.com/api/docs/guides/image-generation
|
||
- https://developers.openai.com/api/reference/resources/images
|
||
|
||
## 认证
|
||
|
||
```bash
|
||
export BASE_URL="https://claude.omniclaw.store/v1"
|
||
export API_KEY="sk-..."
|
||
```
|
||
|
||
所有 JSON 请求带：
|
||
|
||
```http
|
||
Authorization: Bearer $API_KEY
|
||
Content-Type: application/json
|
||
```
|
||
|
||
multipart 编辑接口由 `curl -F` 或 SDK 自动设置 `Content-Type`。
|
||
|
||
## 生成图片
|
||
|
||
### 最小请求
|
||
|
||
```bash
|
||
curl -sS "$BASE_URL/images/generations" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "gpt-image-2",
|
||
"prompt": "A compact Apple-style dashboard UI, clean white background",
|
||
"size": "1024x1024",
|
||
"quality": "medium",
|
||
"output_format": "png",
|
||
"n": 1
|
||
}' > image.json
|
||
```
|
||
|
||
解码：
|
||
|
||
```bash
|
||
jq -r '.data[0].b64_json' image.json | base64 --decode > image.png
|
||
```
|
||
|
||
### 4K 请求
|
||
|
||
```bash
|
||
curl -sS "$BASE_URL/images/generations" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
--max-time 300 \
|
||
-d '{
|
||
"model": "gpt-image-2",
|
||
"prompt": "A modern product poster, cinematic lighting, premium realistic photography",
|
||
"size": "3840x2160",
|
||
"quality": "medium",
|
||
"output_format": "png",
|
||
"n": 1
|
||
}' > image-4k.json
|
||
```
|
||
|
||
生产建议：4K + `high` 很慢且成本高。先用 `1024x1024` 或 `1536x1024` 验证提示词，再升到 `3840x2160`。
|
||
|
||
## 生成参数
|
||
|
||
| 参数 | 类型 | 建议值 | 说明 |
|
||
|---|---|---|---|
|
||
| `model` | string | `gpt-image-2` | 必填。也可用快照 `gpt-image-2-2026-04-21`。 |
|
||
| `prompt` | string | 详细自然语言 | 必填。写清主体、环境、镜头、风格、限制。 |
|
||
| `n` | number | `1` | 生成数量。生产建议单张并发调度，便于重试和计费。 |
|
||
| `size` | string | `1024x1024`、`1536x1024`、`3840x2160` | `gpt-image-2` 支持灵活尺寸，见下方尺寸约束。 |
|
||
| `quality` | string | `low`、`medium`、`high`、`auto` | 草稿用 `low`，常规用 `medium`，最终图用 `high`。 |
|
||
| `output_format` | string | `png`、`jpeg`、`webp` | 默认 `png`。延迟敏感优先 `jpeg`。 |
|
||
| `output_compression` | number | `0-100` | 仅 `jpeg`/`webp` 有意义。 |
|
||
| `background` | string | `auto`、`opaque` | `gpt-image-2` 当前不支持 `transparent`。 |
|
||
| `moderation` | string | `auto`、`low` | 控制图像生成过滤强度；仍需遵守内容政策。 |
|
||
| `stream` | boolean | `false` | 开启 SSE 流式图片事件。 |
|
||
| `partial_images` | number | `0-3` | 流式时返回部分图片；会增加输出 token 成本。 |
|
||
| `user` | string | 用户 ID | 终端用户标识，便于审计和滥用监控。 |
|
||
|
||
## 尺寸约束
|
||
|
||
`gpt-image-2` 的 `size` 可以是 `auto`，也可以是满足约束的 `宽x高`：
|
||
|
||
- 最大边不超过 `3840px`
|
||
- 宽和高都必须是 `16px` 的倍数
|
||
- 长边/短边比例不超过 `3:1`
|
||
- 总像素在 `655,360` 到 `8,294,400` 之间
|
||
|
||
常用尺寸：
|
||
|
||
```text
|
||
1024x1024 # 方图，通常最快
|
||
1536x1024 # 横图
|
||
1024x1536 # 竖图
|
||
2048x2048 # 2K 方图
|
||
2048x1152 # 2K 横图
|
||
3840x2160 # 4K 横图
|
||
2160x3840 # 4K 竖图
|
||
auto
|
||
```
|
||
|
||
超过 `2560x1440` 的输出通常应按实验性高像素场景处理：高延迟、高成本、失败概率更高。
|
||
|
||
## 返回结构
|
||
|
||
典型响应：
|
||
|
||
```json
|
||
{
|
||
"created": 1770000000,
|
||
"background": "opaque",
|
||
"data": [
|
||
{
|
||
"b64_json": "...",
|
||
"revised_prompt": "..."
|
||
}
|
||
],
|
||
"model": "gpt-image-2",
|
||
"output_format": "png",
|
||
"quality": "medium",
|
||
"size": "1024x1024",
|
||
"usage": {
|
||
"input_tokens": 43,
|
||
"input_tokens_details": {
|
||
"image_tokens": 0,
|
||
"text_tokens": 43
|
||
},
|
||
"output_tokens": 196,
|
||
"output_tokens_details": {
|
||
"image_tokens": 196,
|
||
"text_tokens": 0
|
||
},
|
||
"total_tokens": 239
|
||
}
|
||
}
|
||
```
|
||
|
||
业务侧应持久化：
|
||
|
||
- `model`
|
||
- `size`
|
||
- `quality`
|
||
- `output_format`
|
||
- `usage.total_tokens`
|
||
- `usage.input_tokens`
|
||
- `usage.output_tokens`
|
||
- 请求耗时
|
||
- 上游账号/分组/用户/key
|
||
|
||
## 编辑图片
|
||
|
||
### 单图编辑
|
||
|
||
```bash
|
||
curl -sS "$BASE_URL/images/edits" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-F "model=gpt-image-2" \
|
||
-F "image[]=@input.png" \
|
||
-F "prompt=Replace the sofa with a minimalist white lounge chair" \
|
||
-F "size=1024x1024" \
|
||
-F "quality=medium" \
|
||
-F "output_format=png" \
|
||
> edit.json
|
||
```
|
||
|
||
### 局部遮罩编辑
|
||
|
||
```bash
|
||
curl -sS "$BASE_URL/images/edits" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-F "model=gpt-image-2" \
|
||
-F "image[]=@input.png" \
|
||
-F "mask=@mask.png" \
|
||
-F "prompt=Change only the transparent masked region into a glass button" \
|
||
-F "size=1024x1024" \
|
||
-F "quality=medium" \
|
||
> edit-mask.json
|
||
```
|
||
|
||
遮罩要求：
|
||
|
||
- `image` 和 `mask` 必须同格式、同尺寸
|
||
- 文件小于 50MB
|
||
- `mask` 必须包含 alpha 通道
|
||
- `gpt-image-2` 不要传 `input_fidelity`；它自动按高保真处理输入图
|
||
|
||
## Responses API 调用 image_generation tool
|
||
|
||
用于多轮 Agent、让模型先理解需求再调用图片工具。主模型使用文本/Agent 模型，例如 `gpt-5.5`。
|
||
|
||
```bash
|
||
curl -sS "$BASE_URL/responses" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "gpt-5.5",
|
||
"input": "Generate a clean product poster for an AI proxy service.",
|
||
"tools": [
|
||
{
|
||
"type": "image_generation",
|
||
"quality": "medium",
|
||
"size": "1536x1024",
|
||
"output_format": "png"
|
||
}
|
||
]
|
||
}' > response-image.json
|
||
```
|
||
|
||
注意：
|
||
|
||
- `model` 是主推理模型，不是 `gpt-image-2`
|
||
- `image_generation` 工具负责图片生成
|
||
- sub2api 对 Codex 官方客户端请求会注入 `image_generation` 工具提示，但业务调用仍建议显式传 tool
|
||
|
||
## 流式图片
|
||
|
||
Image API 支持流式生成：
|
||
|
||
```bash
|
||
curl -N "$BASE_URL/images/generations" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "gpt-image-2",
|
||
"prompt": "A futuristic city skyline at sunrise",
|
||
"stream": true,
|
||
"partial_images": 2,
|
||
"size": "1536x1024",
|
||
"quality": "medium"
|
||
}'
|
||
```
|
||
|
||
事件类型：
|
||
|
||
```text
|
||
image_generation.partial_image
|
||
image_generation.completed
|
||
```
|
||
|
||
`partial_images` 可设 `0-3`。每张 partial image 会额外产生输出 token 成本。
|
||
|
||
## SDK 示例
|
||
|
||
### Node.js
|
||
|
||
```ts
|
||
import fs from "node:fs";
|
||
import OpenAI from "openai";
|
||
|
||
const client = new OpenAI({
|
||
apiKey: process.env.API_KEY,
|
||
baseURL: process.env.BASE_URL ?? "https://claude.omniclaw.store/v1",
|
||
});
|
||
|
||
const result = await client.images.generate({
|
||
model: "gpt-image-2",
|
||
prompt: "A premium product poster for an AI service",
|
||
size: "1536x1024",
|
||
quality: "medium",
|
||
output_format: "png",
|
||
n: 1,
|
||
});
|
||
|
||
const b64 = result.data?.[0]?.b64_json;
|
||
if (!b64) throw new Error("No image returned");
|
||
fs.writeFileSync("image.png", Buffer.from(b64, "base64"));
|
||
```
|
||
|
||
### Python
|
||
|
||
```py
|
||
import base64
|
||
import os
|
||
from openai import OpenAI
|
||
|
||
client = OpenAI(
|
||
api_key=os.environ["API_KEY"],
|
||
base_url=os.environ.get("BASE_URL", "https://claude.omniclaw.store/v1"),
|
||
)
|
||
|
||
result = client.images.generate(
|
||
model="gpt-image-2",
|
||
prompt="A premium product poster for an AI service",
|
||
size="1536x1024",
|
||
quality="medium",
|
||
output_format="png",
|
||
n=1,
|
||
)
|
||
|
||
b64 = result.data[0].b64_json
|
||
with open("image.png", "wb") as f:
|
||
f.write(base64.b64decode(b64))
|
||
```
|
||
|
||
## 生产调度建议
|
||
|
||
- 路由：图片生成优先使用 plus/team/pro OpenAI OAuth 账号，避免 free 账号能力不足或限流。
|
||
- 超时：普通图设置 120 秒，4K 设置 300 秒。
|
||
- 重试：只对网络错误、502/503/504 做有限重试；不要对内容政策拒绝无限重试。
|
||
- 并发：4K 请求输出 token 高，建议单账号小并发；普通 1024 图可更高并发。
|
||
- 成本：记录 `usage` 并按 `input_tokens + output_tokens` 计费；4K 输出 token 可能远高于 1024。
|
||
- 延迟：延迟敏感优先 `jpeg`，草稿用 `quality: low`。
|
||
- 失败降级：4K/high 失败时降为 4K/medium；仍失败则 1536x1024/medium 先出图，再走放大流程。
|
||
|
||
## 常见错误
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|---|---|---|
|
||
| `401 INVALID_API_KEY` | key 不是 sub2api key，或已删除/停用 | 从 `/keys` 重新生成 key |
|
||
| `400 invalid_request_error` | 参数不兼容，例如透明背景、尺寸不合法 | 检查 `size`、`background`、`quality` |
|
||
| `429 usage_limit_reached` | 命中 OpenAI 账号用量窗口 | 切换 plus/team/pro 账号或等待恢复 |
|
||
| `502 Upstream request failed` | 上游没返回图片、网络断开、内容被拒绝文本化 | 看服务端日志；必要时改提示词/降质量/改尺寸 |
|
||
| 超过 2 分钟 | 高像素或复杂提示词 | 设置更长超时，使用流式或先低分辨率验证 |
|
||
| `/v1/models` 不显示 `gpt-image-2` | Codex 主模型列表不等于图片接口能力列表 | 直接调用 `/v1/images/generations` |
|
||
|
||
## 安全边界
|
||
|
||
业务侧应在请求前过滤明显违规内容，尤其是：
|
||
|
||
- 未成年人或年轻化人物的性化内容
|
||
- 非自愿、胁迫、性暴力场景
|
||
- 明确裸露或露骨性行为
|
||
- 违法、仇恨、极端暴力内容
|
||
|
||
建议提示词显式写清“成年人、非露骨、无裸露、完全穿着”等约束，降低被上游拒绝或返回非图片文本的概率。
|
||
|