> ## 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 Edits API: подача заявки та використання > OpenAI generation 集成指南 - Ace Data Cloud Сервіс редагування зображень OpenAI дозволяє передавати будь-яку кількість зображень та інструкцій, отримуючи на виході відредаговані зображення. Наразі інтерфейс підтримує `dall-e-2`, `gpt-image-1`, найновішу модель **`gpt-image-2`**, а також серію моделей **`nano-banana` / `nano-banana-2` / `nano-banana-pro`**, підключених через той самий інтерфейс. Цей документ головним чином описує процес використання OpenAI Images Edits API, що дозволяє легко користуватися офіційними функціями редагування зображень OpenAI. ## Процес подачі заявки Щоб користуватися OpenAI Images Edits API, спочатку перейдіть на сторінку [OpenAI Images Edits API](https://platform.acedata.cloud/documents/openai-images-edits) та натисніть кнопку «Acquire» для отримання необхідних облікових даних: ![](https://cdn.acedata.cloud/nyq0xz.png) Якщо ви ще не увійшли або не зареєстровані, вас автоматично перенаправлять на сторінку входу, де можна зареєструватися та увійти. Після входу ви повернетесь на цю сторінку. При першій подачі заявки надається безкоштовний ліміт для безкоштовного використання API. ## Модель GPT-Image-2 У сценаріях редагування зображень `gpt-image-2` має суттєві покращення у порівнянні з `gpt-image-1`: * **Стабільніше збереження структури**: при зміні шкіри, кольорів чи фону майже не порушується макет і композиція оригінального зображення. * **Точніше збереження тексту**: у інфографіках, постерах, меню та інших зображеннях з текстом текст залишається чітким і читабельним після редагування. * **Підтримка прямої передачі URL**: окрім традиційного завантаження файлів через `multipart/form-data`, `gpt-image-2` також **підтримує передачу URL зображень у форматі JSON**, що дозволяє не завантажувати зображення локально — ідеально для серверних конвеєрів. * **Підтримка високої роздільної здатності**: можна передати 1K оригінал і через параметр `size` запросити вихід 2K / 4K, модель одночасно виконає масштабування під час редагування. ### Підтримувані значення параметра `size` Обмеження параметра `size` в інтерфейсі редагування повністю збігаються з інтерфейсом генерації — `gpt-image-2` приймає `size` зі значеннями `auto`, порожнє або у форматі `WIDTHxHEIGHT`. Будь-які інші варіанти повернуть помилку 400. **Вартість розраховується за одне зображення незалежно від роздільної здатності оригіналу та запиту `size`.** Жорсткі обмеження на розмір: ширина і висота мають бути кратні 16, довга сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400. | Співвідношення | Рекомендовано 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` | > Наприклад: якщо оригінал `1024x1024`, при `size` = `2048x2048` модель відредагує та виведе 2K зображення; при `size` = `3840x2160` — 4K горизонтальне; при `auto` або відсутності параметра модель вибере сама. Вартість усіх трьох варіантів однакова. > **Про параметр `n`** > > Інтерфейс редагування `gpt-image-2` наразі **не підтримує `n > 1`**: цей параметр ігнорується, незалежно від значення `n` повертається лише одне зображення і стягується плата за одне. Якщо потрібно отримати кілька варіантів, слід робити кілька паралельних запитів. Це обмеження також діє для `gpt-image-1` / `gpt-image-1.5` та серії `nano-banana`. Лише `dall-e-2` підтримує `n > 1` нативно. Нижче наведено два реальні приклади, що демонструють можливості редагування `gpt-image-2`. ### Варіант виклику 1: JSON + URL зображення (рекомендовано) Відправляйте запит у форматі `application/json`, у полі `image` вказуйте URL зображення — модель завантажить його та відредагує згідно з `prompt`. Наприклад, оригінальне зображення — науково-популярна ілюстрація, згенерована `gpt-image-2`:

