# Aufgabenlebenszyklus

Alle Generationen APIs im Tripo API verwenden ein asynchrones Aufgabenmuster. Nachdem Sie eine Anfrage gesendet haben, gibt API einen `task_id` zurück. Anschließend können Sie den Aufgabenstatus und das Ergebnis abfragen.

## Zustandsmaschine

```
queued -> running -> success
                 -> failed
                 -> cancelled
```

## Statusbeschreibungen

| Status | Beschreibung | Fortschritt |
| :-: | :-: | :-: |
| `queued` | Die Aufgabe wurde erstellt und wartet in der Warteschlange | 0 |
| `running` | Die Aufgabe wird bearbeitet | 0-100 |
| `success` | Die Aufgabe ist abgeschlossen und das Feld `output` ist verfügbar | 100 |
| `failed` | Die Aufgabe ist fehlgeschlagen, normalerweise aufgrund eines serverseitigen Problems. Kontaktieren Sie den Support | - |
| `banned` | Der eingegebene Inhalt verstößt gegen die Inhaltsrichtlinie | - |
| `expired` | Die Aufgabe ist abgelaufen und die Ausgabedateien sind nicht mehr verfügbar | - |
| `cancelled` | Die Aufgabe wurde abgebrochen | - |

## Aufgabenablauf

```
1. Create a task (POST /v3/generation/*)
   |
   v
2. Return task_id
   |
   v
3. Poll status (GET /v3/tasks/{task_id})
   |
   v
4a. status=success -> Get download links from output
4b. status=failed  -> Check error details and contact support
4c. status=banned  -> Modify the input content and submit again
```

## Kredit-Freeze-Modell

Tripo verwendet ein Guthabenmodell „Einfrieren und dann abziehen“, um sicherzustellen, dass Benutzern keine Kosten für fehlgeschlagene Aufgaben in Rechnung gestellt werden:

| Bühne | Kreditänderung | Beschreibung |
| :-: | :-: | :-: |
| Aufgabenerstellung | Frieren Sie die benötigten Credits ein | Gutschriften werden vom verfügbaren Guthaben vorautorisiert und in einen eingefrorenen Zustand versetzt |
| Die Aufgabe ist erfolgreich | Eingefrorene Credits werden zu verbrauchten Credits | Credits werden offiziell abgezogen |
| Aufgabe schlägt fehl | Eingefrorene Guthaben werden freigegeben | Gutschriften werden auf das verfügbare Guthaben zurückerstattet |
| Aufgabe wird abgebrochen | Eingefrorene Guthaben werden freigegeben | Gutschriften werden auf das verfügbare Guthaben zurückerstattet |

Aktuellen Kontostand und eingefrorene Guthaben abfragen:

```bash
curl -X GET https://openapi.tripo3d.ai/v3/account/balance \
  -H "Authorization: Bearer {api_key}"
```

```json
{
  "code": 0,
  "data": {
    "balance": 10000,
    "frozen": 200
  }
}
```

## Umfrageempfehlungen

- **Abfrageintervall**: Abfrage einmal alle 1–2 Sekunden
- **Verwenden Sie das Feld `progress`, um den Fortschritt anzuzeigen**: Der Wert ist eine Ganzzahl von 0 bis 100
- **Legen Sie eine Zeitüberschreitung fest**: Wir empfehlen, eine maximale Abfragedauer festzulegen, z. B. 5 Minuten. Wenn es zu einer Zeitüberschreitung kommt, bitten Sie den Benutzer, es später noch einmal zu überprüfen
- **Verwenden Sie `POST /v3/tasks/list` für Batch-Aufgaben**: Reduzieren Sie die Anzahl der Anforderungen

### Python Abfragebeispiel

```python
import time
import requests

def wait_for_task(task_id, api_key, interval=2, timeout=300):
    url = f"https://openapi.tripo3d.ai/v3/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    start = time.time()

    while time.time() - start < timeout:
        response = requests.get(url, headers=headers)
        task = response.json()["data"]
        status = task["status"]
        progress = task.get("progress", 0)

        print(f"[{task_id}] {status} ({progress}%)")

        if status == "success":
            return task["output"]
        if status in ("failed", "cancelled", "banned"):
            raise Exception(f"Task terminated: {status}")

        time.sleep(interval)

    raise TimeoutError(f"Task {task_id} timed out")
```

### JavaScript Abfragebeispiel

```javascript
async function waitForTask(taskId, apiKey, interval = 2000, timeout = 300000) {
  const url = `https://openapi.tripo3d.ai/v3/tasks/${taskId}`;
  const headers = { "Authorization": `Bearer ${apiKey}` };
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const response = await fetch(url, { headers });
    const { data: task } = await response.json();
    const { status, progress = 0 } = task;

    console.log(`[${taskId}] ${status} (${progress}%)`);

    if (status === "success") return task.output;
    if (["failed", "cancelled", "banned"].includes(status)) {
      throw new Error(`Task terminated: ${status}`);
    }

    await new Promise(resolve => setTimeout(resolve, interval));
  }

  throw new Error(`Task ${taskId} timed out`);
}
```