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.00,
    "frozen": 200.00
  }
}

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