> ## Documentation Index
> Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片生成与编辑

> 使用兼容 OpenAI 的接口生成和编辑图片，按尺寸档位逐张计费。

`POST /v1/images/generations` 根据文字描述生成图片，`POST /v1/images/edits` 编辑你上传的一张或多张图片。两个接口都遵循 OpenAI Images API，因此官方 OpenAI SDK 只需把 base URL 设为 `https://api.omnirelay.ai/v1`、使用 OmniRelay API Key 即可调用。

Key 的规则与文本模型相同：有效期、[IP 白名单](https://omnirelay.ai/docs/cn/overview/rate-limits.md#key-的-ip-白名单)、[可调用模型限制](https://omnirelay.ai/docs/cn/overview/authentication.md#限定-key-可调用的模型)、预算以及[请求频率与并发](https://omnirelay.ai/docs/cn/overview/rate-limits.md)。写代码之前，也可以先在控制台的「模型体验」里试用这两个接口。

## 模型

| 模型 ID | 生成 | 编辑 | 每次张数 |
| - | - | - | - |
| `gpt-image-2` | 支持 | 支持 | 1–4 |
| `gpt-image-2.5` | 支持 | 支持 | 1–4 |

图片模型会出现在你自己的 [`GET /v1/models`](https://omnirelay.ai/docs/cn/llms/listing-models#图片模型) 列表中，带有 `capabilities.image_generation: true` 以及本工作区的每张单价。

## 价格

图片按**实际返回的张数**计费，不按 token 计费。请求的 `size` 决定本次调用中每张图片的档位：

| 档位 | 请求的 `size` | 每张标价 |
| - | - | - |
| 1K | 最长边不超过 1024 px，例如 `1024x1024`、`1024x768` | USD 0.134 |
| 2K | 最长边不超过 2048 px，例如 `1536x1024`、`2048x2048`；未传或为 `auto` 时也按 2K | USD 0.201 |
| 4K | 最长边不超过 4096 px，例如 `3840x2160` | USD 0.268 |

`quality` 不影响价格，折扣与文本模型相同。调用发出前按档位预留 `n` 张的费用，结算时只对实际返回的图片扣费，扣费金额见响应中的 `cost_microusd`。详见[用量与计费](https://omnirelay.ai/docs/cn/general/usage-billing.md#图片模型)。

## 生成图片

```bash cURL theme={null}
curl https://api.omnirelay.ai/v1/images/generations \
  -H "Authorization: Bearer $OMNIRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A red bicycle on a white background","size":"1024x1024","quality":"low"}' \
  | jq -r '.data[0].b64_json' | base64 --decode > bicycle.png
```

```python Python theme={null}
import base64, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OMNIRELAY_API_KEY"], base_url="https://api.omnirelay.ai/v1")

result = client.images.generate(
    model="gpt-image-2",
    prompt="A red bicycle on a white background",
    size="1024x1024",
    quality="low",
)
open("bicycle.png", "wb").write(base64.b64decode(result.data[0].b64_json))
```

```javascript JavaScript theme={null}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OMNIRELAY_API_KEY, baseURL: "https://api.omnirelay.ai/v1" });

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A red bicycle on a white background",
  size: "1024x1024",
  quality: "low",
});
fs.writeFileSync("bicycle.png", Buffer.from(result.data[0].b64_json, "base64"));
```

## 编辑图片

以 `multipart/form-data` 上传原图，字段名为 `image`（多张时用 `image[]`）；可选的 `mask` 中透明区域表示要修改的位置。整个请求最大 20 MiB。

```bash cURL theme={null}
curl https://api.omnirelay.ai/v1/images/edits \
  -H "Authorization: Bearer $OMNIRELAY_API_KEY" \
  -F model=gpt-image-2 \
  -F prompt="Make the bicycle blue" \
  -F size=1024x1024 \
  -F image=@bicycle.png \
  | jq -r '.data[0].b64_json' | base64 --decode > blue-bicycle.png
```

```python Python theme={null}
result = client.images.edit(
    model="gpt-image-2",
    image=open("bicycle.png", "rb"),
    prompt="Make the bicycle blue",
    size="1024x1024",
)
open("blue-bicycle.png", "wb").write(base64.b64decode(result.data[0].b64_json))
```

```javascript JavaScript theme={null}
const result = await client.images.edit({
  model: "gpt-image-2",
  image: fs.createReadStream("bicycle.png"),
  prompt: "Make the bicycle blue",
  size: "1024x1024",
});
fs.writeFileSync("blue-bicycle.png", Buffer.from(result.data[0].b64_json, "base64"));
```

## 参数

| 字段 | 规则 |
| - | - |
| `model` | `GET /v1/models` 中的图片模型 ID。 |
| `prompt` | 必填，最多 32,000 个字符。 |
| `size` | `宽x高` 或 `auto`（默认）。决定价格档位；最长边超过 4096 px 时返回 `400 invalid_parameter`。 |
| `quality` | 原样传给模型，例如 `low`、`medium`、`high`、`auto`。质量越高耗时越长，但价格不变。 |
| `n` | 图片张数，1–4，默认 1。 |
| `response_format` | 仅支持 `b64_json`；传 `url` 会在扣费前返回 `400 unsupported_parameter`。 |
| `stream` | 图片接口不支持流式。 |
| `image`、`image[]`、`mask` | 仅编辑接口：上传的文件，最多 17 个，合计不超过 20 MiB。 |
| 其他字段 | `background`、`output_format`、`output_compression`、`moderation`、`user` 原样传给模型，由模型决定是否接受；被拒绝时返回 `400` 并带 `error.param`，不扣费。 |

## 响应

```json theme={null}
{
  "created": 1791734841,
  "model": "gpt-image-2",
  "data": [{ "b64_json": "iVBORw0KGgo…", "revised_prompt": "…" }],
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": { "input_tokens": 18, "output_tokens": 196, "total_tokens": 214 },
  "cost_microusd": 134000
}
```

* `data[].b64_json` 是按 `output_format` 编码的 base64 图片；不会以链接形式返回。
* `usage` 是模型报告的 token 数，仅供参考；实际扣费以 `cost_microusd` 为准，按张计。
* 与文本模型一样，发送 `X-Gateway-Metadata: enabled` 可额外返回 `gateway_metadata`（同时以旧名 `omnirelay_metadata` 返回）。

## 长耗时调用

图片调用通常需要 15–90 秒，高质量或 4K 可能更久。若约 25 秒后仍未完成，OmniRelay 会先返回 `200`，并持续发送空格直到 JSON 正文就绪，避免代理断开空闲连接。JSON 解析器和 OpenAI SDK 都会忽略开头的空格。

由于状态码已经发出，**此后发生的失败会以 `200` 正文中的错误对象返回**。读取 `data` 之前，务必先检查解析后的正文里是否有 `error`：

```python theme={null}
import json, requests

response = requests.post(
    "https://api.omnirelay.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {key}"},
    json={"model": "gpt-image-2", "prompt": "A lighthouse at dusk", "quality": "high"},
    timeout=300,
)
body = json.loads(response.text)
if "error" in body:
    raise RuntimeError(body["error"]["code"], body.get("request_id"))
```

HTTP 客户端的超时请设为至少 3 分钟。

## 失败与扣费

| 情况 | 响应 | 是否扣费 |
| - | - | - |
| 请求不合法、参数被拒、预算或限额不足 | `400`、`402`、`403`、`413` 或 `429`，附错误码 | 否 |
| 模型服务方拒绝调用 | `502 upstream_rejected` | 否 |
| 超时、连接中断、服务方服务器错误，或返回无法核验 | `502` 或 `504 image_call_held` | 进入人工复核；仅当确实生成了图片时扣费 |

即使结果没有送达，服务方完成的图片仍会计费，因此 OmniRelay 不会自动释放 `image_call_held` 的调用，预留会保留到对账完成；若长时间未处理，请带上 `request_id` 联系支持。不要循环重发同一请求：每次调用都会单独计费。参见[错误](https://omnirelay.ai/docs/cn/general/errors.md)。

## 限制

* 每次最多 4 张；每个请求最大 20 MiB；提示词最多 32,000 个字符。
* 图片调用与文本调用一样计入工作区、成员和 Key 的每分钟请求数和并发数。
* OmniRelay 不保存图片，请自行保存 `b64_json`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.