Limiti di velocità e concorrenza

Tripo API applica limiti di velocità e limiti di concorrenza per garantire la stabilità del servizio e un utilizzo corretto.

Limiti di velocità

I limiti di tariffa limitano il numero di richieste API che puoi effettuare in un intervallo di tempo.

Regole sui limiti

I limiti di velocità sono calcolati al livello API Key
I limiti variano in base all’endpoint. Gli endpoint di generazione, come /v3/generation/*, hanno limiti inferiori, mentre gli endpoint di query, come /v3/tasks/*, hanno limiti più alti
Quando viene superato un limite, API restituisce HTTP 429 Too Many Requests con il codice di errore 1007

Intestazioni di risposta

Ogni risposta API include intestazioni di risposta relative al limite di velocità:

Intestazione della risposta	Descrizione
`X-RateLimit-Limit`	Numero massimo di richieste consentite nella finestra temporale corrente
`X-RateLimit-Remaining`	Numero di richieste rimanenti disponibili nella finestra temporale corrente
`X-RateLimit-Reset`	Timestamp Unix, in secondi, quando la finestra del limite di velocità viene reimpostata

Risposta in caso di velocità limitata

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

Limiti di concorrenza

I limiti di concorrenza limitano il numero di attività che possono essere eseguite simultaneamente nel tuo account. Questo è diverso dai limiti di velocità: i limiti di velocità limitano la frequenza delle richieste, mentre i limiti di concorrenza limitano le attività in esecuzione parallela.

Come funziona

La concorrenza viene calcolata a livello di account (non per API Key)
I limiti vengono applicati per categoria di attività: ogni categoria ha il proprio pool di concorrenza indipendente
Quando la concorrenza di una categoria è piena, la creazione di una nuova attività per quella categoria restituisce HTTP 429 con il codice di errore 2000
Le attività in altre categorie non sono interessate: puoi comunque creare attività nelle categorie con slot disponibili

Limiti predefiniti

Tutti gli utenti iniziano con una concorrenza predefinita di 10 per categoria; alcune categorie hanno limiti diversi (vedi tabella seguente).

Categoria	Tipi di attività inclusi	Concorrenza predefinita
Generazione 3D: serie H	testo in modello (H), immagine in modello (H), multivista in modello (H)	10
Generazione 3D: serie P	testo in modello (P), immagine in modello (P), multivista in modello (P)	5
Generazione di immagini	testo in immagine, immagine in immagine, immagine in visualizzazione multipla, modifica visualizzazione multipla	1
Animazione	auto-rig, rig-check, animazione-retarget	10
Elaborazione del modello	texture, conversione del formato, perfezionamento	5
Operazioni di rete	segmentazione, completamento, retopologia	10

Nota: le attività all’interno della stessa categoria condividono il pool di concorrenza. Ad esempio, se sono in esecuzione 10 attività di conversione da testo a modello della serie H, non è possibile avviare un’attività di conversione da immagine a modello della serie H finché non viene completata. Tuttavia, è ancora possibile avviare attività di serie P o di generazione di immagini.

Risposta in caso di superamento della concorrenza

JSON

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

La risposta include un’intestazione Retry-After che indica quanti secondi attendere prima di riprovare.

Aumentare la concorrenza

Per richiedere limiti di concorrenza più elevati, contatta il nostro team tramite il canale di supporto. La concorrenza personalizzata può essere configurata per categoria in base alle esigenze di utilizzo.

Gestione di 429 risposte

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

Migliori pratiche

Implementa tentativi di backoff esponenziale: attendere inizialmente 1 secondo, raddoppiare l’attesa ogni volta e limitare l’attesa massima a 32 secondi
Preferisci intestazioni Retry-After e X-RateLimit-Reset: attendi esattamente fino al ripristino della finestra limite
Progetta per la concorrenza a livello di categoria: distribuisci i carichi di lavoro tra le categorie quando possibile: la generazione di immagini e la generazione 3D hanno pool separati
Utilizza API batch: utilizza POST /v3/tasks/list invece di più richieste GET /v3/tasks/{task_id}
Eseguire sondaggi saggiamente: quando si attende il completamento dell’attività, eseguire il polling a intervalli ragionevoli (ogni 1-2 secondi) anziché sovraccaricare l’endpoint della query