> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAI 圖像生成 API 申請及使用
> OpenAI generation 整合指南 - Ace Data Cloud
OpenAI 圖像生成 API 目前支持多種圖像生成模型，包括經典的 `dall-e-3`、文字渲染能力更強的 `gpt-image-1`、最新一代的 **`gpt-image-2`**，以及通過同一接口接入的 **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`** 系列模型。它們都能根據文本描述生成高質量的圖像。
本文檔主要介紹 OpenAI 圖像生成 API 操作的使用流程，利用它我們可以輕鬆使用 OpenAI 系列的圖像生成功能。
## 申請流程
要使用 OpenAI 圖像生成 API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。
如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。
**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。
> 📘 完整文檔：[OpenAI 圖像生成 API →](https://platform.acedata.cloud/documents/openai-images-generations)
## GPT-Image-2 模型
`gpt-image-2` 是 OpenAI 推出的新一代圖像生成模型，相比 `dall-e-3` 和 `gpt-image-1`，在以下方面有明顯提升：
* **指令遵循能力更強**：能夠準確理解複雜構圖、計數、位置關係等結構化指令。
* **文字渲染更清晰**：海報、菜單、信息圖、標誌等場景下的英文與數字幾乎不會出現錯亂。
* **風格表現更豐富**：原生支持電影感人像、復古海報、兒童插畫、產品攝影、信息圖等多種風格。
* **原生多比例 + 高分辨率支持**：覆蓋 5 種比例（1:1、4:3、3:4、16:9、9:16）共 3 档分辨率（1K / 2K / 4K）。
調用方式與其它模型完全一致，只需將 `model` 字段設置為 `gpt-image-2` 即可。返回結果中的 `url` 是一個永久托管在 `platform.cdn.acedata.cloud` 上的圖片鏈接，可以直接在瀏覽器中打開或嵌入到網頁中。
### 线路变体（`:official` / `:reverse`）
`gpt-image-2` 默認走標準线路。通過模型名後綴可以顯式選擇线路：
* **`gpt-image-2:official`**：官方通道，穩定合規。支持真實 2K / 4K 分辨率，**按每張圖片計費，單價為默認 `gpt-image-2` 的 2 倍**。线路不可用時直接返回錯誤，不會自動降級。
* **`gpt-image-2:reverse`**：與默認 `gpt-image-2` 完全等價，性價比更高，價格不變。
### 支持的 `size` 取值
`gpt-image-2` 只檢查 `size` 的格式，只要不是 `auto` 或空串，就需要匹配 `WIDTHxHEIGHT`（例如 `1024x1024`、`2048x1152`、`800x600`）；任何其他形態會返回 400。**所有尺寸（1K / 2K / 4K / 自定義）按單張統一扣費，不按尺寸加價。**
尺寸限制：自定義尺寸須滿足寬高均為 16 的倍數、長邊 ≤ 3840、總像素數 ≤ 8,294,400，超出範圍會以 4xx 返回。
| 比例 | 1K 推薦 | 2K 推薦 | 4K 推薦 |
| ---- | ----------- | ----------- | ----------- |
| 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` |
> 顯式傳 `size: "auto"` 時，平台會在連續比例空間中規劃畫布，並按以下優先級判斷：提示詞中的明確像素或比例、命名標準（紙張 / 印刷品 / 平台版位 / 廣告 / 設備 / 攝影 / 電影）、介質慣例、最後才是構圖推斷。因此除了常見的 `1:1`、`4:5`、`9:16`、`21:9`，也能保留 `1.91:1`、`1.85:1`、`2.39:1`、ISO 紙張 `1:√2` 等非預設比例；最終尺寸會自動調整為服務支持的 16 倍數和像素預算。自動判斷不可用時會回退到模型默認畫幅，不會阻斷生成。省略 `size` 字段則直接使用模型默認畫幅；對像素有嚴格要求時仍建議直接傳 `WIDTHxHEIGHT`。
> 1K 档下輸出不保證嚴格像素對齊——你傳 `1024x1024` 可能拿到 `1254x1254`，比例保持一致。如果你重新把它當作 `size` 傳進來，計費不變。
> 4K 單次調用通常需要 4–8 分鐘，建議配合後文的 `callback_url` 異步回調使用。
> **關於 `n` 參數**
> `gpt-image-2` 支持 `n > 1`（取值 1–10）：一次請求即可返回並按張計費對應數量的圖片。為了讓多張結果有差異，建議同時傳不同的 `prompt` 或 `seed`。同樣適用於 `gpt-image-1` / `gpt-image-1.5`，以及 `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` 系列；`dall-e-3` 僅支持 `n = 1`。注意 `response_format=b64_json` 僅支持 `n=1`，`n>1` 時請使用默認的 URL 返回。若其中部分圖片生成失敗，只會返回並計費成功的部分。
下面通過幾個不同方位的真實示例來直觀感受 `gpt-image-2` 的能力。
### 場景一：電影感人像
提示詞中可以使用電影術語（35mm 膠卷、淺景深、霓虹光等）來精確控制氛圍與質感。
Python 範例調用代碼：
```python theme={null}
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)
```
返回結果如下：
```json theme={null}
{
"success": true,
"task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3",
"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/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
}
]
}
```
生成的圖片如下所示：
### 場景二：復古旅行海報（帶文字渲染）
`gpt-image-2` 在排版與字體渲染方面表現穩定，非常適合用來生成海報、菜單、賀卡等帶文字的設計稿。
```python theme={null}
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` 都被清晰、正確地渲染出來。
### 場景三：複雜構圖與計數
下面這個提示詞用來測試模型對“數量”和“位置”等結構化指令的遵循能力。
```python theme={null}
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` 時代很難穩定做到的。
### 場景四：插畫風格（橫屏）
通過指定藝術媒介與情緒關鍵詞，可以引導模型產出風格化的插畫。
```python theme={null}
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-banana` | 0.14 | 普通圖像生成，速度最快、成本最低 |
| `nano-banana-2-lite` | 0.14 | Gemini 3.1 輕量圖像模型，仅支持 1K，低延遲出圖 |
| `nano-banana-2` | 0.28 | 質量與細節明顯提升 |
| `nano-banana-pro` | 0.35 | 系列中的旗艦，構圖、細節、文字均最佳 |
> **重要：參數支持範圍**
> Nano Banana 通過適配層接入 OpenAI 協議，與 `gpt-image-*` 相比僅支持以下參數：`model`、`prompt`、`size`、`n`。
>
> * `size` 會按下表映射為內部 `aspect_ratio`，未列出的尺寸會退化為 `1:1`：
> * `1024x1024` / `512x512` / `256x256` → `1:1`
> * `1792x1024` → `16:9`
> * `1024x1792` → `9:16`
> * 不支持 `quality`、`style`、`response_format`、`background`、`output_format` 等參數；填了也會被忽略。`n > 1` 則受支持（1–10），會返回並按張計費對應數量的圖片。
> * 返回結構遵循 OpenAI 格式（`data[].url`），但 `created` 固定為 `0`，且不會返回 `b64_json`，`revised_prompt` 始終等於原始 `prompt`。
### 基本調用
```python theme={null}
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)
```
返回結果如下：
```json theme={null}
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
"revised_prompt": "一顆小紅蘋果在白色桌子上，照片寫實"
}
]
}
```
生成的圖片可以直接通過返回的 `url` 字段訪問：
### 升級到旗艦模型 `nano-banana-pro`
只需把 `model` 改為 `nano-banana-pro`，其餘參數完全一致：
```python theme={null}
payload = {
"model": "nano-banana-pro",
"prompt": "抽象畫",
"size": "1024x1024"
}
```
返回示例：
```json theme={null}
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
"revised_prompt": "抽象畫"
}
]
}
```
### 非同步回調
`callback_url` 非同步回調機制對 nano-banana 同樣有效，調用流程與其它模型完全一致，詳見下文 [非同步回調](#非同步回調) 一節。
## 基本使用
接下來就可以在介面上填寫對應的內容，如圖所示：
在第一次使用該接口時，我們至少需要填寫三個內容，一個是 `authorization`，直接在下拉列表裡面選擇即可。另一個參數是 `model`， `model` 就是我們選擇使用 OpenAI DALL-E 官網模型類別，這裡我們主要有 1 種模型，詳情可以看我們提供的模型。最後一個參數是`prompt`，`prompt` 是我們輸入要生成圖像的提示詞。
同時您可以注意到右側有對應的調用代碼生成，您可以複製代碼直接運行，也可以直接點擊「Try」按鈕進行測試。
Python 樣例調用代碼：
```python theme={null}
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": "一隻可愛的海獺寶寶"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
調用之後，我們發現返回結果如下：
```json theme={null}
{
"created": 1721626477,
"data": [
{
"revised_prompt": "一幅愉快的圖像展示了一隻年輕的海獺，它出生時是棕色的，擁有寬大的迷人眼睛。它愉快地躺在背上，在平靜的海水中划水。它濃密、柔軟的毛發看起來濕潤而閃閃發光，捕捉了它棲息地的本質。這隻小生物好奇地用小爪子玩著一個海貝，看起來在它的自然環境中絕對無辜而迷人。",
"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 樣例調用代碼：
```python theme={null}
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": "一隻可愛的海獺寶寶",
"quality": "standard"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
調用之後，我們發現返回結果如下：
```json theme={null}
{
"created": 1721636023,
"data": [
{
"revised_prompt": "一隻可愛的海獺寶寶在水中愉快地躺著，毛發看起來光滑而柔軟。它的一隻小爪子好奇地伸出，臉上帶著純粹的喜悅和溫暖的表情，仰望著天空。它的身體周圍環繞著因為在水中嬉戲而產生的氣泡。微風輕拂著它的毛發，使它看起來更加迷人。這個場景描繪了海洋生物的寧靜和魅力。",
"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 样例调用代码：
```python theme={null}
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)
```
调用之后，我们发现返回结果如下：
```json theme={null}
{
"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 样例调用代码：
```python theme={null}
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)
```
调用之后，我们发现返回结果如下：
```json theme={null}
{
"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 範例調用代碼：
```python theme={null}
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": "一隻可愛的海獺寶寶",
"response_format": "url"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
調用之後，我們發現返回結果如下：
```json theme={null}
{
"created": 1721637575,
"data": [
{
"revised_prompt": "一幅迷人的海獺寶寶的描繪。海獺安靜地仰躺在柔和的藍色海浪中。海獺寶寶的毛皮是柔和的灰褐色混合，微微在柔和的陽光下閃爍。它的小爪子輕輕抬起，似乎在玩弄一個看不見的物體。它圓圓的、表情豐富的眼睛充滿好奇，閃爍著生命和純真。使用寫實風格來喚起海獺的自然棲息地和它可愛的毛茸茸外觀。",
"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](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) 這是可以直接訪問的，圖片內容如下圖所示：
與上述相同操作，僅需將圖片鏈接的格式參數為 `b64_json` ，可以得到結果 Base64 編碼後的圖片鏈接，具體結果如下圖所示：
```json theme={null}
{
"created": 1721638071,
"data": [
{
"b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==",
"revised_prompt": "一幅迷人的年輕海獺寶寶的圖片。海獺輕輕漂浮在平靜的藍色海面上，沐浴在從清澈的天空中灑下的溫暖金色陽光中。海獺的毛皮是豐富的巧克力棕色，看起來非常柔軟和蓬鬆。海獺的眼睛明亮而富有表情，充滿了孩子般的好奇和快樂。它有小小的豎耳和像鈕扣一樣的鼻子，增添了它的可愛程度。在它周圍的海水中，可以看到閃閃發光的水滴，在陽光的照耀下，這一幕無疑是令人愉悅的。"
}
]
}
```
## 非同步回調
由於 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 樣例網站 [https://webhook.site/，打開該網站即可得到一個](https://webhook.site/，打開該網站即可得到一個) Webhook URL，如圖所示：
將此 URL 複製下來，就可以作為 Webhook 來使用，此處的樣例為 `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`。
接下來，我們可以設置字段 `callback_url` 為上述 Webhook URL，同時填入相應的參數，如以下代碼所示：
```python theme={null}
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": "一隻可愛的海獺寶寶",
"callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
點擊運行，可以發現會立即得到一個結果，如下：
```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": [
{
"revised_prompt": "一幅展示年輕海獺的愉快圖片...",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/..."
}
]
}
}
```
可以看到結果中有一個 `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 theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 結論
通過本文檔，您已經了解了如何使用 OpenAI Images Generations API 輕鬆使用官方 OpenAI DALL-E 的圖像生成功能。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支持團隊。