OpenAI GPT-Image-2 API 发布及文档更新

全模态研习社
0 阅读16分钟

OpenAI Images Generations API 申请及使用

OpenAI Images Generations API 目前支持多种图像生成模型，包括经典的 dall-e-3、文字渲染能力更强的 gpt-image-1、最新一代的 gpt-image-2，以及通过同一接口接入的 nano-banana / nano-banana-2 / nano-banana-pro 系列模型。它们都能根据文本描述生成高质量的图像。

本文档主要介绍 OpenAI Images Generations API 操作的使用流程，利用它我们可以轻松使用 OpenAI 系列的图像生成功能。

申请流程

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

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

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

GPT-Image-2 模型

gpt-image-2 是 OpenAI 推出的新一代图像生成模型，相比 dall-e-3 和 gpt-image-1，在以下方面有明显提升：

  • 指令遵循能力更强：能够准确理解复杂构图、计数、位置关系等结构化指令。
  • 文字渲染更清晰：海报、菜单、信息图、标志等场景下的英文与数字几乎不会出现错乱。
  • 风格表现更丰富：原生支持电影感人像、复古海报、儿童插画、产品摄影、信息图等多种风格。
  • 原生多比例支持：直接支持 1024x1024（方图）、1024x1536（竖屏）、1536x1024（横屏）。

调用方式与其它模型完全一致，只需将 model 字段设置为 gpt-image-2 即可。返回结果中的 url 是一个永久托管在 platform.cdn.acedata.cloud 上的图片链接，可以直接在浏览器中打开或嵌入到网页中。

下面通过几个不同方位的真实示例来直观感受 gpt-image-2 的能力。

场景一：电影感人像

提示词中可以使用电影术语（35mm 胶片、浅景深、霓虹光等）来精准控制氛围与质感。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

返回结果如下：

{
  "success": true,
  "task_id": "6738988a-ea3c-44ae-932f-488b14e5902b",
  "created": 1777048800,
  "data": [
    {
      "revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/6738988a-ea3c-44ae-932f-488b14e5902b_0.png"
    }
  ]
}

生成的图片如下所示：

转存失败，建议直接上传图片文件

场景二：复古旅行海报（带文字渲染）

gpt-image-2 在排版与字体渲染方面表现稳定，非常适合用来生成海报、菜单、贺卡等带文字的设计稿。

payload = {
    "model": "gpt-image-2",
    "prompt": "A vintage travel poster of the Amalfi Coast, Italy. Stylized art-deco illustration of cliffside lemon-yellow houses cascading down to a turquoise sea, with a small white sailboat in the harbor. Bold typography at the top reads AMALFI and at the bottom ITALIA 1958. Limited color palette: cream, sea-blue, lemon yellow, terracotta. Slight paper-grain texture.",
    "size": "1024x1536"
}

返回结果中的 url 字段对应的图片如下：

转存失败，建议直接上传图片文件

可以看到模型不仅准确还原了 Art Deco 海报的视觉风格，标题文字 AMALFI 与 ITALIA 1958 都被清晰、正确地渲染出来。

场景三：复杂构图与计数

下面这个提示词用来测试模型对“数量”和“位置”等结构化指令的遵循能力。

payload = {
    "model": "gpt-image-2",
    "prompt": "A wooden bookshelf consisting of three shelves: On the top shelf, there should be one book. On the second shelf, there should be three books. On the bottom shelf, there should be seven books. Soft warm lighting, photorealistic, cozy library atmosphere.",
    "size": "1024x1024"
}

生成的图片如下：

转存失败，建议直接上传图片文件

可以看到三层书架上的书本数量（1 / 3 / 7）与提示词完全一致，这是 dall-e-3 时代很难稳定做到的。

场景四：插画风格（横屏）

通过指定艺术媒介与情绪关键词，可以引导模型产出风格化的插画。

payload = {
    "model": "gpt-image-2",
    "prompt": "A soft, poetic children's book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.",
    "size": "1536x1024"
}

生成的横屏插画如下：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

异步与回调

