Limites de taxa e simultaneidade

O Tripo API aplica limites de taxa e limites de simultaneidade para garantir a estabilidade do serviço e o uso justo.

Limites de taxa

Os limites de taxa restringem o número de solicitações API que você pode fazer em um intervalo de tempo.

Regras de Limite

Os limites de taxa são calculados no nível API Key
Os limites variam de acordo com o endpoint. Os endpoints de geração, como /v3/generation/*, têm limites mais baixos, enquanto os endpoints de consulta, como /v3/tasks/*, têm limites mais altos
Quando um limite é excedido, API retorna HTTP 429 Too Many Requests com código de erro 1007

Cabeçalhos de resposta

Cada resposta API inclui cabeçalhos de resposta relacionados ao limite de taxa:

Cabeçalho de resposta	Descrição
`X-RateLimit-Limit`	Número máximo de solicitações permitidas na janela de tempo atual
`X-RateLimit-Remaining`	Número de solicitações restantes disponíveis na janela de tempo atual
`X-RateLimit-Reset`	Carimbo de data/hora Unix, em segundos, quando a janela de limite de taxa é redefinida

Resposta quando a taxa é limitada

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"
}

Limites de simultaneidade

Os limites de simultaneidade restringem o número de tarefas que podem ser executadas simultaneamente em sua conta. Isso é diferente dos limites de taxa – os limites de taxa limitam a frequência de solicitação, enquanto os limites de simultaneidade limitam as tarefas de execução paralela.

Como funciona

A simultaneidade é calculada no nível da conta (não por API Key)
Os limites são aplicados por categoria de tarefa — cada categoria tem seu próprio pool de simultaneidade independente
Quando a simultaneidade de uma categoria está completa, a criação de uma nova tarefa para essa categoria retorna HTTP 429 com o código de erro 2000
Tarefas em outras categorias não são afetadas — você ainda pode criar tarefas em categorias que tenham vagas disponíveis

Limites padrão

Todos os usuários começam com uma simultaneidade padrão de 10 por categoria; algumas categorias têm limites diferentes (veja a tabela abaixo).

Categoria	Tipos de tarefas incluídas	Simultaneidade padrão
Geração 3D – Série H	texto para modelo (H), imagem para modelo (H), multivisualização para modelo (H)	10
Geração 3D — Série P	texto para modelo (P), imagem para modelo (P), multivisualização para modelo (P)	5
Geração de imagem	texto para imagem, imagem para imagem, imagem para multivisualização, edição multivisualização	1
Animação	auto-rig, rig-check, animação-retarget	10
Processamento de modelo	textura, conversão de formato, refinar	5
Operações de malha	segmentação, conclusão, retopologia	10

Observação: Tarefas dentro da mesma categoria compartilham o pool de simultaneidade. Por exemplo, se você tiver 10 tarefas de texto para modelo da série H em execução, não será possível iniciar uma tarefa de imagem para modelo da série H até que uma seja concluída. No entanto, você ainda pode iniciar tarefas da série P ou de geração de imagens.

Resposta quando a simultaneidade é excedida

JSON

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

A resposta inclui um cabeçalho Retry-After indicando quantos segundos esperar antes de tentar novamente.

Aumentando a simultaneidade

Para solicitar limites maiores de simultaneidade, entre em contato com nossa equipe pelo canal de suporte. A simultaneidade personalizada pode ser configurada por categoria com base nas suas necessidades de uso.

Lidando com 429 respostas

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");
}

Melhores Práticas

Implementar novas tentativas de espera exponencial: espere 1 segundo inicialmente, duplique a espera a cada vez e limite a espera máxima a 32 segundos
Prefira os cabeçalhos Retry-After e X-RateLimit-Reset: aguarde precisamente até que a janela de limite seja redefinida
Projete para simultaneidade em nível de categoria: distribua cargas de trabalho entre categorias quando possível — a geração de imagens e a geração 3D têm pools separados
Use APIs em lote: use POST /v3/tasks/list em vez de várias solicitações GET /v3/tasks/{task_id}
Pesquise com sabedoria: ao aguardar a conclusão da tarefa, pesquise em intervalos razoáveis (a cada 1–2 segundos) em vez de sobrecarregar o endpoint da consulta