> ## 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 Edits API Заявка и использование > OpenAI generation API guide - Ace Data Cloud OpenAI сервис редактирования изображений позволяет передавать любое количество изображений и команд, выводя измененные изображения. В настоящее время интерфейс поддерживает `dall-e-2`, `gpt-image-1`, новейшую **`gpt-image-2`**, а также модели из серии **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`**, подключаемые через тот же интерфейс. В этом документе в основном описывается процесс использования OpenAI Images Edits API, с помощью которого мы можем легко использовать официальные функции редактирования изображений OpenAI. ## Процесс заявки Чтобы использовать OpenAI Images Edits 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 Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## Модель GPT-Image-2 `gpt-image-2` в сценариях редактирования изображений имеет очень заметные улучшения по сравнению с `gpt-image-1`: * **Структура остается более стабильной**: при смене кожи, цветовой гаммы или фона почти не нарушается оригинальная компоновка и композиция изображения. * **Текст сохраняется более точно**: изображения с текстом, такие как инфографика, постеры, меню и т.д., остаются четкими и читаемыми после редактирования. * **Поддержка прямой передачи URL**: помимо традиционной загрузки файлов `multipart/form-data`, `gpt-image-2` также **дополнительно поддерживает передачу URL изображений в формате JSON**, что позволяет не загружать изображения на локальный компьютер, что идеально подходит для интеграции на сервере. * **Поддержка прямой передачи base64**: как и в официальной версии, поле `image` также может принимать base64 (например, `data:image/png;base64,...` или чистый base64), что позволяет редактировать локальные изображения без предварительной загрузки на хостинг. * **Поддержка высококачественной перерисовки**: можно передать оригинальное изображение 1K и запросить вывод 2K / 4K с помощью параметра `size`, модель будет одновременно увеличивать изображение в процессе редактирования. ### Официальный маршрут / Обратный вариант (`: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` Ограничения интерфейса редактирования по `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`, один запрос всегда вернет 1 изображение и будет взиматься плата только за 1 изображение. Если вам нужно получить несколько вариантов редактирования, пожалуйста, **инициируйте несколько запросов параллельно**. Это ограничение также применимо к `gpt-image-1` / `gpt-image-1.5`, а также к сериям `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`. `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": "Преобразуйте эту инфографику в темный режим: темно-синий фон, светлый кремовый текст, глубокие серые закругленные карточки модулей с мягкими тенями. Сохраните всю компоновку, структуру и расположение модулей идентичными — только инвертируйте цветовую схему.", "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": "Преобразуйте эту инфографику в темный режим: темно-синий фон, светлый кремовый текст, глубокие серые закругленные карточки модулей с мягкими тенями. Сохраните всю компоновку, структуру и расположение модулей идентичными — только инвертируйте цветовую схему.", "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": "Преобразуйте эту инфографику в темный режим: темно-синий фон, светлый кремовый текст, глубокие серые закругленные карточки модулей с мягкими тенями. Сохраните всю компоновку, структуру и расположение модулей идентичными — только инвертируйте цветовую схему.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Отредактированное изображение выглядит следующим образом:

