Ограничения скорости API генерации изображений: чего ожидать и как HiAPI справляется со всплесками трафика

Что на самом деле означает «ограничение скорости» в API изображений

Когда запрос на генерацию изображения завершается ошибкой HTTP 429, или ваш пакетный процесс каждый раз застревает на одном и том же количестве параллельных задач, вы сталкиваетесь с ограничением скорости, а не с ошибкой. Все производственные API изображений ограничивают трафик как минимум по одному из трёх измерений, и понимание этих различий критично для отладки:

• RPM (запросов в минуту) — количество вызовов POST, которые можно выполнить в скользящем 60-секундном окне. Дружелюбно к всплескам, быстро восстанавливается.
• RPD (запросов в день) — суточный лимит, обычно привязанный к вашему тарифному уровню. Сбрасывается в полночь по UTC (или в расчётный день вашего аккаунта).
• Параллелизм / число активных задач — количество задач изображений, которые могут выполняться одновременно. Даже если RPM в норме, 5-я активная задача будет поставлена в очередь или отклонена.

Применительно к генерации изображений узким местом почти всегда является параллелизм, а не RPM — одна задача 1024×1024 может занимать от 8 до 30 секунд от начала до конца, поэтому 10 параллельных задач ≠ 10 RPM. Смешение этих двух понятий — самая частая причина ситуации «мои повторы только ухудшают дело».

Частые причины в порядке вероятности

1. Ваш параллелизм превышает лимит параллельных задач. Наиболее вероятная причина. Ваш цикл разом отправляет 50 вызовов POST /v1/tasks, провайдер принимает первые N, остальные возвращают 429. Лимиты параллелизма большинства провайдеров не документированы отдельно по ключам — они выводятся из вашего тарифного уровня.
2. Шторм повторов после мгновенных ошибок. Одна задача возвращает 5xx, что немедленно запускает повтор, все остальные активные задачи делают то же самое, и ваш эффективный параллелизм удваивается за секунду.
3. Лимит RPM по модели, о котором вы не знаете. Универсальный ключ высокого уровня может по-прежнему подчиняться ограничениям на уровне модели, особенно для новых или продвинутых моделей. Вызов gpt-image-2 и flux-1-pro одним и тем же ключом не означает, что они делят одну квоту.
4. Дневная квота исчерпывается к полудню. Менее распространено, но наиболее сбивает с толку — ваши запросы работают нормально, а затем каждый день в одно и то же время начинают падать. Это всегда RPD.
5. Шумные соседи по общему субаккаунту. Если вы настраиваете ключи по средам, но они используют один расчётный аккаунт, предпродажный трафик съедает производственную квоту.

Шаги исправления

Выполняйте шаги по порядку. Каждый изолирует отдельное измерение.

1. Читайте тело ответа об ошибке, а не только код состояния. Настоящий 429 от HiAPI выглядит так:

   {
     "error": {
       "code": "rate_limit_exceeded",
       "type": "hiapi_error",
       "request_id": "req_01HXXXXXXXXXXXXXXX"
     }
   }
   

   Запишите request_id. Это единственная информация, которая позволит команде поддержки точно отследить, какое ограничение вы нарушили.

2. Различайте 429 и 401. 401 с {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} — это не ограничение скорости, а ошибка аутентификации или прав доступа. Не добавляйте задержки для 401; сколько бы вы ни ждали, он не превратится в 200.

3. Сначала ограничьте клиентский параллелизм, потом количество повторов. Достаточно простого семафора:

   import asyncio, httpx
   sem = asyncio.Semaphore(4)  # сопоставьте это значение с лимитом параллелизма провайдера
   
   async def submit(client, payload):
       async with sem:
           return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)
   

   Начните с 4. Повышайте только после того, как весь пакет задач выполнится без единого 429.

4. Используйте экспоненциальную задержку с полным джиттером только при 429.

   import asyncio, random
   async def backoff(attempt):
       # 1s, 2s, 4s, 8s, максимум 30s, рандомизация для предотвращения эффекта громового стада
       delay = min(30, 2 ** attempt) * random.random()
       await asyncio.sleep(delay)
   

   Ограничьте количество повторов до 5. После этого сообщайте об ошибке — не повторяйте бесконечно.

5. Соблюдайте Retry-After, если он присутствует. Если ответ содержит заголовок Retry-After, провайдер явно сообщает вам, когда сбросится окно. Этот повтор должен использовать его, а не вычисленную вами задержку.

