tutorial6 мин чтения

Локальное редактирование и расширение холста в GPT Image 2 Image Edits API

Редактируйте готовые изображения по текущему контракту GPT Image 2: правки по промпту и reference_images на gpt-image-2 и точный инпеинтинг по маске на gpt-image-2-official — оба через асинхронный endpoint generations.

ToAPIs Engineering & Evaluation Team
TL;DR - Ключевые моменты
  • Текущий контракт ToAPIs для изображений — это асинхронный POST /v1/images/generations, а не синхронный multipart /v1/images/edits и не идентификатор каталога gpt-image-2-edit.
  • Точный gpt-image-2 поддерживает правки по промпту через reference_images (только публичные URL, до 14 штук). Пиксельно точный инпеинтинг с альфа-маской задокументирован для gpt-image-2-official через mask_url и image_urls.
  • size — это соотношение сторон, например 1:1 или 16:9; resolution — это уровень 1k, 2k или 4k. Не передавайте в size пиксельную строку вроде 1024x1024.
  • Отдельного флага outpaint в документации нет. Чтобы расширить холст, смените size на целевое соотношение, передайте оригинал как опорное изображение и опишите расширение в промпте.
  • Сохраняйте идентификатор задачи и опрашивайте GET /v1/images/generations/{id}. Таймаут клиента не доказывает, что задача завершилась ошибкой.

Локальное редактирование и расширение холста в GPT Image 2 Image Edits API

Целевые модели: gpt-image-2, gpt-image-2-official
Эндпоинт инференса: https://api.toapis.com/v1/images/generations
Связанные материалы: руководство по GPT Image 2 API · рабочие процессы 4K и соотношений сторон · глобальное зеркало и прокси · официальная справка по инпеинтингу


1. Краткое содержание и обзор (TL;DR)

  • Задача: заменить область готового изображения (инпеинтинг) или расширить холст до нового соотношения сторон (аутпеинтинг), не изобретая второй недокументированный API.
  • Контракт: используйте идентификаторы, которые есть в каталоге. Точный gpt-image-2 принимает prompt, size как соотношение, resolution как 1k / 2k / 4k и необязательный reference_images. Инпеинтинг по маске задокументирован для gpt-image-2-official с image_urls и mask_url.
  • Это не текущий контракт: идентификатор gpt-image-2-edit, синхронный multipart POST /v1/images/edits или size: "1024x1024". Такие формы встречаются в старых черновиках и не должны попадать в новые клиенты.
  • Ввод и вывод: загрузите исходные изображения и маски через POST /v1/uploads/images, затем передайте возвращённый публичный URL. Base64 не принимается в reference_images, image_urls и mask_url.
  • Асинхронный протокол: вызов отправки возвращает id задачи. Опрашивайте GET /v1/images/generations/{id}, пока статус не станет completed или failed. Таймаут клиента не доказывает сбой задачи.

2. Практическая ценность программного редактирования изображений

Сгенерировать кадр по текстовому промпту — только первый шаг. В продакшен-каталогах, рекламе и дизайн-системах чаще нужны точечные правки: заменить товар, очистить фон или растянуть квадратный packshot в широкий герой, сохранив свет и идентичность объекта.

Текущее семейство GPT Image 2 в ToAPIs закрывает эти задачи одним путём, POST /v1/images/generations, и двумя разными идентификаторами модели:

ЗадачаИдентификатор моделиКак указать исходникМаска?
Правка по промпту или перенос стиляgpt-image-2reference_images (список URL, максимум 14)Для этого ID не задокументирована
Пиксельно точный инпеинтингgpt-image-2-officialimage_urls (список URL, максимум 16)mask_url нужен вместе с первым изображением
Расширение холста (аутпеинтинг)Любой из двух IDПередайте оригинал как опору и смените size на целевое соотношениеОтдельного флага outpaint нет

На точном gpt-image-2 поле image_urls — обратно совместимый псевдоним reference_images, который нормализует шлюз. Примеры официального канала в справке используют image_urls вместе с mask_url. Берите имена полей из справки того ID, который вызываете.

