# Ratenbegrenzungen und Parallelität

Der Tripo API wendet Ratenbegrenzungen und Parallelitätsbegrenzungen an, um Dienststabilität und faire Nutzung sicherzustellen.

## Ratenbeschränkungen

Ratenbegrenzungen beschränken die Anzahl der API-Anfragen, die Sie innerhalb eines Zeitfensters stellen können.

### Limitregeln

- Ratenbegrenzungen werden auf der Ebene **API Key** berechnet
- Die Grenzwerte variieren je nach Endpunkt. Generierungsendpunkte wie `/v3/generation/*` haben niedrigere Grenzwerte, während Abfrageendpunkte wie `/v3/tasks/*` höhere Grenzwerte haben
- Wenn ein Grenzwert überschritten wird, gibt API HTTP `429 Too Many Requests` mit dem Fehlercode `1007` zurück

### Antwortheader

Jede API-Antwort enthält Antwortheader im Zusammenhang mit der Ratenbegrenzung:

| Antwortheader | Beschreibung |
| :-: | :-: |
| `X-RateLimit-Limit` | Maximale Anzahl zulässiger Anfragen im aktuellen Zeitfenster |
| `X-RateLimit-Remaining` | Anzahl der verbleibenden Anfragen, die im aktuellen Zeitfenster verfügbar sind |
| `X-RateLimit-Reset` | Unix-Zeitstempel in Sekunden, wenn das Ratenbegrenzungsfenster zurückgesetzt wird |

### Reaktion bei begrenzter Rate

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

---

## Parallelitätsbeschränkungen

Parallelitätsbeschränkungen beschränken die Anzahl der Aufgaben, die **gleichzeitig** unter Ihrem Konto ausgeführt werden können. Dies unterscheidet sich von Ratenbegrenzungen – Ratenbegrenzungen begrenzen die Anforderungshäufigkeit, während Parallelitätsbegrenzungen parallel laufende Aufgaben begrenzen.

### Wie es funktioniert

- Die Parallelität wird auf **Kontoebene** berechnet (nicht gemäß API Key).
- Es gelten Beschränkungen **pro Aufgabenkategorie** – jede Kategorie verfügt über ihren eigenen unabhängigen Parallelitätspool
- Wenn die Parallelität einer Kategorie voll ist, wird beim Erstellen einer neuen Aufgabe für diese Kategorie HTTP `429` mit dem Fehlercode `2000` zurückgegeben
- Aufgaben in anderen Kategorien sind **nicht betroffen** – Sie können weiterhin Aufgaben in Kategorien erstellen, die über freie Plätze verfügen

### Standardgrenzen

Alle Benutzer beginnen mit einer Standard-Parallelität von **10** pro Kategorie; Für einige Kategorien gelten unterschiedliche Grenzwerte (siehe Tabelle unten).

| Kategorie | Enthaltene Aufgabentypen | Standard-Parallelität |
| :-: | :-: | :-: |
| 3D-Generierung – H-Serie | Text-zu-Modell (H), Bild-zu-Modell (H), Multiview-zu-Modell (H) | 10 |
| 3D-Generierung – P-Serie | Text-zu-Modell (P), Bild-zu-Modell (P), Multiview-zu-Modell (P) | 5 |
| Bilderzeugung | Text-zu-Bild, Bild-zu-Bild, Bild-zu-Multiview, Bearbeiten-Multiview | 1 |
| Animation | Auto-Rig, Rig-Check, Animation-Retarget | 10 |
| Modellverarbeitung | Textur, Formatkonvertierung, Verfeinerung | 5 |
| Mesh-Operationen | Segmentierung, Vervollständigung, Retopologie | 10 |

> **Hinweis:** Aufgaben innerhalb derselben Kategorie teilen sich den Parallelitätspool. Wenn beispielsweise 10 Text-zu-Modell-Aufgaben der H-Serie ausgeführt werden, können Sie eine Bild-zu-Modell-Aufgabe der H-Serie erst dann starten, wenn eine davon abgeschlossen ist. Sie können jedoch weiterhin P-Serien- oder Bildgenerierungsaufgaben starten.

### Reaktion, wenn die Parallelität überschritten wird

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

Die Antwort enthält einen `Retry-After`-Header, der angibt, wie viele Sekunden vor dem erneuten Versuch gewartet werden muss.

### Zunehmende Parallelität

Um höhere Parallelitätslimits anzufordern, kontaktieren Sie bitte unser Team über den Support-Kanal. Benutzerdefinierte Parallelität kann je nach Ihren Nutzungsanforderungen pro Kategorie konfiguriert werden.

---

## Bearbeitung von 429 Antworten

### Python

```python
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")
```

### JavaScript

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

## Best Practices

- **Exponentielle Backoff-Wiederholungsversuche implementieren**: Warten Sie zunächst 1 Sekunde, verdoppeln Sie die Wartezeit jedes Mal und begrenzen Sie die maximale Wartezeit auf 32 Sekunden
- **Bevorzugen Sie die Header `Retry-After` und `X-RateLimit-Reset`**: Warten Sie genau, bis das Begrenzungsfenster zurückgesetzt wird
- **Design für Parallelität auf Kategorieebene**: Verteilen Sie Arbeitslasten nach Möglichkeit auf mehrere Kategorien – Bildgenerierung und 3D-Generierung verfügen über separate Pools
- **Batch-APIs verwenden**: Verwenden Sie `POST /v3/tasks/list` anstelle mehrerer `GET /v3/tasks/{task_id}`-Anfragen
- **Mit Bedacht abfragen**: Wenn Sie auf den Abschluss einer Aufgabe warten, führen Sie eine Abfrage in angemessenen Abständen (alle 1–2 Sekunden) durch, anstatt den Abfrageendpunkt zu überfluten