> ## 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 Images Generations API > OpenAI generation API guide - Ace Data Cloud OpenAI Images Generations API наразі підтримує різноманітні моделі генерації зображень, включаючи класичну `dall-e-3`, `gpt-image-1` із потужнішими можливостями рендерингу тексту, новітнє покоління **`gpt-image-2`**, а також серію моделей **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`**, підключених через той самий інтерфейс. Усі вони можуть генерувати високоякісні зображення на основі текстових описів. Цей документ головним чином описує процес використання OpenAI Images Generations API. За допомогою нього ми можемо легко використовувати функції генерації зображень серії OpenAI. ## Процес подання заявки Щоб використовувати OpenAI Images Generations API, спочатку перейдіть до [Ace Data Cloud консолі](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token і зберегти його для подальшого використання. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Якщо ви ще не увійшли в систему або не зареєстровані, вас буде автоматично перенаправлено на сторінку входу, де буде запропоновано зареєструватися та увійти. Після завершення ви автоматично повернетеся на поточну сторінку. **Один API Token може викликати всі сервіси платформи, немає необхідності подавати окрему заявку для кожного сервісу.** Під час першої заявки буде надано безкоштовний ліміт, який можна використовувати для безкоштовного тестування; коли ліміт буде недостатнім, можна поповнити універсальний баланс у [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація：[OpenAI Images Generations 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`**：офіційна проксі-лінія. Підтримує `n > 1` (одночасне повернення кількох зображень) і справжню роздільну здатність 2K / 4K, **оплата здійснюється за кожне зображення, ціна за одиницю у 2 рази вища за стандартний `gpt-image-2`**. Наразі доступна лише через канал openai-hk, якщо лінія недоступна, буде безпосередньо повернуто помилку без переходу на реверс-лінію. * **`gpt-image-2:reverse`**：повністю еквівалентна стандартному `gpt-image-2` (реверс-лінія), використовується для явного зазначення використання реверс-лінії, ціна не змінюється. > Обмеження щодо параметра `n`, описані нижче, застосовуються лише до стандартної / реверс-лінії; `gpt-image-2:official` підтримує `n > 1` і тарифікується за кількістю зображень. ### Підтримувані значення `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 зображення, і оплата здійснюється лише за 1 зображення. Якщо вам потрібно отримати кілька варіантів зображень за один раз, будь ласка, **самостійно запускайте кілька паралельних запитів** (рекомендується одночасно передавати різні `prompt` або різні `seed`, інакше отримані зображення можуть бути дуже схожими). Це обмеження також застосовується до `gpt-image-1` / `gpt-image-1.5`, а також серії `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`. `dall-e-2` наразі є єдиною моделлю з нативною підтримкою `n > 1`; `dall-e-3` підтримує лише `n = 1`. Нижче наведено кілька реальних прикладів із різних ракурсів, щоб наочно відчути можливості `gpt-image-2`. ### Сценарій один: кінематографічний портрет У підказках можна використовувати кінематографічні терміни (35mm плівка, мала глибина різкості, неонове світло тощо), щоб точно контролювати атмосферу та якість текстури. Приклад виклику коду Python: ````markdown theme={null} ```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) ``` Результат відповіді виглядає так: ```json { "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" } ] } ``` Згенероване зображення показано нижче:

### Сценарій 2: Вінтажний туристичний постер (із рендерингом тексту) `gpt-image-2` стабільно працює з версткою та рендерингом шрифтів, тому чудово підходить для створення постерів, меню, листівок та інших макетів із текстом. ```python 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`. ### Сценарій 3: Складна композиція та підрахунок Наведений нижче промпт використовується для перевірки здатності моделі дотримуватися структурованих інструкцій, таких як «кількість» і «розташування». ```python 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` було дуже важко досягти стабільно. ### Сценарій 4: Стиль ілюстрації (горизонтальний формат) Вказавши художній стиль і ключові слова, що описують настрій, можна спрямувати модель на створення стилізованих ілюстрацій. ```python 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` на будь-яке з наведених у таблиці нижче. | Модель | Вартість (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`. > - `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 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 { "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`, інші параметри повністю залишаються такими ж: ```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" } ] } ```

### Асинхронний зворотний виклик Механізм асинхронного зворотного виклику `callback_url` також ефективний для nano-banana, процес виклику повністю такий самий, як і для інших моделей. Детальніше дивіться розділ [Асинхронний зворотний виклик](#异步回调) нижче. ## Базове використання Далі можна заповнити відповідний вміст у інтерфейсі, як показано на зображенні:

Під час першого використання цього API нам потрібно заповнити щонайменше три поля: одне з них — `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": "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` у ньому є детальним посиланням на згенероване зображення, що можна побачити на зображенні нижче.

## Параметр якості зображення `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": "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`, виглядає так:

与上述相同操作，仅需将图片质量参数设置为 `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` , чтобы получить изображение, показанное ниже: ![](https://cdn.acedata.cloud/4pilae.png) Можно увидеть, что размеры изображений явно отличаются, кроме того, можно установить больше вариантов размеров, подробную информацию смотрите в документации на нашем официальном сайте. ## Параметр стиля изображения `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": "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` має вигляд [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": "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`, яке представляє поточний ідентифікатор завдання. Коли завдання буде завершено, результат генерації зображення буде надіслано клієнту через POST JSON на вказаний клієнтом `callback_url`, де також буде міститися поле `task_id`, таким чином результат завдання можна буде пов'язати за ідентифікатором. Нижче ми розглянемо, як виконати конкретні операції за допомогою прикладу. Перш за все, Webhook-зворотний виклик — це сервіс, який може приймати HTTP-запити. Розробник повинен замінити його на URL власного HTTP-сервера. Для зручності демонстрації тут використовується відкритий приклад вебсайту 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` як наведений вище 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": "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" } ``` Трохи зачекавши, ми можемо побачити результат генерації зображення за URL 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` містить той самий результат генерації зображення, що й синхронний виклик. За допомогою поля `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 DALL-E через OpenAI Images Generations API. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.