tutorial6 мин чтения

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

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

ToAPIs Engineering & Evaluation Team
TL;DR - Ключевые моменты
  • Точный gpt-image-2 открывает resolution как полноценный уровень: 1k, 2k и 4k. Нативный 4K получают, отправляя resolution: "4k" в POST /v1/images/generations — не серверным флагом upscale: true и не строкой size вида 1024x1024.
  • size — это соотношение сторон (1:1, 16:9 и другие документированные значения). Справка API публикует таблицу пикселей: 16:9 на уровне 4k даёт 3840x2160, а 1:1 на уровне 4k — 2880x2880.
  • Текущий Playground скрывает 5:4 и 4:5, когда resolution равен 4K, хотя таблица размеров API приводит пиксельные значения 4k и для этих двух соотношений. Если они нужны, подтвердите это живой справкой.
  • Задачи асинхронны: сохраняйте идентификатор задачи и опрашивайте GET /v1/images/generations/{id}. Таймаут клиента, особенно на 4k, не доказывает сбой задачи.
  • Не планируйте бюджет по старым ценам за 1024px / 2048px. Подтвердите действующую ставку по уровням для точного идентификатора модели в своём аккаунте.

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

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


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

  • Задача: получить изображение документированного уровня 4K с тем соотношением сторон, которое вам действительно нужно, одним запросом gpt-image-2.
  • Контракт: POST /v1/images/generations с идентификатором gpt-image-2. size — это соотношение сторон (1:1, 16:9 и другие документированные значения). resolution — это 1k, 2k или 4k. Официальная справка публикует итоговые пиксельные размеры для каждой пары.
  • Чего не следует отправлять: size: "2048x2048", флаг quality: "hd" на точном gpt-image-2 или выдуманное поле upscale: true, которое якобы превращает рендер 2048 px в 3840x2160. 4K — это полноценное значение resolution.
  • Асинхронный протокол: вызов отправки возвращает id задачи. Опрашивайте GET /v1/images/generations/{id} (или GET /v1/tasks/{id}), пока статус не станет completed или failed. Задачи 4K могут занимать больше времени, чем черновики 1K; таймаут клиента не доказывает сбой.
  • FinOps: делайте черновик на 1k, повышайте принятые промпты до 4k и подтверждайте действующую ставку по уровням. Не копируйте в прогноз старые строки цен для 1024 px / 2048 px.

2. Соотношения сторон, уровни разрешения и нативный вывод 4K

Текущий контракт gpt-image-2 разделяет форму и уровень. size выбирает соотношение сторон; resolution выбирает уровень качества; сервис выводит ширину и высоту в пикселях из обоих значений. Поэтому «изображение 4K» — не всегда 3840x2160: этот размер является документированным результатом size: "16:9" плюс resolution: "4k". Квадратный вывод 4K задокументирован как 2880x2880.

Предустановленные соотношения из официальной справки:

1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21

Можно передать auto и оставить выбор апстриму, но тогда итоговое соотношение и пиксельный размер не гарантированы. У точного gpt-image-2 не задокументировано поле пользовательского пиксельного размера. Пользовательские соотношения width:height (например, 7:4) описаны для gpt-image-2-vip и gpt-image-2-official и подчиняются их ограничениям (стороны кратны 16, длинная сторона не больше 3 840 px, соотношение не больше 3:1, общее число пикселей от 655 360 до 8 294 400).

Официальная таблица размеров для точного gpt-image-2:

size1k2k4k
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

Рядом с этой таблицей нужно держать две оговорки:

  • Текущий Playground ToAPIs сохраняет 3:2 и 2:3 на 4K, но убирает 5:4 и 4:5, когда разрешение равно 4K. Таблица выше по-прежнему приводит пиксели 4k для этих двух соотношений. Если продукту нужен 4k в 5:4 или 4:5, подтвердите это живым запросом и не принимайте ограничение Playground за предел API.
  • В разных интерфейсах встречаются строчные (4k) и прописные (4K) написания. Официальные примеры gpt-image-2 используют строчные буквы; конфигурация Playground — 1K / 2K / 4K. В клиентах следуйте справке API и не считайте регистр вторым параметром.

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

Рисунок 1: Разрешение — это полноценное поле запроса. Документированный путь — запросить 4k напрямую, а не изобретать флаг постпроцессингового апскейлера.

У ToAPIs нет документированного переключателя upscale: true, который берёт нативный рендер 2048 px и возвращает 3840x2160. Если у вас уже есть изображение 1K или 2K и нужно более крупное, поддерживаемый шаг — новая генерация (при желании с черновиком в reference_images) с resolution: "4k". Не обещайте сохранность типографики, «печатные мастер-файлы 300 DPI» или апскейл без артефактов, пока не измерите это на своих материалах.

