> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API: Запит та використання > OpenAI generation 集成指南 - XHuoAPI Сервіс редагування зображень 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://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) та натисніть кнопку «Acquire», щоб отримати необхідні для запиту облікові дані: ![](https://cdn.xhuoapi.ai/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`: * **1K стандартна ціна**: будь-який рекомендований розмір 1K з таблиці нижче або поширені 1K псевдоніми (`1254x1254`, `1672x941`, `941x1672`). * **Інші тарифи (1.5×)**: рекомендовані 2K / 4K розміри з таблиці, а також будь-які ваші власні `WIDTHxHEIGHT`. Жорсткі обмеження з боку сервера: ширина і висота мають бути кратні 16, довша сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400. | Співвідношення | 1K (стандартна ціна) | 2K рекомендоване (×1.5) | 4K рекомендоване (×1.5) | | -------------- | -------------------- | ----------------------- | ----------------------- | | 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 зображення, тарифікується як «інші»; при `3840x2160` виводиться 4K горизонтальне зображення, також тарифікується як «інші»; при `auto` або пропущеному параметрі тарифікується як 1K стандартна ціна. > **Про параметр `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.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Відредаговане зображення:

Як видно, структура модулів, розподіл інформації, шрифти збережені, змінено лише кольорову схему на темну. > **Підказка**: поле `image` також підтримує масив, наприклад `"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.xhuoapi.ai/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.xhuoapi.ai/v1/openai` та `OPENAI_API_KEY` у значення отриманого токена: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## Серія моделей Nano Banana Серія `nano-banana` також інтегрована через `/openai/images/edits`, достатньо вказати у `model` будь-яку з моделей таблиці: | Модель | Вартість (Credits / запит) | Сценарій використання | | ----------------- | -------------------------- | ----------------------------------------------------------- | | `nano-banana` | 0.14 | Звичайне редагування, найшвидший та найдешевший | | `nano-banana-2` | 0.28 | Покращена якість і деталізація | | `nano-banana-pro` | 0.35 | Флагман серії, найкраще збереження структури, тексту, стилю | > **Важливо: підтримувані параметри** > > Nano Banana підключається через адаптер OpenAI протоколу і підтримує лише параметри: `model`, `prompt`, `image`. > > * `image` можна передавати як файл через `multipart/form-data` (всередині worker конвертує у `data:;base64,...` для upstream), або як 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.xhuoapi.ai/v1/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.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Відповідь: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/v1/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.xhuoapi.ai/v1/openai` та `OPENAI_API_KEY` зі значенням токена: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/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)). ## Асинхронний callback Оскільки редагування зображень може займати тривалий час, щоб уникнути тривалого утримання HTTP-з’єднання і зайвих ресурсів, API підтримує асинхронний callback. Процес: клієнт при запиті вказує поле `callback_url`. API одразу повертає відповідь із `task_id` — ідентифікатором завдання. Після завершення редагування результат у форматі POST JSON надсилається на `callback_url`, включно з `task_id` для зв’язку результату із завданням. Приклад: Webhook callback — це HTTP-сервер, який приймає запити. Для демонстрації можна використати публічний сервіс [https://webhook.site/](https://webhook.site/), де після відкриття сайту отримаєте URL вебхука, наприклад: ![](https://cdn.xhuoapi.ai/cjjfly.png) Скопіюйте URL, наприклад `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Далі виконайте запит із параметром `callback_url`: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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.site з’явиться результат редагування: ```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` з результатом редагування, що дозволяє зв’язати завдання за 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. Якщо виникнуть питання, звертайтеся до нашої технічної підтримки.