> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API 申请及使用 > OpenAI generation 集成指南 - XHuoAPI OpenAI 图片编辑服务，可以传入任意多张图片和指令，输出修改之后的图片。目前接口同时支持 `dall-e-2`、`gpt-image-1`、最新的 **`gpt-image-2`**，以及通过同一接口接入的 **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** 系列模型。 本文档主要介绍 OpenAI Images Edits API 操作的使用流程，利用它我们可以轻松使用官方 OpenAI 图像编辑功能。 ## 申请流程 要使用 OpenAI Images Edits API，首先可以到 [OpenAI Images Edits API](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) 页面点击「Acquire」按钮，获取请求所需要的凭证： ![](https://cdn.xhuoapi.ai/nyq0xz.png) 如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。 在首次申请时会有免费额度赠送，可以免费使用该 API。 ## GPT-Image-2 模型 `gpt-image-2` 在图像编辑场景下相比 `gpt-image-1` 有非常明显的提升： * **结构保持更稳定**：换皮肤、换配色、换背景时几乎不会破坏原图的版式与构图。 * **文字保留更准确**：信息图、海报、菜单等含文字的图片在编辑后文字仍然清晰可读。 * **支持 URL 直传**：除了传统的 `multipart/form-data` 文件上传，`gpt-image-2` 还**额外支持以 JSON 方式传入图片 URL**，无需先把图片下载到本地，非常适合服务端流水线接入。 * **支持高分辨率重绘**：可以传入一张 1K 原图，通过 `size` 参数请求 2K / 4K 输出，模型会在编辑过程中同时完成放大。 ### 支持的 `size` 取值与计费档位 编辑接口对 `size` 的约束与生成接口完全一致——`gpt-image-2` 只需要 `size` 为 `auto`、空，或者符合 `WIDTHxHEIGHT` 格式，任何其他形态会返回 400。计费只分两个档位，与原图分辨率无关，只看 `size` 请求值： * **1K 标准价**：下表中任一 1K 推荐尺寸，或上游 1K 常见输出别名（`1254x1254`、`1672x941`、`941x1672`）。 * **其他档位（1.5×）**：包括下表推荐的 2K / 4K 预设，以及你自定义传入的任意 `WIDTHxHEIGHT`。 上游对自定义尺寸的硬约束同样适用：宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400。 | 比例 | 1K（标准价） | 2K推荐（×1.5） | 4K推荐（×1.5） | | ---- | ----------- | ----------- | ----------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > 例如：原图是 `1024x1024`，`size` 传 `2048x2048` 时，模型会按编辑指令重绘并输出 2K 图，按“其他”档位计费；`size` 传 `3840x2160` 时输出 4K 横屏图，同样按“其他”计费；传 `auto` 或省略则按 1K 标准价计费。 > **关于 `n` 参数** > > `gpt-image-2` 编辑接口目前**不支持 `n > 1`**：该参数会被静默忽略，无论传 `n=1` 还是 `n=10`，单次请求都只会返回 1 张图，并且只按 1 张计费。如果你需要一次拿到多张候选编辑结果，请**自行并发发起多次请求**。该限制同样适用于 `gpt-image-1` / `gpt-image-1.5`，以及 `nano-banana` / `nano-banana-2` / `nano-banana-pro` 系列。`dall-e-2` 是目前唯一原生支持 `n > 1` 的编辑模型。 下面通过两个不同方位的真实示例感受 `gpt-image-2` 的编辑能力。 ### 调用方式一：JSON + 图片 URL（推荐） 直接以 `application/json` 方式发送请求，`image` 字段填入一张图片的 URL，模型会去抓取该图片并按 `prompt` 进行编辑。 例如，下面这张原图是用 `gpt-image-2` 生成的科普图鉴：

我们希望把它改成“夜间模式”配色。可以这样调用： ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` 或者用 Python： ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 返回结果如下： ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 编辑之后的图片如下：

可以看到模块结构、信息分区、字体排版都被严格保留，只有配色被反转为深色主题。 > **提示**：`image` 字段也支持传入一个数组，例如 `"image": ["url1", "url2", "url3"]`，最多可同时传入 16 张参考图，让模型综合参考多张图片进行编辑。 ### 调用方式二：JSON + 多张参考图 `gpt-image-2` 支持同时参考多张图片来生成最终结果，例如把多张产品照合成到一张礼物篮中： ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### 场景示例：换风格 + 保持结构 下面是另一个例子，把一张木质书架替换为现代浮架，但严格保留每层书本的数量和排列。 原图（用 `gpt-image-2` 生成的木质书架）：

调用： ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` 编辑结果（`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`）：