Рабочая маска для инпеинтинга — это PNG с альфа-каналом. Её пиксельные размеры должны совпадать с первым опорным изображением. Прозрачные пиксели (alpha = 0) — зона перерисовки; непрозрачные должны сохраниться. Соберите маску в конвейере (например, через Pillow), загрузите её и отправьте только URL.

Аутпеинтинг — это рабочий процесс, а не отдельный endpoint. Если есть packshot 1:1 и нужен баннер 16:9, оставьте оригинал как опору, задайте size равным 16:9, явно укажите уровень resolution и попросите модель сохранить объект и расширить сцену. Практичный вариант — скомпоновать оригинал на больший прозрачный холст, загрузить этот холст и использовать его как опору. Путь по-прежнему /v1/images/generations, без флага outpaint: true.

Рама с островом маски проходит через шестиугольный шлюз на расширенный холст

Рисунок 1: Исходный холст и внутренняя область маски проходят через шлюз ToAPIs; документированный путь по-прежнему POST /v1/images/generations, а mask_url зарезервирован для gpt-image-2-official.

Поля size и resolution следуют тому же контракту, что и текстовая генерация: size — это соотношение вроде 1:1 или 16:9, а resolution — 1k, 2k или 4k. Точный gpt-image-2 в текущем контракте Playground не открывает поле quality; quality (low / medium / high) есть у gpt-image-2-official. Таблицу пикселей см. в руководстве по 4K.


3. Продакшен-реализация: cURL и Python

Международные примеры этой серии используют https://api.toapis.com. Официальная документация указывает пользователям материкового Китая использовать https://toapis.cn. Оставляйте один origin на среду. Пути, идентификаторы моделей и заголовок Bearer остаются теми же.

Шаг 1: Загрузите исходное изображение (и маску, если она нужна)

bash
curl -X POST "https://api.toapis.com/v1/uploads/images" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -F "file=@./product.png"

В ответе есть data.url. Повторите вызов для PNG-маски, если вызываете gpt-image-2-official. Не встраивайте base64 в запрос генерации.

Шаг 2: Правка по промпту на точном gpt-image-2

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url",
    "reference_images": ["https://example.com/product.png"]
  }'

Шаг 3: Инпеинтинг по маске на gpt-image-2-official

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-official",
    "prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'

Шаг 4: Отправка и опрос на Python

Сопоставляйте имена полей со справкой API для того идентификатора, который вызываете. Фрагмент использует документированный путь статуса изображения и статусы completed / failed.

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def upload_image(path: str) -> str:
    with open(path, "rb") as handle:
        res = requests.post(
            f"{BASE}/v1/uploads/images",
            headers=HEADERS,
            files={"file": handle},
            timeout=60,
        )
    res.raise_for_status()
    url = res.json().get("data", {}).get("url")
    if not url:
        raise RuntimeError(f"Unexpected upload envelope: {res.text}")
    return url


def dispatch_edit(payload: dict) -> str:
    res = requests.post(
        f"{BASE}/v1/images/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json=payload,
        timeout=30,
    )
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(
        f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
    )