Можно увидеть, что структура модулей, информационные разделы и типографика были строго сохранены, только цветовая схема была инвертирована в темный режим. > **Подсказка**: поле `image` также поддерживает передачу массива, например, `"image": ["url1", "url2", "url3"]`, максимум можно передать 16 изображений для одновременного редактирования. > **Прямой ввод base64**: `image` (и каждый элемент массива) может быть не только URL, но и base64 — `data:image/png;base64,...` или чистый base64, что подходит для локальных изображений, которые не нужно загружать на хостинг. Например: > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "Преобразуйте эту инфографику в темный режим.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### Способ вызова два: 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": "Объедините все вышеуказанные предметы в одну корзину подарков 'Расслабьтесь и отдохните' на чистом белом фоне, фотореалистично, с мягким естественным освещением.", "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": "Замените деревянную полку на стильную современную белую плавающую полку, установленную на пастельной синей стене. Сохраните точное расположение книг (1 книга сверху, 3 в середине, 7 внизу). Добавьте маленький горшок с суккулентом на верхней полке рядом с книгой. Яркий воздушный дневной свет слева.", "size": "1024x1024" } ``` Результат редактирования (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Можно увидеть, что стиль и окружение были полностью заменены в соответствии с подсказкой, но количество книг на каждом уровне (1 / 3 / 7) по-прежнему строго сохранено, и по требованию добавлен горшок с суккулентом. ### Способ вызова три: 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="Преобразуйте это изображение в темный режим, сохраняя компоновку." ) 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-lite` | 0.14 | Легкая модель изображений Gemini 3.1, поддерживает только 1K, редактирование с низкой задержкой | | `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.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=добавить зеленый лист на верх яблока" \ -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": "добавить зеленый лист на верх яблока" } ] } ``` Отредактированное изображение:

### Вызов через форму + локальный файл ```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": "добавить зеленый лист на верх яблока" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### Асинхронный обратный вызов Механизм асинхронного обратного вызова `callback_url` также работает для nano-banana, процесс вызова полностью аналогичен другим моделям, подробности см. в разделе [Асинхронный обратный вызов](#асинхронный-обратный-вызов). ## Основное использование Теперь можно использовать код для вызова, ниже приведен пример вызова через 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=Создайте красивую корзину с подарками с этими предметами внутри' ``` При первом использовании этого интерфейса необходимо заполнить как минимум четыре поля: одно из них `authorization`, которое можно выбрать из выпадающего списка. Другой параметр — это `model`, `model` — это категория модели OpenAI, которую мы выбираем, здесь у нас в основном 1 модель, подробности можно посмотреть в предоставленных моделях. Еще один параметр — это `prompt`, `prompt` — это текст, который мы вводим для генерации изображения. Последний параметр — это `image`, этот параметр требует путь к изображению, которое нужно отредактировать, изображение показано ниже:

Пример кода на Python с аналогичным эффектом вызова: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Сгенерируйте фотореалистичное изображение корзины с подарками на белом фоне с надписью 'Relax & Unwind' с лентой и шрифтом, похожим на рукописный, содержит все предметы из эталонных изображений. """ 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). ## Асинхронный обратный вызов Поскольку время редактирования изображений API OpenAI Images Edits может быть относительно долгим, если API долго не отвечает, HTTP-запрос будет поддерживать соединение, что приведет к дополнительному потреблению системных ресурсов, поэтому этот API также предоставляет поддержку асинхронного обратного вызова. Общий процесс: когда клиент инициирует запрос, дополнительно указывается поле `callback_url`, после того как клиент инициирует API-запрос, API немедленно возвращает результат, содержащий информацию о поле `task_id`, представляющем текущий идентификатор задачи. Когда задача завершена, результат редактирования изображения будет отправлен на указанный клиентом `callback_url` в формате POST JSON, который также включает поле `task_id`, таким образом, результат задачи можно связать по ID. Ниже мы рассмотрим пример, чтобы понять, как это работает. Во-первых, обратный вызов Webhook — это служба, которая может принимать HTTP-запросы, разработчики должны заменить ее на URL своего собственного HTTP-сервера. Для удобства демонстрации используется публичный сайт примера Webhook [https://webhook.site/](https://webhook.site/), открыв этот сайт, вы получите URL Webhook, как показано на изображении: ![](https://cdn.acedata.cloud/cjjfly.png) Скопируйте этот URL, чтобы использовать его в качестве Webhook, пример здесь: `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Далее мы можем установить поле `callback_url` на указанный Webhook 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=Создайте красивую подарочную корзину с этими предметами" \ -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, если возникнет ошибка, 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": "не удалось получить" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Заключение С помощью этого документа вы узнали, как легко использовать API редактирования изображений OpenAI для использования официальной функции редактирования изображений OpenAI. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.