# Images API — 生成与编辑图像

Source: https://ofox.io/zh/docs/api/openai/images

两个端点：**生成**（文字 → 图）、**编辑**（图 + 文字 → 图）。响应都是 OpenAI 标准结构 `data[0].b64_json`。

| 我要做什么 | 端点 | 支持的模型 |
|------|------|------|
| 文字生成图片 | `POST /v1/images/generations` | GPT Image、Nano Banana（Gemini）、Seedream、Qwen-Image、MAI Image 各系列 |
| 上传图片 + 指令改图 | `POST /v1/images/edits` | GPT Image、Nano Banana（Gemini）、MAI Image |

Seedream 和 Qwen-Image 不支持 `/v1/images/edits`，图生图走 `generations` 端点，但参考图字段不同：**Seedream** 用 `image`，**Qwen** 用 `input_images`，注意不要写反。Gemini 需要控制分辨率（512 至 4K）时走 [Gemini 原生协议](https://ofox.io/zh/docs/api/gemini/generate-content#生成与编辑图像)。各系列的参数差异见对应系列页。

## 快速开始
一个最小可运行的请求：生成一张 1024×1024 的图，解码后存成 `output.png`。

- base_url: `https://api.ofox.io/v1`
- 文生图接口: `https://api.ofox.io/v1/images/generations`
- 改图接口: `https://api.ofox.io/v1/images/edits`
- 模型 ID: `openai/gpt-image-2.5-flare`

**Python**

```python filename="gen.py"
import base64
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",
    base_url="https://api.ofox.io/v1",
    timeout=600,  # 图像接口同步返回，耗时较长
)

resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="白色桌面上的一个红苹果",
    size="1024x1024",
    quality="low",
)

with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "prompt": "白色桌面上的一个红苹果",
    "size": "1024x1024",
    "quality": "low"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png
```

**接口同步返回，客户端超时请设为 600 秒。** 高画质、大尺寸及改图请求可能需要数分钟，见[实测耗时](https://ofox.io/zh/docs/develop/models/gpt-image#timeouts)。

各系列调用方式一致，换模型只改 `model`。取值范围与独有参数不同，见下方各参数说明。

## 生成图像

```http
POST https://api.ofox.io/v1/images/generations
```

### 请求参数
下面的可选值与默认值**适用于 GPT Image 系列**（`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2`）。其他系列有差异的地方单独注明。实测细节见 [GPT Image 系列](https://ofox.io/zh/docs/develop/models/gpt-image)。

**必填**

**model** `string` · required

模型 ID，**区分大小写**，写错返回 `404 model_not_found`。

支持的模型见本页开头的表格。建议写带厂商前缀的完整 ID，如 `openai/gpt-image-2.5-flare`。

**prompt** `string` · required

描述要生成的画面。

**常用**

**size** `string` · default `auto` · values `宽x高` / `auto`

输出尺寸。可自定义宽高，但要满足四条约束，否则返回 `400 Invalid size`。

四条约束：

- 宽、高都能被 16 整除
- 最长边 ≤ 3840
- 宽高比在 1:3 到 3:1 之间
- 总像素 ≥ 655,360（`768x768` 不合法，`1024x768` 合法）

不传或传 `auto` 时由模型决定，实测返回 1254×1254。需要固定尺寸请显式传入。其他系列的尺寸规则不同，见对应系列页。详见 [GPT Image · 尺寸](https://ofox.io/zh/docs/develop/models/gpt-image#size)。

**quality** `string` · values `low` / `medium` / `high` / `xhigh` / `max` / `auto`

画质档位，**直接影响价格**。`gpt-image-2` 没有 `xhigh` / `max`。

- `gpt-image-2` 没有 `xhigh` / `max`，传了返回 400。
- 不接受 DALL·E 时代的 `standard` / `hd`，传了返回 400。
- 不传不等于 `medium`：由模型自己选档（实测选了 `low`）。想要画质和成本稳定，请显式指定。

其他系列大多没有档位，见对应系列页。详见 [GPT Image · 画质](https://ofox.io/zh/docs/develop/models/gpt-image#quality)。

**n** `integer` · default `1` · values `1–10`

生成张数，每张单独计费。Gemini 模型不支持，不要传。

**output_format** `string` · default `png` · values `png` / `jpeg` / `webp`

输出文件格式。

**高级**

**output_compression** `integer` · values `0–100`

压缩率，仅对 `jpeg` / `webp` 生效。

**background** `string` · default `opaque` · values `opaque` / `transparent` / `auto`

背景。`transparent` 需要支持 alpha 通道的格式（`png` / `webp`）。

**moderation** `string` · values `auto` / `low`

内容审核强度。

**stream** `boolean` · values `true` / `false`

是否流式返回。配合 `partial_images` 可在生成过程中收到中间图。

**partial_images** `integer` · values `0–3`

流式返回的中间图张数，需同时传 `stream: true`。按 OpenAI 官方说明，每张中间图额外计 100 个输出 token。

**input_images** `string[]` · values `1–3 张`

参考图数组（URL 或 base64），**仅 Qwen 系列**支持，1–3 张。

其他系列传了不报错也不生效；Seedream 的参考图字段是 `image`。

**extra_body.provider.type** `string` · values `azure_foundry` / `openai`

指定供应商。**可选，通常不需要**，网关会自动路由。有内容审核方面的需求时可考虑指定；指定后若该供应商不可用，不会自动切换到其他供应商。

等价写法是请求头 `X-OfoxAI-Provider-Type`。见[进阶：指定供应商](#provider)。

### 响应

```json filename="200 OK（b64_json 已截断）"
{
  "created": 1777385517,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2.5-flare",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196 },
    "total_tokens": 209
  }
}
```

**data[].b64_json** `string`

图片的 base64 编码，**不带** `data:image/png;base64,` 前缀。

解码后写文件；在浏览器里显示需要自己拼前缀。响应里没有 `url` 字段。

**data[].index** `integer`

图片序号，`n > 1` 时区分多张图。

**size** `string`

实际输出尺寸。没传 `size` 或传了 `auto` 时，从这里读出实际尺寸。

**quality** `string`

实际使用的画质档位。没传 `quality` 时，从这里确认实际用了哪一档。

**background · output_format** `string`

实际使用的背景与格式。**不一定返回**，不要依赖这两个字段。

**usage** `object`

计费用量。`output_tokens` 为输出的图片 token，`input_tokens_details.text_tokens` 为提示词 token。

按这里的数字核算单次成本。

## 编辑图像

```http
POST https://api.ofox.io/v1/images/edits
```

此端点支持 GPT Image、Nano Banana（Gemini）、MAI Image。Seedream 和 Qwen-Image 调用会返回 `400 endpoint_not_supported`，请改用生成接口的参考图字段，见 [Seedream](https://ofox.io/zh/docs/develop/models/seedream#edit)、[Qwen-Image](https://ofox.io/zh/docs/develop/models/qwen-image#edit)。

### 请求参数
`multipart/form-data`，以表单字段提交，需上传图片文件。可选值与默认值同样适用于 GPT Image 系列。

**必填**

**model** `string` · form · required

模型 ID，规则同[生成接口](#generations-model)。支持的模型见本页开头的表格。

**image** `file` · form · required · values `PNG` / `JPEG`

参考图，传**本地文件**（cURL 用 `@` 前缀），不是 URL。

多张时字段名写 `image[]` 重复传入。单张 ≤ 15 MB，请求体 ≤ 50 MB；张数网关不额外限制，建议不超过 16 张。

**prompt** `string` · form · required

编辑指令。

**常用**

**mask** `file` · form · values `PNG（带 alpha）`

局部重绘遮罩：带 alpha 通道的 PNG，尺寸与 `image` 一致，透明区域 = 要重画的部分。

**只在本端点生效**，传到生成接口会被静默忽略。制作方法与实测效果见 [GPT Image · mask 局部重绘](https://ofox.io/zh/docs/develop/models/gpt-image/inpainting#mask)。

**size** `string` · form · default `auto` · values `宽x高` / `auto`

输出尺寸，约束同[生成接口](#generations-size)。

不传或传 `auto` 时由模型决定，**不保证与原图一致**。要保持原尺寸请显式传入。

**quality** `string` · form · values `low` / `medium` / `high` / `xhigh` / `max` / `auto`

画质档位，规则同[生成接口](#generations-quality)：`gpt-image-2` 没有 `xhigh` / `max`。

**n** `integer` · form · default `1` · values `1–10`

生成张数，每张单独计费。

**高级**

**X-OfoxAI-Provider-Type** `string` · header · values `azure_foundry` / `openai`

指定供应商。**可选，通常不需要**，网关会自动路由。有内容审核方面的需求时可考虑指定；指定后若该供应商不可用，不会自动切换到其他供应商。

本端点是 multipart 上传，想固定供应商时**只能用请求头**，表单字段 `extra_body` 会被静默忽略。见[进阶：指定供应商](#provider)。

### 响应
结构与生成接口相同，`usage` 里多出参考图的输入 token：

```json filename="200 OK（b64_json 已截断）"
{
  "created": 1777385669,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "auto",
  "quality": "low",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 17 },
    "num_input_images": 1,
    "output_tokens": 358,
    "total_tokens": 1399
  }
}
```

**usage.input_tokens_details.image_tokens** `integer`

参考图折算成的输入 token。实测一张 1024×1024 的参考图计 1,024 个。改图比同尺寸的文生图贵，主要贵在这一项。

**usage.num_input_images** `integer`

参考图张数。可以用它确认参考图确实被模型读取了。

其余字段同[生成接口的响应](#generations-response)。

支持的模型与价格见 [模型目录](https://ofox.io/zh/models)。

### 调用

**Python**

```python filename="edit.py"
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1", timeout=600)

with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="把苹果改成绿色，其他保持不变",
        size="auto",
        quality="low",
    )

with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))
```

**TypeScript**

```typescript filename="edit.ts"
import OpenAI, { toFile } from 'openai'
import fs from 'node:fs'

const client = new OpenAI({
  apiKey: 'YOUR_OFOX_API_KEY',
  baseURL: 'https://api.ofox.io/v1',
  timeout: 600_000, // 毫秒
})

const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: '把苹果改成绿色，其他保持不变',
  size: 'auto',
  quality: 'low',
})

fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))
```

**cURL**

```bash filename="Terminal"
curl -X POST 'https://api.ofox.io/v1/images/edits' \
  --max-time 600 \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="把苹果改成绿色，其他保持不变"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'
```

`image` 字段传**本地文件路径**（cURL 用 `@` 前缀），不是 URL。

实测对比：

| 原图 | 编辑后 |
|------|--------|
| ![原始红苹果](https://ofox.io/screenshots/images-api/example-gpt-image-2-generated.webp) | ![编辑后的绿苹果](https://ofox.io/screenshots/images-api/example-gpt-image-2-edited.webp) |

## 错误
出错时返回 HTTP 错误码和下面的结构（实测）：

```json filename="400 Bad Request"
{
  "error": {
    "code": null,
    "message": "The model 'gpt-image-2' does not support quality 'xhigh'.",
    "param": null,
    "request_id": "fbe4f24c-779d-41a0-8b3a-c62886cdd1ae",
    "type": "image_generation_user_error"
  }
}
```

`code` 可能为 `null`。请按 HTTP 状态码和 `message` 判断。

| 状态码 | 报错 | 原因 | 怎么改 |
|------|------|------|------|
| 400 | `Invalid size '…'` | 尺寸不满足四条约束 | 按 [size](#generations-size) 的规则调整 |
| 400 | `does not support quality '…'` 或取值无效 | `gpt-image-2` 传了 `xhigh` / `max`；或传了 `standard` / `hd` | 改用 [quality](#generations-quality) 列出的值 |
| 400 | `Unknown parameter: '…'` | 传了不支持的字段，如 DALL·E 的 `style` | 去掉该字段 |
| 400 | `Invalid image file or mode for image 1` | 参考图不是 PNG / JPEG；或 mask 不是带 alpha 的 PNG、尺寸与原图不一致 | 检查 [image](#edits-image) 与 [mask](#edits-mask) |
| 400 | `provider_type_unavailable` | 指定的供应商不提供该模型 | 去掉供应商参数，让网关自动路由 |
| 404 | `model_not_found` | 模型 ID 拼错或大小写不对 | 从本页表格复制完整 ID |
| 429 | `rate_limit_exceeded` | 超过每个团队 100 RPM；多建 Key 不会提高上限 | 降低并发，退避后重试 |

联系支持时，请附上响应里的 `request_id` 和报错信息（HTTP 状态码与 `error.message`）。建议在日志里记录它们。

## 进阶：指定供应商
**可选，通常不需要。** GPT Image 三个模型（`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2`）都由 `azure_foundry` 和 `openai` 两家承载，生成和编辑都支持。不指定时网关自动路由。

有内容审核方面的需求时可以指定供应商。指定后请求只会发往该供应商；该供应商不可用时，**不会自动切换**到其他供应商。

指定未承载该模型的供应商会返回 `400 provider_type_unavailable`。

| 供应商 | 说明 | 内容审核（`gpt-image-2`） |
|------|------|------|
| `azure_foundry` | 微软云托管 | 较严格 |
| `openai` | OpenAI 官方 API | 相对宽松 |

`openai/gpt-image-2` 的两个供应商审核尺度不同。**提示词反复被拒时，可以显式指定 `openai`**。未指定时请求会被加权分流，可能落到 `azure_foundry`。

### 文生图 `/v1/images/generations`

JSON 请求体，请求体字段 `extra_body.provider.type` 与请求头 `X-OfoxAI-Provider-Type` 两种写法均可。

**Python**

```python filename="gen_pinned.py"
resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    extra_body={"extra_body": {"provider": {"type": "openai"}}},
)
```

**TypeScript**

```typescript filename="gen_pinned.ts"
const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  extra_body: { provider: { type: 'openai' } },
})
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/v1/images/generations \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "...",
    "n": 1,
    "size": "1024x1024",
    "extra_body": { "provider": { "type": "openai" } }
  }'
```

使用官方 OpenAI SDK 时，`extra_body` 需作为请求体中的字面量键存在。TypeScript SDK 在参数对象中直接书写 `extra_body` 即可。Python SDK 的 `extra_body=` 参数会把内容合并到请求体顶层，因此需额外嵌套一层，或改用请求头。

### 图生图 `/v1/images/edits`

multipart 上传，没有 JSON 请求体可供嵌套 `extra_body`，因此**只能使用请求头**。

```bash filename="Terminal"
curl https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "X-OfoxAI-Provider-Type: openai" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=..." \
  -F "image=@input.png"
```

SDK 写法：Python 传 `extra_headers={"X-OfoxAI-Provider-Type": "openai"}`；TypeScript 在第二个参数传 `{ headers: { 'X-OfoxAI-Provider-Type': 'openai' } }`。

在 `/v1/images/edits` 上，作为表单字段传递的 `extra_body` 会被**静默忽略**：图片照常生成，但约束不生效。请改用 `X-OfoxAI-Provider-Type`。

完整参考见 [API · 供应商路由](https://ofox.io/zh/docs/api/provider-routing)。

## 官方文档与更多
官方文档描述的是直连 OpenAI 的行为。与 OfoxAI 实测不一致时，以本站实测为准。

**OpenAI 官方**

- [图像生成指南 · 生成图像](https://developers.openai.com/api/docs/guides/image-generation#generate-images)
- [图像生成指南 · 编辑图像](https://developers.openai.com/api/docs/guides/image-generation#edit-images)
- [图像生成指南 · 用 mask 局部编辑](https://developers.openai.com/api/docs/guides/image-generation#edit-an-image-using-a-mask)
- [图像生成指南 · 尺寸与画质](https://developers.openai.com/api/docs/guides/image-generation#size-and-quality-options)
- [图像生成指南 · 成本计算](https://developers.openai.com/api/docs/guides/image-generation#calculating-costs)
- [Images API 参考](https://developers.openai.com/api/reference/resources/images)

**OfoxAI 系列页**

- [GPT Image 系列概览](https://ofox.io/zh/docs/develop/models/gpt-image)：选型、尺寸、画质、耗时、报错
- [文生图](https://ofox.io/zh/docs/develop/models/gpt-image/text-to-image)
- [改图与多图](https://ofox.io/zh/docs/develop/models/gpt-image/image-edit)
- [局部重绘](https://ofox.io/zh/docs/develop/models/gpt-image/inpainting)
- [Nano Banana 系列](https://ofox.io/zh/docs/develop/models/nano-banana)（Gemini Image）与[报错排查](https://ofox.io/zh/docs/develop/models/nano-banana/errors)
- [Seedream 系列](https://ofox.io/zh/docs/develop/models/seedream)
- [Qwen-Image 系列](https://ofox.io/zh/docs/develop/models/qwen-image)
- [MAI Image 系列](https://ofox.io/zh/docs/develop/models/mai-image)