> ## 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).

Вызов API идентичен другим моделям, достаточно указать поле `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` с сохранением пропорций. Если использовать это значение повторно, плата не изменится.
>
> Вызов для 4K обычно занимает 4–8 минут, рекомендуется использовать асинхронный `callback_url` для обратного вызова.

> **О параметре `n`**
>
> В `gpt-image-2` **не поддерживается `n > 1`**: параметр игнорируется, и независимо от значения `n` возвращается только одно изображение, тарифицируемое как одно. Для получения нескольких вариантов необходимо самостоятельно параллельно отправлять несколько запросов (рекомендуется менять `prompt` или `seed`, чтобы избежать схожих результатов). Это ограничение также действует для моделей `gpt-image-1` / `gpt-image-1.5` и серии `nano-banana`. Единственная модель с нативной поддержкой `n > 1` — `dall-e-2`; `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>

Модель точно воспроизвела стиль арт-деко, заголовки `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`, смена endpoint не требуется — достаточно указать нужное значение `model` из таблицы ниже.

| Модель            | Стоимость (кредиты / вызов) | Сценарии использования                                      |
| ----------------- | --------------------------- | ----------------------------------------------------------- |
| `nano-banana`     | 0.14                        | Обычная генерация изображений, самая быстрая и дешевая      |
| `nano-banana-2`   | 0.28                        | Значительно улучшенное качество и детализация               |
| `nano-banana-pro` | 0.35                        | Флагман серии, лучшее качество композиции, деталей и текста |

> **Важное: поддерживаемые параметры**
>
> Nano Banana адаптирована под протокол OpenAI и поддерживает только параметры: `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>

При первом использовании API необходимо заполнить минимум три поля: `authorization` (выбирается из выпадающего списка), `model` (выбор модели OpenAI DALL-E, подробности в документации моделей), и `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` — уникальный идентификатор задачи генерации изображения.
* `data` — содержит информацию о сгенерированном изображении.

Внутри `data` поле `url` содержит ссылку на сгенерированное изображение.

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

## Параметр качества изображения `quality`

Далее рассмотрим, как настроить параметры качества результата генерации. Параметр `quality` имеет два значения: `standard` — стандартное качество, и `hd` — более детализированное и согласованное изображение.

Пример установки качества `standard`:

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

Справа отображается сгенерированный код вызова, который можно скопировать или запустить через кнопку «Try».

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

Аналогично, установив параметр качества в `hd`, получаем изображение с более детальной проработкой:

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

`hd` обеспечивает более тонкие детали и большую согласованность по сравнению с `standard`.

## Параметр размера изображения `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` имеет два значения: `vivid` — более живое изображение, и `natural` — более естественное.

Пример установки стиля `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 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>

Аналогично, параметр `natural` даёт более естественное изображение:

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

`vivid` создаёт более живые и яркие изображения по сравнению с `natural`.

## Параметр формата ссылки на изображение `response_format`

Параметр `response_format` имеет два значения: `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 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 может занимать продолжительное время, при отсутствии ответа HTTP-соединение остаётся открытым, что приводит к дополнительным затратам ресурсов. Поэтому API поддерживает асинхронный обратный вызов.

Процесс: клиент при запросе указывает поле `callback_url`. API сразу возвращает ответ с полем `task_id` — идентификатором задачи. После завершения генерации результат в формате POST JSON отправляется на указанный `callback_url`, включая `task_id` для связывания результата с задачей.

Пример настройки webhook — используем публичный сервис [https://webhook.site/](https://webhook.site/), где можно получить URL для приёма запросов:

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

Скопируйте URL, например `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, и используйте его в поле `callback_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 придёт результат:

```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` с результатом генерации, что позволяет связать ответ с запросом.

## Обработка ошибок

При ошибках 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. Если у вас возникнут вопросы, пожалуйста, обращайтесь в нашу техническую поддержку.