gpt-image-2 单次调用通常需要 60～90 秒，如果不希望保持长连接，可以使用本文后续介绍的 callback_url 异步回调机制，调用流程与其它模型完全一致。

Nano Banana 系列模型

nano-banana 系列是基于 Gemini 的图像生成模型，已通过同一个 /openai/images/generations 接口接入，无需切换 endpoint，只要把 model 改为下表中的任意一个即可。

模型计费（Credits / 次）适用场景
nano-banana0.14普通图像生成，速度最快、成本最低
nano-banana-20.28质量与细节明显提升
nano-banana-pro0.35系列中的旗舰，构图、细节、文字均最佳

重要：参数支持范围

Nano Banana 通过适配层接入 OpenAI 协议，与 gpt-image-* 相比仅支持以下参数：model、prompt、size。

  • size 会按下表映射为内部 aspect_ratio，未列出的尺寸会退化为 1:1：
    • 1024x1024 / 512x512 / 256x256 → 1:1
    • 1792x1024 → 16:9
    • 1024x1792 → 9:16
  • 不支持 n、quality、style、response_format、background、output_format 等参数；填了也会被忽略。
  • 返回结构遵循 OpenAI 格式（data[].url），但 created 固定为 0，且不会返回 b64_json，revised_prompt 始终等于原始 prompt。

基本调用

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "nano-banana",
    "prompt": "a small red apple on a white table, photoreal",
    "size": "1024x1024"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

返回结果如下：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
      "revised_prompt": "a small red apple on a white table, photoreal"
    }
  ]
}

生成的图片可以直接通过返回的 url 字段访问：

升级到旗舰模型 nano-banana-pro

只需把 model 改为 nano-banana-pro，其余参数完全一致：

payload = {
    "model": "nano-banana-pro",
    "prompt": "abstract painting",
    "size": "1024x1024"
}

返回示例：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
      "revised_prompt": "abstract painting"
    }
  ]
}

异步回调

callback_url 异步回调机制对 nano-banana 同样有效，调用流程与其它模型完全一致，详见下文 异步回调 一节。

基本使用

接下来就可以在界面上填写对应的内容，如图所示：

在第一次使用该接口时，我们至少需要填写三个内容，一个是 authorization，直接在下拉列表里面选择即可。另一个参数是 model， model 就是我们选择使用 OpenAI DALL-E 官网模型类别，这里我们主要有 1 种模型，详情可以看我们提供的模型。最后一个参数是prompt，prompt 是我们输入要生成图像的提示词。

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

调用之后，我们发现返回结果如下：

