> ## 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. **Все размеры (1K / 2K / 4K / пользовательские) тарифицируются одинаково за каждое изображение, независимо от исходного разрешения и запрошенного `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=1` или `n=10`) возвращается только одно изображение и тарифицируется как одно. Если нужно получить несколько вариантов, необходимо самостоятельно параллельно отправлять несколько запросов. Это ограничение также распространяется на `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 интегрирован через адаптер OpenAI протокола и поддерживает только параметры: `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)). ## Основное использование Далее приведён пример вызова через 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` с токеном из `authorization`. В 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 может быть достаточно долгим, при отсутствии ответа 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.acedata.cloud/cjjfly.png) Скопируйте этот URL, например `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, и используйте его как `callback_url`. Далее отправим запрос с указанием `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. Если у вас возникнут вопросы, обращайтесь в нашу техническую поддержку.