if __name__ == "__main__":
    source = upload_image("product.png")
    # Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
    task_id = dispatch_edit(
        {
            "model": "gpt-image-2",
            "prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
            "size": "16:9",
            "resolution": "1k",
            "n": 1,
            "response_format": "url",
            "reference_images": [source],
        }
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

Чтобы вместо этого выполнить инпеинтинг по маске, загрузите RGBA-маску того же размера, что и первое изображение, смените model на gpt-image-2-official и отправьте image_urls вместе с mask_url. Сохраняйте идентификатор модели, size и resolution рядом с записью задачи, чтобы смена SKU позже была явным решением.


4. Обработка ошибок и матрица статусов

Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Даже при успешном HTTP-ответе нужно читать status задачи.

HTTP-статусТипичная категорияРекомендуемое действие
400Неверное поле или неподдерживаемая комбинацияПроверьте идентификатор модели, что size — документированное соотношение, что resolution равен 1k / 2k / 4k, что URL публичны, и что маска (если используется) — PNG того же размера с альфа-каналом на gpt-image-2-official
401Отсутствующий или недействительный API-ключСмените ключ в панели ToAPIs и проверьте заголовок Authorization
429Ограничение частоты или параллелизмаСоблюдайте Retry-After, если оно есть; делайте откат с джиттером; повторяйте запрос только когда это безопасно
5xx или сетевой таймаутВременная проблема шлюза или апстримаПеред повторной отправкой проверьте статус задачи; используйте политику повторов с верхним пределом

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. Цены и FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • Не используйте черновые единичные цены, например фиксированную пару $0.024 / $0.048 («standard против HD»). Эти цифры устарели относительно текущего каталога, который тарифицирует по идентификатору модели, а для стандартного сравнения GPT Image 2 на лендинге — ещё и по уровню разрешения.
  • Гид по модели GPT Image 2 сейчас показывает сравнительные цены ToAPIs на лендинге: $0.015 / $0.020 / $0.025 за изображение на 1K / 2K / 4K для стандартного gpt-image-2. Считайте это опубликованным сравнением, а не счётом. Официальные канальные SKU и скидки аккаунта могут отличаться; подтвердите ставку для того ID, который вызываете.
  • Выбор маршрута (api.toapis.com или toapis.cn) — это выбор базового URL, а не документированная скидка. Выигрыш FinOps даёт черновик на 1k, отказ от повторной отправки после таймаута клиента и правильный выбор SKU (gpt-image-2 против gpt-image-2-official), а не выдуманная более дешёвая «модель редактирования».
  • Для контекста см. статью о ценах GPT Image 2, затем сверьте каждое число с живым каталогом, прежде чем включать его в прогноз.

6. Часто задаваемые вопросы

См. блок FAQ во frontmatter. Кратко: у точного gpt-image-2 не задокументированы mask_url и /v1/images/edits; инпеинтинг по маске описан для gpt-image-2-official; маски должны быть RGBA PNG того же размера и передаваться как URL; аутпеинтинг — это смена size плюс опорное изображение; тариф нужно подтверждать в аккаунте для точного идентификатора модели.


7. Чек-лист действий

  • Создайте ключ на портале разработчика ToAPIs.
  • Задайте один базовый URL на среду (https://api.toapis.com или, где требуется, https://toapis.cn) и загрузите исходное изображение через POST /v1/uploads/images.
  • Проверьте дымовым тестом правку по промпту на gpt-image-2 с reference_images, size: "1:1" и resolution: "1k".
  • Если нужна пиксельно точная маска, переключитесь на gpt-image-2-official, загрузите RGBA-маску того же размера, что и первое изображение, и отправьте image_urls плюс mask_url.
  • Сохраните id задачи, опрашивайте GET /v1/images/generations/{id} с ограниченным дедлайном и соблюдайте Retry-After при 429.
  • Дальше: руководство по соотношениям сторон и 4K, если повышаете resolution, и руководство по API для полной карты параметров.

Модели и API, упомянутые в статье

OpenAIIMAGE

GPT-Image-2

Текущий тариф:3 credits /request
OpenAIIMAGE

gpt-image-2-official

Текущий тариф:Input 800 credits/1M, Output 4,800 credits/1M

Похожие статьи

tutorial6 мин чтения

Нативная генерация 4K в GPT Image 2: соотношения сторон и процессы масштабирования

Создавайте нативный 4K по текущему контракту GPT Image 2: задайте size как соотношение сторон и resolution как 4k. Документированного флага upscale: true нет, а пиксельный размер 4K зависит от выбранного соотношения.

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2
tutorial5 мин чтения

Глобальное зеркало и прокси GPT Image 2: низкая задержка для международных команд

Как международные команды вызывают GPT Image 2 API через задокументированный origin ToAPIs: повторное использование сессий и опрос асинхронных задач без опоры на непроверенные цифры задержки.

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2