Ми хочемо змінити кольорову схему на «нічний режим». Запит виглядає так: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` Або на Python: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Відповідь: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Відредаговане зображення:

Структура модулів, розподіл інформації та шрифти збережені, змінена лише кольорова схема на темну. > **Підказка**: поле `image` підтримує масив URL, наприклад `"image": ["url1", "url2", "url3"]`, можна передати до 16 зображень для комплексного редагування. ### Варіант виклику 2: JSON + кілька референсних зображень `gpt-image-2` підтримує одночасне використання кількох зображень для створення результату, наприклад, об’єднання кількох фото товарів у кошик подарунків: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### Приклад сценарію: зміна стилю + збереження структури Інший приклад — замінити дерев’яну книжкову полицю на сучасну плаваючу, при цьому строго зберегти кількість і розташування книг на кожній полиці. Оригінал (створений `gpt-image-2` дерев’яна полиця):

Запит: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` Результат редагування (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Стиль і оточення повністю змінені відповідно до підказки, але кількість книг (1 / 3 / 7) збережена, а також додано маленьку сукуленту на верхній полиці. ### Варіант виклику 3: multipart/form-data (сумісність з OpenAI SDK) Якщо ви користуєтеся офіційним OpenAI Python SDK, традиційний спосіб завантаження через `multipart/form-data` також працює, достатньо змінити `model` на `gpt-image-2`: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` Для роботи з SDK потрібно встановити два змінні середовища: `OPENAI_BASE_URL` на `https://api.acedata.cloud/openai` та `OPENAI_API_KEY` на отриманий токен: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## Серія моделей Nano Banana Серія `nano-banana` також підключена через `/openai/images/edits`; достатньо вказати у `model` будь-яку з моделей таблиці нижче. | Модель | Вартість (кредити / запит) | Сценарії застосування | | ----------------- | -------------------------- | ------------------------------------------------------------------------ | | `nano-banana` | 0.14 | Звичайне редагування, найшвидша та найдешевша | | `nano-banana-2` | 0.28 | Покращена якість та деталізація | | `nano-banana-pro` | 0.35 | Флагманська модель серії, найкраще збереження структури, тексту та стилю | > **Важливо: підтримувані параметри** > > Nano Banana через адаптаційний шар підтримує лише параметри: `model`, `prompt`, `image`. > > * `image` можна передавати через `multipart/form-data` (внутрішньо конвертується у `data:;base64,...`) або як URL у формі. > * Параметри `mask`, `n`, `size`, `response_format` не підтримуються і ігноруються. > * Відповідь відповідає формату OpenAI (`data[].url`), але `created` завжди 0, `b64_json` не повертається, а `revised_prompt` завжди дорівнює оригінальному `prompt`. ### Виклик через форму + URL зображення ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=add a green leaf on top of the apple" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Відповідь: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` Відредаговане зображення:

### Виклик через форму + локальний файл ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "add a green leaf on top of the apple" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### Асинхронний callback Механізм асинхронного callback через `callback_url` також підтримується для nano-banana, процес виклику ідентичний іншим моделям (див. розділ [Асинхронний callback](#асинхронний-callback)). ## Основне використання Далі можна викликати API через код. Приклад виклику через CURL: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` При першому використанні цього інтерфейсу потрібно вказати принаймні чотири параметри: `authorization` (вибирається зі списку), `model` (модель OpenAI, тут доступна одна основна, див. опис моделей), `prompt` (текстова підказка для генерації зображення) та `image` (шлях до зображення для редагування). Нижче приклад зображення для редагування:

Еквівалентний приклад на Python: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Збереження зображення у файл with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` Для виклику через Python потрібно встановити два змінні середовища: `OPENAI_BASE_URL` на `https://api.acedata.cloud/openai` та `OPENAI_API_KEY` на отриманий токен. У Mac OS це можна зробити так: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` Після виклику у поточній директорії з’явиться файл `gift-basket.png` з результатом:

Таким чином, ми завершили операцію редагування зображення. Інтерфейс Edits підтримує три моделі: `dall-e-2`, `gpt-image-1` та `gpt-image-2`, причому рекомендована модель — `gpt-image-2` (див. розділ [Модель GPT-Image-2](#модель-gpt-image-2)). ## Асинхронний callback Оскільки редагування зображень через OpenAI Images Edits API може займати тривалий час, HTTP-запит може довго утримувати з’єднання, що призводить до додаткових витрат системних ресурсів. Тому API підтримує асинхронний callback. Загальний процес: клієнт при запиті вказує поле `callback_url`. Після отримання запиту API одразу повертає результат із полем `task_id`, що ідентифікує завдання. Коли завдання завершується, результат редагування надсилається POST-запитом у форматі JSON на вказаний `callback_url`, включно з `task_id` для зв’язку результату із завданням. Розглянемо приклад. Webhook callback — це HTTP-сервер, який приймає запити. Розробник повинен замінити URL на власний сервер. Для демонстрації можна використати публічний сервіс [https://webhook.site/](https://webhook.site/), який генерує унікальний URL: ![](https://cdn.acedata.cloud/cjjfly.png) Скопіюйте цей URL, наприклад `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, і використовуйте як `callback_url` у запиті: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Відразу отримаємо відповідь: ```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": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` У відповіді є поле `task_id` та поле `data` з результатом редагування, як і при синхронному виклику. За `task_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 Edits API для зручного редагування зображень за допомогою офіційних функцій OpenAI. Сподіваємося, що він допоможе вам ефективно інтегрувати та використовувати цей API. Якщо виникнуть питання, звертайтеся до нашої технічної підтримки.