> ## 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 и запросить вывод в 2K или 4K через параметр `size`, модель одновременно выполнит редактирование и масштабирование. ### Поддерживаемые значения `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 изображение согласно инструкции и будет тарифицироваться по уровню «другие»; при `size` `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` поддерживает передачу массива 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.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` любое из значений из таблицы ниже. | Модель | Стоимость (кредиты за запрос) | Сценарии использования | | ----------------- | ----------------------------- | ----------------------------------------------------------------------------- | | `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,...` для апстрима), либо как 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). ## Основное использование Далее пример вызова через 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 SDK необходимо задать два переменных окружения: `OPENAI_BASE_URL` в `https://api.xhuoapi.ai/v1/openai` и `OPENAI_API_KEY` — полученный токен. В macOS это можно сделать так: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` После вызова в текущей директории появится файл `gift-basket.png` с результатом:

Таким образом, мы завершили операцию редактирования изображения. В настоящее время Edits API поддерживает три модели: `dall-e-2`, `gpt-image-1` и `gpt-image-2`. Рекомендуется использовать `gpt-image-2`, подробнее в разделе [Модель GPT-Image-2](#модель-gpt-image-2). ## Асинхронный callback Поскольку время редактирования изображения может быть значительным, при длительном отсутствии ответа 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 webhook, например: ![](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 можно увидеть результат: ```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. При возникновении вопросов обращайтесь в нашу техническую поддержку.