Локальное редактирование и расширение холста в 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, синхронный multipartPOST /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-2 | reference_images (список URL, максимум 14) | Для этого ID не задокументирована |
| Пиксельно точный инпеинтинг | gpt-image-2-official | image_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: Загрузите исходное изображение (и маску, если она нужна)
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
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
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.
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 или сетевой таймаут | Временная проблема шлюза или апстрима | Перед повторной отправкой проверьте статус задачи; используйте политику повторов с верхним пределом |
5. Цены и FinOps ROI
- Не используйте черновые единичные цены, например фиксированную пару
$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 для полной карты параметров.