Точный gpt-image-2 также принимает необязательный background: "transparent" и до 14 URL в reference_images. В текущем контракте Playground у него нет поля quality; quality есть у идентификаторов вроде gpt-image-2-vip.


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

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

Шаг 1: Отправка нативного 4K через cURL

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": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
    "size": "16:9",
    "resolution": "4k",
    "n": 1,
    "response_format": "url"
  }'

Этот запрос по документации нацелен на 3840x2160. Для квадратного мастера 4K смените size на 1:1 (документированный размер — 2880x2880). Для вертикального кадра 9:16 используйте size: "9:16" (документированный размер — 2160x3840).

Шаг 2: Черновик, затем повышение в Python

Итерируйте на 1k, сохраните принятый промпт (и необязательные опорные URL), затем отправьте заново на 4k. Вспомогательная функция опроса использует тот же асинхронный контракт, что и руководство по зеркалу и прокси.

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_image(
    prompt: str,
    size: str = "16:9",
    resolution: str = "1k",
    model: str = "gpt-image-2",
    reference_images: list[str] | None = None,
) -> str:
    payload = {
        "model": model,
        "prompt": prompt,
        "size": size,
        "resolution": resolution,
        "n": 1,
        "response_format": "url",
    }
    if reference_images:
        payload["reference_images"] = reference_images
    res = requests.post(ENDPOINT, headers=HEADERS, 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 = 300) -> 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__":
    prompt = (
        "Wide architectural photograph of a concrete pavilion at dusk, "
        "still water in the foreground, no typography, no logos"
    )
    draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
    print("Draft:", draft_id, poll_image_task(draft_id))
    final_id = dispatch_image(prompt, size="16:9", resolution="4k")
    print("4K:", final_id, poll_image_task(final_id, deadline_s=300))

Для опросов 4K задайте более длинный дедлайн, чем для черновиков 1K. Сразу сохраняйте id задачи, чтобы таймаут клиента всё ещё можно было разрешить поздней проверкой статуса. Если позже переведёте клиент на gpt-image-2-vip (пользовательские соотношения, quality) или gpt-image-2-official, меняйте по одной переменной и заново читайте справку этого ID: единицы тарификации сами по себе не совпадают.


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

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

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

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 за 1024 px или $0.072 за 2048 px. Эти строки относятся к устаревшему контракту размеров.
  • Гид по модели GPT Image 2 сейчас показывает сравнительные цены ToAPIs на лендинге: $0.015 / $0.020 / $0.025 за изображение на 1K / 2K / 4K для стандартного gpt-image-2. Используйте это только как опубликованное сравнение. Подтвердите ставку, которая действует для вашего аккаунта и точного идентификатора модели.
  • Дешёвый цикл — черновик на 1k, затем повышение принятого промпта (и опор) до 4k. Две успешные задачи — это два оплачиваемых изображения, если только условия аккаунта не говорят иное. Документированного бесплатного «апскейла того же промпта» нет.
  • Токенные цены официального вендора и цены ToAPIs за запрос не взаимозаменяемы. Если переходите на gpt-image-2-vip или официальный канальный SKU, заново прочитайте прайс этого ID.
  • Для контекста см. статью о ценах GPT Image 2, затем сверьте каждое число с живым каталогом, прежде чем включать его в прогноз.

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

См. блок FAQ во frontmatter. Кратко: 4K — это полноценное значение resolution, а не флаг upscale; пиксельные размеры зависят и от size, и от resolution; не передавайте 1024x1024 как size; если нужны 5:4 / 4:5 на 4k, подтвердите это живым API; опубликованные ставки 1K / 2K / 4K нужно сверять в аккаунте.


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

  • Создайте ключ на портале разработчика ToAPIs.
  • Задайте один базовый URL на среду (https://api.toapis.com или, где требуется, https://toapis.cn) и проверьте дымовым тестом фрагмент cURL с size: "16:9" и resolution: "1k".
  • Повысьте тот же промпт до resolution: "4k" и подтвердите документированный пиксельный размер для этого соотношения (для 16:9 это 3840x2160).
  • Сохраните id задачи, дайте опросам 4K более длинный дедлайн и соблюдайте Retry-After при 429.
  • Дальше: руководство по инпеинтингу и аутпеинтингу, если редактируете готовый кадр, и руководство по API для полной карты параметров.

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

OpenAIIMAGE

GPT-Image-2

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

GPT-Image-2 VIP

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

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

tutorial6 мин чтения

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

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

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