OpenAI Images Edits API 的应用与使用

OpenAI 的图像编辑服务允许用户输入任意数量的图像和编辑指令，输出修改后的图像。这篇文章将手把手地介绍如何使用 OpenAI Images Edits API，使你能够轻松利用 OpenAI 官方的图像编辑功能。

环境准备

在开始之前，请确保你已经注册并登录到 Ace Data Cloud。你需要一个有效的 API 密钥来进行身份验证。

申请流程

要使用 OpenAI Images Edits API，首先访问 OpenAI Images Edits API 页面，点击"获取"按钮以获得所需的凭据：

如果你尚未登录或注册，系统会自动重定向到登录页面。登录或注册后，你将被自动返回到当前页面。

首次申请时，系统会提供一个免费的配额，让你可以免费使用该 API。

基本使用

接下来，我们可以通过代码发起调用，以下是使用 CURL 的示例：

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 items in it'

在使用此接口时，我们需要填写至少四个信息：authorization，可以直接从下拉列表中选择；model，这是我们选择使用的 OpenAI 官方模型的类别；prompt，是生成图像的输入提示；最后是 image，需要编辑图像的路径，如下图所示：

使用 Python 的示例代码如下：

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)

# 保存图像到文件
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 中，你可以使用以下命令设置环境变量：

shell 复制代码

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，并填写相应参数，代码如下：

shell 复制代码

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"

调用后，你将立即收到如下结果：

json 复制代码

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

片刻后，我们可以在 Webhook URL 观察编辑图像的结果，内容如下：

json 复制代码

{
  "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：错误请求，可能是由于缺少或无效的参数。
400 api_not_implemented：错误请求，可能是由于缺少或无效的参数。
401 invalid_token：未授权，令牌无效或缺失。
429 too_many_requests：请求过多，超出速率限制。
500 api_error：内部服务器错误，服务器出现问题。

错误响应示例

json 复制代码

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

总结

通过本文，你已学习如何轻松使用 OpenAI 的图像编辑功能与 OpenAI Images Edits API。希望本文能帮助你更好地集成与使用该 API。如果你有任何问题，请随时联系技术支持团队。

技术标签：#OpenAI #图像编辑 #API #开发教程 #AceDataCloud