{
  "created": 1721626477,
  "data": [
    {
      "revised_prompt": "A delightful image showcasing a young sea otter, who is born brown, with wide charming eyes. It is delightfully lying on its back, paddling in the calm sea waters. Its dense, velvety fur appears wet and shimmering, capturing the essence of its habitat. The small creature curiously plays with a sea shell with its small paws, looking absolutely innocent and charming in its natural environment.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回结果一共有多个字段，介绍如下：

  • created ，生成此次图像生成的 ID，用于唯一标识此次任务。
  • data，包含图像生成的结果信息。

其中 data 是包含了模型生成图片的具体信息，它里面的 url 是生成图片的详情链接，可以发现如图所示。

图片质量参数 quality

接下来将介绍如何设置图像生成结果的一些详细参数，其中图片质量参数 quality 包含俩种，第一个 standard 表示生成标准的图片，另一个 hd 表示创建的图像具有更精细的细节和更大的一致性。

下面设置图片质量参数为 standard ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "quality": "standard"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

调用之后，我们发现返回结果如下：

{
  "created": 1721636023,
  "data": [
    {
      "revised_prompt": "A cute baby sea otter is lying playfully on its back in the water, with its fur looking glossy and soft. One of its tiny paws is reaching out curiously, and it has an expression of pure joy and warmth on its face as it looks up to the sky. Its body is surrounded by bubbles from its playful twirling in the water. A gentle breeze is playing with its fur making it look more charming. The scene portrays the tranquility and charm of marine life.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片质量参数为 standard 的生成图片如下图所示：

与上述相同操作，仅需将图片质量参数设置为 hd ，可以得到如下图所示的图片：

可以看到 hd 比 standard 生成的图片具有更精细的细节和更大的一致性。

图片大小尺寸参数 size

我们还可以设置生成图片的尺寸大小，我们可以进行下面的设置。

下面设置图片的尺寸大小为 1024 * 1024 ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter"
    "size": "1024x1024"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

调用之后，我们发现返回结果如下：

{
  "created": 1721636652,
  "data": [
    {
      "revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片的尺寸大小为 1024 * 1024 的生成图片如下图所示：

与上述相同操作，仅需将图片的尺寸大小为 1792 * 1024 ，可以得到如下图所示的图片：

可以看到图片的尺寸大小很明显不一样，另外还可以设置更多尺寸大小，详情信息参考我们官网文档。

图片风格参数 style

图片风格参数 style 包含俩个参数，第一种 vivid 表示生成的图片是更加生动的，另一种 natural 表示生成的图片更加的自然一点。

下面设置图片风格参数为 vivid ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "style": "vivid"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

调用之后，我们发现返回结果如下：

{
  "created": 1721637086,
  "data": [
    {
      "revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片风格参数为 vivid 的生成图片如下图所示：

与上述相同操作，仅需将图片风格参数为 natural ，可以得到如下图所示的图片：

可以看到 vivid 比 natural 生成的图片具有更加生动逼真。

图片链接的格式参数 response_format

最后一个图片链接的格式参数 response_format 也有俩种，第一种 b64_json 是对图片链接进行 Base64 编码，另一种 url 就是普通的图片链接，可以直接查看图片。

下面设置图片链接的格式参数为 url ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "response_format": "url"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

调用之后，我们发现返回结果如下：

{
  "created": 1721637575,
  "data": [
    {
      "revised_prompt": "A charming depiction of a baby sea otter. The otter is seen resting serenely on its back amidst the gentle, blue ocean waves. The baby otter's fur is an endearing mix of soft greyish brown shades, glinting subtly in the muted sunlight. Its small paws are touching, lifted slightly towards the sky as if playing with an unseen object. Its round, expressive eyes are wide in curiosity, sparking with life and innocence. Use a realistic style to evoke the otter's natural habitat and its adorably fluffy exterior.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片链接的格式参数为 url 的生成图片的链接为 图片 URL 这是可以直接访问的，图片内容如下图所示：

与上述相同操作，仅需将图片链接的格式参数为 b64_json ，可以得到结果 Base64 编码后的图片链接，具体结果如下图所示：

{
  "created": 1721638071,
  "data": [
    {
      "b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==",
      "revised_prompt": "A charming image of a young baby sea otter. The otter is gently floating on a calm blue sea, basking in the warm, golden rays of sunlight streaming down from a clear sky above. The otter's fur is a rich chocolate brown, and it looks incredibly soft and fluffy. The otter's eyes are bright and expressive, filled with childlike curiosity and joy. It has small, pricked ears and a button-like nose which adds to its overall cuteness. In the sea around it, twinkling droplets of water can be seen, pepped up by the sunlight, the sight is certainly a delightful one."
    }
  ]
}

异步回调

由于 OpenAI Images Generations API 生成图片的时间可能相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 webhook.site/，打开该网站即可得到一… Webhook URL，如图所示：

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

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

import requests

url = "https://api.acedata.cloud/openai/images/generations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

点击运行，可以发现会立即得到一个结果，如下：

{
  "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": [
      {
        "revised_prompt": "A delightful image showcasing a young sea otter...",
        "url": "https://dalleprodsec.blob.core.windows.net/private/images/..."
      }
    ]
  }
}

可以看到结果中有一个 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"
}

结论

通过本文档，您已经了解了如何使用 OpenAI Images Generations API 轻松使用官方 OpenAI DALL-E 的图像生成功能。希望本文档能帮助您更好地对接和使用该 API。

avatar
文章
阅读
粉丝