Ограничения скорости и параллелизм

Tripo API применяет ограничения скорости и параллелизма для обеспечения стабильности сервиса и справедливого использования.

Ограничения ставок

Ограничения скорости ограничивают количество запросов API, которые вы можете сделать в пределах временного окна.

Ограничительные правила

Ограничения скорости рассчитываются на уровне API Key.
Ограничения различаются в зависимости от конечной точки. Конечные точки генерации, такие как /v3/generation/*, имеют более низкие ограничения, а конечные точки запроса, такие как /v3/tasks/*, имеют более высокие ограничения.
При превышении лимита API возвращает HTTP 429 Too Many Requests с кодом ошибки 1007.

Заголовки ответов

Каждый ответ API включает заголовки ответа, связанные с ограничением скорости:

Заголовок ответа	Описание
`X-RateLimit-Limit`	Максимальное количество запросов, разрешенное в текущем временном окне
`X-RateLimit-Remaining`	Количество оставшихся запросов, доступных в текущем временном окне
`X-RateLimit-Reset`	Временная метка Unix в секундах, когда окно ограничения скорости сбрасывается.

Реакция при ограничении скорости

JSON

{
  "code": 1007,
  "message": "Rate limit exceeded, you've generated too many requests in a short amount of time",
  "suggestion": "Please wait for a while and try again"
}

Ограничения параллелизма

Ограничения параллелизма ограничивают количество задач, которые могут выполняться одновременно под вашей учетной записью. Это отличается от ограничений скорости: ограничения скорости ограничивают частоту запросов, а ограничения параллелизма ограничивают параллельно выполняемые задачи.

Как это работает

Параллелизм рассчитывается на уровне учетной записи (не для API Key).
Ограничения применяются для каждой категории задач — каждая категория имеет свой собственный независимый пул параллелизма.
Когда параллелизм категории заполнен, при создании новой задачи для этой категории возвращается HTTP 429 с кодом ошибки 2000.
Задачи в других категориях не затрагиваются — вы по-прежнему можете создавать задачи в категориях, в которых есть свободные слоты.

Пределы по умолчанию

Все пользователи начинают с параллелизма по умолчанию, равного 10 для каждой категории; в некоторых категориях установлены другие лимиты (см. таблицу ниже).

Категория	Включенные типы задач	Параллелизм по умолчанию
3D-поколение — серия H	преобразование текста в модель (H), преобразование изображения в модель (H), преобразование нескольких представлений в модель (H)	10
3D-генерация — серия P	преобразование текста в модель (P), преобразование изображения в модель (P), преобразование нескольких представлений в модель (P)	5
Генерация изображений	преобразование текста в изображение, изображение в изображение, изображение в несколько изображений, редактирование нескольких изображений	1
Анимация	авто-риг, проверка рига, перенацеливание анимации	10
Обработка модели	текстура, преобразование формата, уточнение	5
Операции с сеткой	сегментация, завершение, ретопология	10

Примечание. Задачи одной категории используют общий пул параллелизма. Например, если у вас запущено 10 задач преобразования текста в модель серии H, вы не сможете запустить задачу преобразования изображения в модель серии H, пока одна из них не будет завершена. Однако вы по-прежнему можете запускать задачи P-серии или создания изображений.

Реакция при превышении параллелизма

JSON

{
  "code": 2000,
  "message": "You have exceeded the limit of generation",
  "suggestion": "Try again later. You can also check `Retry-After` header."
}

Ответ включает заголовок Retry-After, указывающий, сколько секунд нужно подождать перед повторной попыткой.

Увеличение параллелизма

Чтобы запросить более высокие лимиты одновременности, свяжитесь с нашей командой через канал поддержки. Пользовательский параллелизм можно настроить для каждой категории в зависимости от ваших потребностей в использовании.

Обработка 429 ответов

import time
import requests

def request_with_backoff(method, url, headers, json=None, max_retries=5):
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, json=json)

        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        reset_at = response.headers.get("X-RateLimit-Reset")

        if retry_after:
            wait = int(retry_after)
        elif reset_at:
            wait = max(int(reset_at) - int(time.time()), 1)
        else:
            wait = 2 ** attempt

        print(f"429 triggered. Waiting {wait} seconds (attempt {attempt + 1})...")
        time.sleep(wait)

    raise Exception("Maximum retry attempts exhausted")

async function requestWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = response.headers.get("Retry-After");
    const resetAt = response.headers.get("X-RateLimit-Reset");
    const wait = retryAfter
      ? Number(retryAfter)
      : resetAt
        ? Math.max(Number(resetAt) - Math.floor(Date.now() / 1000), 1)
        : 2 ** attempt;

    console.log(`429 triggered. Waiting ${wait} seconds (attempt ${attempt + 1})...`);
    await new Promise(resolve => setTimeout(resolve, wait * 1000));
  }

  throw new Error("Maximum retry attempts exhausted");
}

Лучшие практики

Реализовать повторные попытки экспоненциальной отсрочки: сначала подождите 1 секунду, каждый раз удваивайте время ожидания и ограничьте максимальное время ожидания 32 секундами.
Предпочитайте заголовки Retry-After и X-RateLimit-Reset: дождитесь сброса окна пределов.
Проектируйте параллелизм на уровне категорий: по возможности распределяйте рабочую нагрузку по категориям — создание изображений и создание 3D-изображений имеют отдельные пулы.
Использовать пакетные запросы API: используйте POST /v3/tasks/list вместо нескольких запросов GET /v3/tasks/{task_id}.
Опрос разумный: ожидая завершения задачи, опрашивайте через разумные промежутки времени (каждые 1–2 секунды), а не заполняйте конечную точку запроса.