可以看到风格和环境都按提示词进行了完整替换，但每层书本的数量（1 / 3 / 7）依旧严格保留，并且按要求增加了一盆多肉植物。 ### 调用方式三：multipart/form-data（兼容 OpenAI SDK） 如果你已经在使用官方 OpenAI Python SDK，原有的 `multipart/form-data` 上传方式同样适用，只需把 `model` 改为 `gpt-image-2`： ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` 使用 SDK 时需要先导入两个环境变量，`OPENAI_BASE_URL` 设为 `https://api.xhuoapi.ai/v1/openai`，`OPENAI_API_KEY` 设为申请到的 token： ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## Nano Banana 系列模型 `nano-banana` 系列在编辑场景下同样接入了 `/openai/images/edits`，把 `model` 改为下表中的任意一个即可。 | 模型 | 计费（Credits / 次） | 适用场景 | | ----------------- | --------------- | ------------------- | | `nano-banana` | 0.14 | 普通图像编辑，速度最快、成本最低 | | `nano-banana-2` | 0.28 | 质量与细节明显提升 | | `nano-banana-pro` | 0.35 | 系列中的旗舰，结构、文字、风格保留最佳 | > **重要：参数支持范围** > > Nano Banana 通过适配层接入 OpenAI 协议，仅支持以下参数：`model`、`prompt`、`image`。 > > * `image` 既可以通过 `multipart/form-data` 上传文件（worker 内部会转成 `data:;base64,...` 传给上游），也可以通过表单字段直接传图片 URL 字符串。 > * 不支持 `mask`、`n`、`size`、`response_format` 等参数；填了也会被忽略。 > * 返回结构遵循 OpenAI 格式（`data[].url`），但 `created` 固定为 `0`，且不会返回 `b64_json`，`revised_prompt` 始终等于原始 `prompt`。 ### 通过表单 + 图片 URL 调用 ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=add a green leaf on top of the apple" \ -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` 返回结果如下： ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` 编辑后的图片：

### 通过表单 + 本地文件调用 ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "add a green leaf on top of the apple" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### 异步回调 `callback_url` 异步回调机制对 nano-banana 同样有效，调用流程与其它模型完全一致，详见下文 [异步回调](#异步回调) 一节。 ## 基本使用 接下来就可以使用代码进行调用，下方是通过CURL进行调用： ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` 在第一次使用该接口时，我们至少需要填写四个内容，一个是 `authorization`，直接在下拉列表里面选择即可。另一个参数是 `model`， `model` 就是我们选择使用 OpenAI 官网模型类别，这里我们主要有 1 种模型，详情可以看我们提供的模型。还有一个参数是`prompt`，`prompt` 是我们输入要生成图像的提示词。最后一个参数是`image`，这个参数需要编辑的图片路径，需要编辑的图片如下图所示：

相同调用效果的Python 样例调用代码： ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Save the image to a file with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` 使用Python调用全我们需要先导入俩个环境变量，一个`OPENAI_BASE_URL`，可以设置为`https://api.xhuoapi.ai/v1/openai`，还有一个使用凭证变量`OPENAI_API_KEY`，这个值是从`authorization`获取到的，在Mac OS可以通过以下命令设置环境变量： ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` 调用之后，我们发现会在当前目录下生成一张图片`gift-basket.png`，具体的结果如下：

这样我们就完成了对图片的编辑操作，目前 Edits 接口共支持三种模型：`dall-e-2`、`gpt-image-1` 和 `gpt-image-2`，其中 `gpt-image-2` 是当前推荐使用的模型，详见上文 [GPT-Image-2 模型](#gpt-image-2-模型) 一节。 ## 异步回调 由于 OpenAI Images Edits API 编辑图片的时间可能相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个 `callback_url` 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 `task_id` 的字段信息，代表当前的任务 ID。当任务完成之后，编辑图片的结果会通过 POST JSON 的形式发送到客户端指定的 `callback_url`，其中也包括了 `task_id` 字段，这样任务结果就可以通过 ID 关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 [https://webhook.site/，打开该网站即可得到一个](https://webhook.site/，打开该网站即可得到一个) Webhook URL，如图所示： ![](https://cdn.xhuoapi.ai/cjjfly.png) 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`。 接下来，我们可以设置字段 `callback_url` 为上述 Webhook URL，同时填入相应的参数，如以下代码所示： ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` 调用之后，可以发现会立即得到一个结果，如下： ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` 稍等片刻，我们可以在 Webhook URL 上观察到编辑图片的结果，内容如下： ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` 可以看到结果中有一个 `task_id` 字段，`data` 字段包含了和同步调用一样的图片编辑结果，通过 `task_id` 字段即可实现任务的关联。 ## 错误处理 在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如： * `400 token_mismatched`：Bad request, possibly due to missing or invalid parameters. * `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters. * `401 invalid_token`：Unauthorized, invalid or missing authorization token. * `429 too_many_requests`：Too many requests, you have exceeded the rate limit. * `500 api_error`：Internal server error, something went wrong on the server. ### 错误响应示例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 结论 通过本文档，您已经了解了如何使用 OpenAI Images Edits API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。