> ## Documentation Index
> Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Images Generations API 申請および使用方法

> OpenAI generation 集成指南 - Ace Data Cloud

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](https://platform.acedata.cloud/documents/openai-images-generations) ページで「Acquire」ボタンをクリックし、リクエストに必要な認証情報を取得してください。

![](https://cdn.acedata.cloud/nyq0xz.png)

未ログインまたは未登録の場合は自動的にログインページにリダイレクトされ、登録・ログイン後に元のページに戻ります。

初回申請時には無料クレジットが付与され、この API を無料で利用可能です。

## 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` に永久ホスティングされた画像リンクで、ブラウザで直接開くかウェブページに埋め込むことができます。

### サポートされる `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"` を指定するか、**`size` フィールドを省略**すると、モデルがデフォルトのサイズを自動選択します。
>
> 1K 解像度では上流出力が厳密なピクセル数に合致しない場合があります。例えば `1024x1024` を指定しても `1254x1254` が返ることがありますが、比率は維持されます。この場合、その解像度を再度 `size` に指定しても課金は変わりません。
>
> 4K の単一呼び出しは通常4～8分かかるため、後述の `callback_url` を使った非同期コールバックの利用を推奨します。

> **`n` パラメータについて**
>
> `gpt-image-2` は現時点で **`n > 1` をサポートしていません**。このパラメータは無視され、`n=1` でも `n=10` でも単一画像のみ返却され、料金も1枚分のみ課金されます。複数画像が必要な場合は、**複数回のリクエストを並行して送信してください**（異なる `prompt` または異なる `seed` を指定することを推奨します。さもなければ類似画像が生成される可能性があります）。この制限は `gpt-image-1` / `gpt-image-1.5`、および `nano-banana` / `nano-banana-2` / `nano-banana-pro` シリーズにも適用されます。`dall-e-2` は唯一 `n > 1` をネイティブサポートするモデルで、`dall-e-3` は `n = 1` のみ対応です。

以下に複数の実例を示し、`gpt-image-2` の能力を直感的にご紹介します。

### シーン1：映画風ポートレート

プロンプトに映画用語（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"
    }
  ]
}
```

生成画像例：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png" width="500" className="m-auto" />
</p>

### シーン2：レトロ旅行ポスター（文字レンダリング付き）

`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` に対応する画像：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/c6061f92-3fae-498e-af8e-688e7f415ba3_0.png" width="500" className="m-auto" />
</p>

Art Deco ポスターの視覚スタイルが正確に再現されており、タイトル文字 `AMALFI` と `ITALIA 1958` が鮮明かつ正確にレンダリングされています。

### シーン3：複雑な構図と数量指定

以下のプロンプトは「数量」と「位置」などの構造化指示の遵守能力をテストします。

```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"
}
```

生成画像例：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/64a3b932-a082-4cad-9f85-9d30474b104d_0.png" width="500" className="m-auto" />
</p>

三段の本棚の本の数（1 / 3 / 7）がプロンプトと完全に一致しており、`dall-e-3` 時代には安定して実現が難しかった性能です。

### シーン4：イラストスタイル（横長）

アートメディアやムードのキーワードを指定することで、スタイライズされたイラストを生成可能です。

```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"
}
```

生成された横長イラスト：

![](https://platform.cdn.acedata.cloud/gpt-image/6cd57e69-d237-4cc1-a666-759a93964a08_0.png)

### 非同期およびコールバック

`gpt-image-2` の単一呼び出しは通常60～90秒かかります。長時間の接続を維持したくない場合は、後述の `callback_url` を使った非同期コールバック機構を利用可能で、呼び出し手順は他モデルと同様です。

## Nano Banana シリーズモデル

`nano-banana` シリーズは Gemini ベースの画像生成モデルで、同じ `/openai/images/generations` インターフェースから利用可能です。エンドポイントを切り替える必要はなく、`model` を以下のいずれかに変更するだけで利用できます。

| モデル               | 課金（クレジット／回） | 適用シーン                         |
| ----------------- | ----------- | ----------------------------- |
| `nano-banana`     | 0.14        | 一般的な画像生成、最速かつ最安価              |
| `nano-banana-2`   | 0.28        | 品質とディテールが明確に向上                |
| `nano-banana-pro` | 0.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` と同一です。

### 基本呼び出し例

```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": "a small red apple on a white table, photoreal"
    }
  ]
}
```

生成画像は返却された `url` から直接アクセス可能です。

<p>
  <img src="https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" width="500" className="m-auto" />
</p>

### フラッグシップモデル `nano-banana-pro` へのアップグレード

`model` を `nano-banana-pro` に変更するだけで、他のパラメータは同じです。

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

返却例：

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

<p>
  <img src="https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png" width="500" className="m-auto" />
</p>

### 非同期コールバック

`callback_url` による非同期コールバック機構は nano-banana シリーズでも有効で、呼び出し手順は他モデルと同様です。詳細は後述の [非同期コールバック](#非同期コールバック) セクションを参照してください。

## 基本的な使い方

画面上で対応する内容を入力します。例：

<p>
  <img src="https://cdn.acedata.cloud/zv58ug.png" width="500" className="m-auto" />
</p>

初回利用時は少なくとも3つの項目を入力します。1つは `authorization` で、ドロップダウンリストから選択可能です。もう1つは `model` で、OpenAI DALL-E の公式モデルカテゴリを選択します。ここでは主に1種類のモデルを用意しています。最後に `prompt` を入力し、生成したい画像の説明を記述します。

右側には対応する呼び出しコードが生成されており、コピーして直接実行したり、「Try」ボタンでテストできます。

<p>
  <img src="https://cdn.acedata.cloud/pbss4f.png" width="500" className="m-auto" />
</p>

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"
}

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

