OpenAI Images Edits API 申请及使用

OpenAI 图片编辑服务，可以传入任意多张图片和指令，输出修改之后的图片。

本文档主要介绍 OpenAI Images Edits API 操作的使用流程，利用它我们可以轻松使用官方 OpenAI 图像编辑功能。

申请流程

要使用 OpenAI Images Edits API，首先可以到 OpenAI Images Edits API 页面点击「Acquire」按钮，获取请求所需要的凭证：

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用

接下来就可以使用代码进行调用，下方是通过CURL进行调用：

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.acedata.cloud/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 样例调用代码：

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.acedata.cloud/openai，还有一个使用凭证变量OPENAI_API_KEY，这个值是从authorization获取到的，在Mac OS可以通过以下命令设置环境变量：

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

调用之后，我们发现会在当前目录下生成一张图片gift-basket.png，具体的结果如下：

这样我们就完成了对图片的编辑操作，目前官方Edits任务只支持俩种模型，分别为：`dall-e-2`，`gpt-image-1`。

异步回调

由于 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/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，如以下代码所示：

curl -X POST "https://api.acedata.cloud/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"

调用之后，可以发现会立即得到一个结果，如下：

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

稍等片刻，我们可以在 Webhook URL 上观察到编辑图片的结果，内容如下：

{
  "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.

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

,
“error”: {
“code”: “api_error”,
“message”: “fetch failed”
},
“trace_id”: “2cf86e86-22a4-46e1-ac2f-032c0f2a4e89”
}

## 结论

通过本文档，您已经了解了如何使用 OpenAI Images Edits API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。