Cycle de vie des tâches

Toutes les générations API du Tripo API utilisent un modèle de tâche asynchrone. Après avoir soumis une demande, le API renvoie un task_id. Vous pouvez ensuite interroger l’état et le résultat de la tâche.

Machine à états

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

Descriptions des états

Statut	Descriptif	progrès
`queued`	La tâche a été créée et est en attente dans la file d’attente	0
`running`	La tâche est en cours de traitement	0-100
`success`	La tâche est terminée et le champ `output` est disponible	100
`failed`	La tâche a échoué, généralement en raison d’un problème côté serveur. Contacter l’assistance	-
`banned`	Le contenu d’entrée viole la politique de contenu	-
`expired`	La tâche a expiré et les fichiers de sortie ne sont plus disponibles	-
`cancelled`	La tâche a été annulée	-

Flux de tâches

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

Modèle de gel du crédit

Tripo utilise un modèle de crédit « geler puis déduire » pour garantir que les utilisateurs ne sont pas facturés pour les tâches ayant échoué :

Scène	Changement de crédit	Descriptif
Création de tâches	Geler les crédits requis	Les crédits sont pré-autorisés à partir du solde disponible et placés dans un état gelé
La tâche réussit	Les crédits gelés deviennent des crédits consommés	Les crédits sont formellement déduits
La tâche échoue	Les crédits gelés sont libérés	Les crédits sont restitués au solde disponible
La tâche est annulée	Les crédits gelés sont libérés	Les crédits sont restitués au solde disponible

Interrogez le solde actuel et les crédits gelés :

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

Recommandations de sondage

Intervalle d’interrogation : requête une fois toutes les 1 à 2 secondes
Utilisez le champ progress pour afficher la progression : La valeur est un entier compris entre 0 et 100
Définir un délai d’attente : nous vous recommandons de définir une durée d’interrogation maximale, par exemple 5 minutes. Si le délai expire, demandez à l’utilisateur de vérifier à nouveau plus tard.
Utilisez POST /v3/tasks/list pour les tâches par lots : réduisez le nombre de requêtes

Exemple d’interrogation Python

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

Exemple d’interrogation JavaScript

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