GPT Image 2.5 API: генерация и редактирование изображений на Python

Отправьте POST на https://api.omniakey.com/v1/media/tasks с model gpt-image-2.5-flare, опрашивайте вернувшийся id задачи и скачайте assets[0].url, когда статус станет succeeded. 29 октября 2026 года мы сгенерировали изображения в 1K, 2K и 1536x1024 и отредактировали фотографию кафе, затем открыли каждый файл и прочитали реальный размер в пикселях: 1024×1024, 2048×2048, 1536×1024 и 1024×682. Генерация в 1K заняла 29,5 с, в 2K — 45,2 с.

Какой id модели 2.5 использовать

Используйте gpt-image-2.5-flare. Именно этот id мы вызывали во всех запусках ниже. Страница модели GPT-Image 2.5 Flare (проверена 29 октября 2026 года) указывает OpenAI как провайдера, перечисляет текст в изображение и редактирование изображения и содержит примечание "Guide updated 2026-10-27". На той же странице есть второй id 2.5 — gpt-image-2.5-sunburst.

Flare справляется с обеими задачами. Генерация отправляет промпт; редактирование отправляет промпт и одно исходное изображение. Качество принимает low, medium или high, и на той же странице сказано, что уровень не меняет цену. Во всех запусках здесь использовался medium. Мы не запускали sunburst, качество low и high, 4K и 3840x2160, маски и несколько референсных изображений, поэтому планируйте на Flare с medium и одним исходным изображением, пока не проверите остальное сами.

Код запроса

Скрипт ниже — тот самый, что мы запускали, без изменений: два помощника, затем один вызов генерации и один вызов редактирования. Он использует только стандартную библиотеку Python, читает ключ из OMNIAKEY_API_KEY и записывает каждый PNG в папку, из которой вы его запускаете. Оба помощника возвращают id задачи, поэтому его можно сохранить и опросить позже.

import base64
import json
import os
import time
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "gpt-image-2.5-flare"

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    for _ in range(150):
        time.sleep(4)
        state = request("GET", f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signed link: valid for about an hour, so download now
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=120) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