呼び出し後の返却例：

```json theme={null}
{
  "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` は生成された画像の詳細リンクで、以下のように表示されます。

<p>
  <img src="https://cdn.acedata.cloud/dz7u0x.png" width="500" className="m-auto" />
</p>

## 画像品質パラメータ `quality`

生成画像の詳細パラメータの設定方法を紹介します。画像品質パラメータ `quality` は2種類あり、`standard` は標準的な画像生成、`hd` はより細かいディテールと高い一貫性を持つ画像生成を意味します。

以下は `quality` を `standard` に設定した例：

<p>
  <img src="https://cdn.acedata.cloud/1q303w.png" width="500" className="m-auto" />
</p>

右側に対応する呼び出しコードが生成され、コピーして実行可能です。

<p>
  <img src="https://cdn.acedata.cloud/c0ps6i.png" width="500" className="m-auto" />
</p>

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",
    "quality": "standard"
}

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

返却例：

```json theme={null}
{
  "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` 品質の画像例：

<p>
  <img src="https://cdn.acedata.cloud/j5v15b.png" width="500" className="m-auto" />
</p>

同様に `quality` を `hd` に設定すると、以下のようなより精細で一貫性の高い画像が得られます。

<p>
  <img src="https://cdn.acedata.cloud/vjpbqr.png" width="500" className="m-auto" />
</p>

## 画像サイズパラメータ `size`

生成画像のサイズも設定可能です。以下は `1024x1024` に設定した例：

<p>
  <img src="https://cdn.acedata.cloud/dx5rwh.png" width="500" className="m-auto" />
</p>

右側に対応コードが生成されます。

<p>
  <img src="https://cdn.acedata.cloud/0sbybl.png" width="500" className="m-auto" />
</p>

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"
    }
  ]
}
```

`1024x1024` サイズの生成画像例：

<p>
  <img src="https://cdn.acedata.cloud/o4pvvx.png" width="500" className="m-auto" />
</p>

同様に `1792x1024` に設定した場合の画像：

![](https://cdn.acedata.cloud/4pilae.png)

サイズが明確に異なることがわかります。その他のサイズ設定については公式ドキュメントを参照してください。

## 画像スタイルパラメータ `style`

画像スタイルパラメータ `style` は2種類あります。`vivid` はより鮮やかで生き生きとした画像を生成し、`natural` はより自然な画像を生成します。

以下は `style` を `vivid` に設定した例：

<p>
  <img src="https://cdn.acedata.cloud/609l9i.png" width="500" className="m-auto" />
</p>

右側に対応コードが生成されます。

<p>
  <img src="https://cdn.acedata.cloud/ee3u9o.png" width="500" className="m-auto" />
</p>

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` スタイルの生成画像例：

<p>
  <img src="https://cdn.acedata.cloud/e0rpc3.png" width="500" className="m-auto" />
</p>

同様に `style` を `natural` に設定した場合の画像：

<p>
  <img src="https://cdn.acedata.cloud/q9tqwu.png" width="500" className="m-auto" />
</p>

`vivid` は `natural` よりも生き生きとリアルな画像を生成します。

## 画像リンクのフォーマットパラメータ `response_format`

最後に画像リンクのフォーマットパラメータ `response_format` には2種類あります。`b64_json` は画像リンクを Base64 エンコードしたもので、`url` は通常の画像リンクで直接画像を閲覧可能です。

以下は `response_format` を `url` に設定した例：

<p>
  <img src="https://cdn.acedata.cloud/2zbgrg.png" width="500" className="m-auto" />
</p>

右側に対応コードが生成されます。

<p>
  <img src="https://cdn.acedata.cloud/a9exmp.png" width="500" className="m-auto" />
</p>

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",
    "response_format": "url"
}

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

返却例：

```json theme={null}
{
  "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` フォーマットの画像リンクは直接アクセス可能で、画像は以下の通りです。

<p>
  <img src="https://cdn.acedata.cloud/33hs4z.png" width="500" className="m-auto" />
</p>

同様に `response_format` を `b64_json` に設定すると、Base64 エンコードされた画像リンクが返ります。例：

```json theme={null}
{
  "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 は即座に `task_id` を含むレスポンスを返します。タスク完了後、生成画像の結果が POST JSON 形式でクライアント指定の `callback_url` に送信されます。`task_id` によりタスク結果を紐付け可能です。

以下に具体例を示します。

まず Webhook コールバックは HTTP リクエストを受け取れるサービスで、開発者は自身で構築した HTTP サーバーの URL に置き換えてください。ここではデモ用に公開 Webhook サイト [https://webhook.site/](https://webhook.site/) を使用します。サイトを開くと Webhook URL が取得できます。

![](https://cdn.acedata.cloud/cjjfly.png)

この URL をコピーし、Webhook として利用します。例：`https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`

次に `callback_url` フィールドに上記 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": "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)
```

実行すると即座に以下のようなレスポンスが返ります。

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

`task_id` と `data` フィールドにより、同期呼び出しと同様の画像生成結果をタスク ID で紐付け可能です。

## エラー処理

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 の接続や利用に役立ててください。ご不明点があれば、いつでも技術サポートチームまでお問い合わせください。