6. Разделяйте ключи по средам. Если предпродажная и производственная среды используют один ключ, их лимиты параллелизма тоже общие. Отдельный ключ на каждую среду плюс отдельный ключ на каждый пул рабочих процессов с высоким трафиком — самый дешёвый способ решить проблему «лимит кажется ниже, чем указано в документации».

Как HiAPI справляется со всплесками трафика

HiAPI предоставляет конечную точку POST /v1/tasks, которая принимает вашу задачу, немедленно возвращает идентификатор задачи, а затем вы опрашиваете статус завершения. Это разделение важно для расчёта ограничений скорости: вызов создания дешёвый и быстрый, поэтому ограничения RPM мягкие; тяжёлая работа контролируется параллелизмом на стороне модели — именно там, где ему место. Когда нижестоящий провайдер перегружен, вызов создания всё равно успешен — ваша задача просто ждёт в очереди, а GET /v1/tasks/{id} возвращает status: "queued", пока не освободится слот. Вы никогда не увидите 429 из-за мгновенного давления нижестоящего провайдера; только когда вы превышаете квоту собственного ключа.

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

Минимальный пример проверки

Используйте его, чтобы убедиться, что ваш ключ в порядке и настройки параллелизма разумны. Он отправляет задачу изображения в gpt-image-2 и выводит идентификатор задачи:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a single red apple on a wooden table, soft daylight",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Ожидаемый ответ:

• 200 с {"id":"task_...","status":"queued"} → ключ в порядке, квота в норме.
• 429 с {"error":{"code":"rate_limit_exceeded",...}} → вы превысили лимит RPM, RPD или параллелизма. Замедлитесь согласно шагам исправления выше.
• 401 с {"error":{"code":"permission_denied",...}} → ошибка аутентификации, а не ограничение скорости. Проверьте ваш ключ.

Повторите этот вызов быстрым циклом seq 1 10 | xargs -n1 -P10 curl ..., чтобы найти лимит параллелизма — первый возвращённый 429 отметит ваш эффективный лимит.

Связанные материалы

• Диагностика зависаний и тайм-аутов задач HiAPI — когда задача остаётся в состоянии queued или processing дольше ожидаемого.
• Почему не срабатывает обратный вызов вашей задачи HiAPI — устранение неполадок асинхронных обратных вызовов в процессе /v1/tasks.
• Решение ошибки model_not_available — смежная категория ошибок, которую часто ошибочно принимают за ограничение скорости.
• Каталог моделей — цены и типы конечных точек по моделям.
• Цены — разбивка по уровням.

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

Есть ли публичные значения RPM для gpt-image-2 в HiAPI? Лимиты зависят от уровня и могут изменяться, когда провайдеры корректируют собственные ограничения. Смотрите текущие действующие лимиты в вашей панели управления, а не в жёстко закодированных цифрах из статьи в блоге.

Почему повторы иногда ухудшают 429? Наивный повтор с sleep(1) на N параллельных воркерах превращает один 429 в N синхронных повторов, которые снова упираются в лимит. Используйте полный джиттер (sleep * random.random()), а не фиксированную задержку.

Взимает ли HiAPI плату за ответы 429? Нет. Неудачные создания задач (429, 401, обычные 4xx) не тарифицируются. Вы платите только за задачи, которые успешно выдали результат.

Повысит ли увеличение параллелизма на клиенте мой лимит? Нет. Лимит параллелизма задаётся на сервере для каждого ключа. Клиентский параллелизм определяет только, останетесь ли вы ниже лимита или превысите его.

В чём разница между RPM и TPM? API изображений ограничиваются по запросам (RPM), а не по токенам (TPM) — у задач изображений нет осмысленной единицы «токен». Если вы видите лимит TPM в панели управления, он применяется к текстовым/чат-конечным точкам, а не к задачам изображений /v1/tasks.

Стоит ли использовать один ключ с высоким параллелизмом или несколько ключей с низким? Для нагрузки по изображениям один ключ на каждый логический пул рабочих процессов — самая простая мысленная модель. Несколько ключей под одним расчётным аккаунтом фактически не умножают вашу квоту — они её делят.

Могу ли я запросить более высокий лимит параллелизма? Да — как только вы продемонстрируете устойчивое использование на текущем уровне. Предоставьте команде поддержки request_id репрезентативного 429, и они смогут отследить, какое измерение вы задели.

Почему я не вижу заголовок Retry-After? Не все провайдеры его отправляют. При отсутствии используйте экспоненциальную задержку с джиттером, начиная с 1 с. При наличии доверьтесь ему для этого повтора.