def generate_image(prompt, out_path, size="1K", quality="medium"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1K", quality="medium"):
    with open(source_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "edit",
        "input": {"prompt": prompt, "image": {"data": image, "mime_type": "image/jpeg"}},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A small glass greenhouse on a hillside at sunrise, morning fog in the valley, "
        "soft watercolor style, a wooden bench outside the door, no people, no text.",
        "greenhouse.png",
    )
    print("generate task", task)
    task = edit_image(
        "cafe-base.jpg",
        "Change the red bicycle to matte black. Keep everything else exactly the same: "
        "the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos.",
        "cafe-edited.png",
    )
    print("edit task", task)

Authorization: Bearer <key> передаётся в каждом вызове, а вызову создания ещё нужен Idempotency-Key, который скрипт заполняет новым UUID. В теле type равен "image", operation — "generate" или "edit", слова лежат в input.prompt, а размер и качество — в parameters. API также принимает n, и допустимо только 1, поэтому скрипт его не передаёт. Создание возвращает HTTP 202 с id задачи, статус начинается с queued, и цикл ждёт 4 с между проверками, пока статус не выйдет из двух рабочих состояний.

Редактирование добавляет JPEG в input.image как встроенный объект Base64 с типом mime. Тела запросов вместе с Base64 ограничены 1 MiB, поэтому скрипт отправляет JPEG на 1024 пикселя размером около 230 КБ.

Размеры, которые мы запускали, и что вернулось

Четыре запуска, все с качеством medium, 29 октября 2026 года. Три вернулись в запрошенном размере. Редактирование в 1K — нет, в одном из двух запусков.

• 1K, генерация — Размер в пикселях, прочитанный из файла: 1024×1024; Дата: 29 октября 2026
• 2K, генерация — Размер в пикселях, прочитанный из файла: 2048×2048; Дата: 29 октября 2026
• 1536x1024, генерация — Размер в пикселях, прочитанный из файла: 1536×1024; Дата: 29 октября 2026
• 1K, редактирование — Размер в пикселях, прочитанный из файла: 1024×682; Дата: 29 октября 2026

Теплица ниже — генерация в 1K с тем же телом запроса, что и в коде выше.

Из списка следуют две вещи. Во-первых, читайте размер в скачанном файле. Редактирование в 1K просило квадрат, а вернулось с 1024×682 — в форме отправленного JPEG 1024×683, и ещё один запуск того же редактирования в 1K дал 1024×1024. Во-вторых, список размеров в документации по API изображений (проверена 29 октября 2026 года) предлагает auto, 1K, 2K, 4K и 3840x2160 для этой модели и говорит, что размеры вне списка отклоняются до списания; наш вызов 1536x1024 29 октября 2026 года не был отклонён и вернул 1536×1024. Проверьте реальный файл, прежде чем строить макет под один размер.

Редактирование сохраняет сцену и меняет одну вещь

Редактирование отвечает на два вопроса: что меняется и что остаётся. Мы попросили об одном изменении и назвали то, что должно сохраниться.

Prompt: "Change the red bicycle to matte black. Keep everything else exactly the same: the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos."

Велосипед вернулся тёмным, а стол, чашка, растение и оконная рама остались в кадре. Исходник был JPEG 1024×683, результат измерен как 1024×682, запуск занял 38,0 с. Каждый раз пишите список того, что должно остаться: об общей структуре промптов читайте в нашем руководстве по промптам GPT Image 2.

Ошибки и ограничения

Два заголовка делают работу до появления пикселей: bearer-токен и уникальный Idempotency-Key. Если они верны, остальную часть вызова легко повторить.

Ключ может быть длиной до 255 символов, согласно документации, проверенной 29 октября 2026 года. Повтор с тем же телом — безопасная повторная попытка: вы получаете существующую задачу, и ничего нового не списывается. Держите тело меньше 1 MiB вместе с Base64, поэтому уменьшите или сожмите исходник перед отправкой.

Когда задача успешна, assets[0].url — подписанная ссылка, которая живёт около часа, согласно документации, поэтому скачивайте сразу или опросите ту же задачу снова ради новой ссылки. Записи задач хранятся 24 часа.

Один заголовок удивил нас 29 октября 2026 года: POST, отправленный с User-Agent по умолчанию из urllib Python, вернул HTTP 403 с телом "error code: 1010" от Cloudflare. Тот же POST с нашим собственным заголовком User-Agent: omniakey-example/1 дошёл до API, и API ответил 400 invalid_request на пустое тело, которое мы отправили, и ничего не было списано. В документации названы только Authorization и Idempotency-Key, поэтому задайте User-Agent в своём клиенте.

GPT Image 2.5 или GPT Image 2 для работы с API?

Flare — это id 2.5, который мы тестировали. GPT Image 2 на своей странице модели GPT Image 2 использует id gpt-image-2. Если скрипт уже даёт нужный результат на этом id, менять его незачем.

Для фотографии, где сцена должна сохраниться, а один объект измениться, Flare с medium — это то, что покрывают наши запуски 29 октября 2026 года: три сгенерированных размера и редактирование в 1024×682. В сравнении GPT Image 2.5 и GPT Image 2 есть размеры и результаты одного промпта для обеих моделей, чтобы выбирать с цифрами перед глазами. Актуальные тарифы — на странице цен.

Частые вопросы

Какой id модели выбрать: gpt-image-2.5-flare или gpt-image-2.5-sunburst?

Во всех запусках выше мы использовали Flare, и его редактирование сохранило сцену, которую мы просили сохранить. На странице модели Sunburst указан как второй id 2.5: начните с Flare и проверьте Sunburst на своём самом сложном редактировании, прежде чем переключаться.

Можно ли запросить горизонтальный размер, например 1536x1024?

29 октября 2026 года генерация 1536x1024 вернулась с 1536×1024. В списке размеров документации по API изображений этого значения для данной модели нет, поэтому прочитайте файл и сверьтесь с документацией, прежде чем полагаться на него в продакшене.

Почему моё редактирование вернулось в другом размере?

Одно и то же редактирование в 1K вернулось с 1024×682 в одном запуске и с 1024×1024 в другом, поэтому считайте запрошенный размер просьбой, а не обещанием. Откройте PNG и прочитайте ширину и высоту, прежде чем размещать его.

Нужен ли заголовок User-Agent?

29 октября 2026 года запрос с User-Agent по умолчанию из Python получил HTTP 403 с ошибкой Cloudflare 1010. Тот же запрос с нашим собственным заголовком User-Agent дошёл до API, поэтому отправляйте его.

Сколько живут ссылки на изображения?

Документация говорит, что подписанная ссылка живёт около часа. Опросите задачу снова ради новой ссылки и скачайте файл сразу, как только задача завершится.