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

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

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

• Задача: Направить международных клиентов на один шлюз изображений ToAPIs, а не открывать новое дальнее соединение к origin вендора на каждый запрос gpt-image-2.
• Контракт: Используйте ID модели gpt-image-2 в POST /v1/images/generations. В актуальной документации поля включают prompt (до 32 000 символов), size как соотношение сторон (например 1:1 или 16:9, а не строку пикселей 1024x1024) и resolution как уровень (1k, 2k или 4k).
• Регионы: Официальная документация ToAPIs предписывает пользователям в материковом Китае базовый URL https://toapis.cn. Международные примеры этой серии используют https://api.toapis.com. Пути, ID модели и заголовок Bearer не меняются — меняется только origin.
• Асинхронный протокол: Генерация изображения возвращает id задачи. Опрашивайте GET /v1/images/generations/{task_id} (или GET /v1/tasks/{task_id}) до completed или failed. Время на часах клиента — не то же самое, что время генерации, а таймаут клиента не доказывает провал задачи.
• Чего эта статья не утверждает: здесь нет непроверенного списка точек присутствия, времени рукопожатия или целевой сквозной задержки. Измеряйте их на своём пути. Детали параметров и сравнение SKU — в руководстве по API и руководстве по 2.6.

2. Маршрутизация международных команд через шлюз ToAPIs

Команды вдали от «домашнего» региона вендора обычно чувствуют две разные задержки: время на установку соединения и время, которое модель тратит на рендер. Сжимая их в одну фразу «API медленный», вы оптимизируете не то. Первое — сетевая задача, которую можно закрыть более близким задокументированным origin ToAPIs и повторным использованием тёплой HTTP-сессии. Второе — время генерации, которое наблюдается уже после приёма задачи.

ToAPIs предоставляет единый путь генерации изображений. Официальная документация сейчас указывает https://toapis.com и просит пользователей в материковом Китае заменить этот origin на https://toapis.cn. Статьи этой серии, включая руководство по GPT Image 2 API, отправляют те же пути на https://api.toapis.com. Выберите один базовый URL на среду, храните его в конфигурации и не смешивайте origin в одном сервисе.

Рис. 1: Держите клиенты на одном задокументированном origin ToAPIs, переиспользуйте сессию и рассматривайте генерацию изображения как асинхронную задачу, а не как долгий синхронный круговой рейс.

Практические привычки маршрутизации, которые не опираются на неопубликованные цифры задержки:

• Один origin на среду. Сервисы в Сингапуре и Франкфурте могут использовать один и тот же ID модели и тело запроса. Им не следует изобретать собственные URL вендора.
• Повторно используйте соединения. Включите HTTP keep-alive (и HTTP/2, если клиент его уже поддерживает), чтобы не повторять TLS на каждую отправку или опрос.
• Отделите отправку от ожидания. Сразу сохраняйте id задачи. Опрашивайте с ограниченным интервалом или предпочитайте webhook задачи, оставляя опрос запасным вариантом.
• Не считайте «одинаковые промпты из edge-кэша» способом сэкономить. У ToAPIs нет задокументированной гарантии, что повторный промпт отдаётся бесплатно из пограничного кэша. Если отправлены две задачи, планируйте оплату двух, если условия аккаунта не говорят иное.

Контракт запроса тоже легко устаревает. Старые фрагменты иногда передают size как 1024x1024 и флаг quality: "standard". Актуальный справочник gpt-image-2 и контракт фронтенда ToAPIs используют size для соотношения сторон (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) и resolution для уровня (1k, 2k, 4k). В текущем контракте Playground у точного gpt-image-2 нет поля quality; quality появляется у ID вроде gpt-image-2-vip. Подтвердите ID, который вы реально вызываете.

Референсные изображения передавайте в reference_images (только публичные URL, до 14 штук). image_urls — обратно совместимый псевдоним, который нормализуется в reference_images. Не отправляйте base64 — сначала загрузите файл. О произвольных пропорциях, дополнительных уровнях качества и поведении официальных SKU см. руководство по API и гайд модели.

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

Шаг 1: отправка через cURL

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": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

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

Имена полей и конверт ответа сверяйте со справочником API вашего аккаунта. Пример использует задокументированный путь статуса изображения и статусы completed / failed. Меняйте BASE на https://toapis.cn только в среде материкового Китая, которой нужен этот origin.

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 = "1:1",
    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 = 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__":
    task_id = dispatch_image(
        "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

Храните базовый URL, ID модели, size и resolution рядом с записью задачи. Если позже переведёте клиент с gpt-image-2 на gpt-image-2-vip или на SKU поколения 2.6, меняйте по одной переменной и перечитывайте соответствующее руководство — единицы биллинга сами собой не совпадут.

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

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

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

5. Цены и FinOps ROI

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

• Не переиспользуйте черновые или устаревшие единичные цены. Ставки каталога, множители разрешения и обращение с неудачными задачами зависят от SKU и аккаунта. Часть ID GPT Image 2.x тарифицируется за изображение; руководство по 2.6 описывает токенный биллинг для того поколения. Подтвердите ставку именно для того ID, который вызываете.
• Смена маршрута сама по себе не меняет цену модели. api.toapis.com или toapis.cn — это выбор базового URL, а не задокументированная скидка. Выигрыш FinOps даёт отказ от повторной отправки после таймаута клиента, черновики в 1k и правильный выбор SKU.
• Прямые контракты вендоров часто добавляют региональные ограничения расчётов, обязательства или пороги предоплаты. Биллинг ToAPIs обычно строится по факту использования — уточните действующие условия в аккаунте.
• Для более подробного обсуждения ставок можно опереться на статью о ценах GPT Image 2, но перед прогнозом сверьте каждое число с живым каталогом.

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

См. блок FAQ во frontmatter. Кратко: смена origin ToAPIs не меняет ID модели и задокументированную форму запроса; пользователи в материковом Китае должны следовать примечанию о toapis.cn в официальной документации; задания изображений асинхронны; size — соотношение сторон, resolution — уровень; бесплатный edge-кэш повторных промптов не задокументирован.

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

• Создайте ключ на портале разработчика ToAPIs.
• Задайте один базовый URL на среду (https://api.toapis.com или, где требуется, https://toapis.cn) и прогоните дымовой тест cURL с gpt-image-2, size: "1:1" и resolution: "1k".
• Сохраните id задачи, опрашивайте GET /v1/images/generations/{id} с ограниченным дедлайном и соблюдайте Retry-After при 429.
• Далее: параметры — в руководстве по GPT Image 2 API; смена SKU — в руководстве по 2.6; новый аккаунт — в обзоре бесплатных кредитов.