Tripo3D

Ciclo di vita delle attività

Ciclo di vita delle attività

Tutti gli API della generazione Tripo API utilizzano uno schema di attività asincrono. Dopo aver inviato una richiesta, API restituisce un task_id. È quindi possibile eseguire il polling dello stato e del risultato dell’attività.

Macchina dello Stato

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

Descrizioni dello stato

Stato Descrizione progresso
queued L’attività è stata creata ed è in attesa in coda 0
running L’attività è in fase di elaborazione 0-100
success L’attività è completata e il campo output è disponibile 100
failed L’attività non è riuscita, in genere a causa di un problema lato server. Contatta l’assistenza -
banned Il contenuto immesso viola la politica sui contenuti -
expired L’attività è scaduta e i file di output non sono più disponibili -
cancelled L’attività è stata annullata -

Flusso di attività

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

Modello di congelamento del credito

Tripo utilizza un modello di “congelamento e detrazione” del credito per garantire che agli utenti non vengano addebitati costi per attività non riuscite:

Palcoscenico Cambio di credito Descrizione
Creazione di attività Congelare i crediti richiesti I crediti vengono pre-autorizzati dal saldo disponibile e spostati in uno stato congelato
L’attività riesce I crediti congelati diventano crediti consumati I crediti vengono formalmente detratti
L’attività fallisce I crediti congelati vengono rilasciati I crediti vengono restituiti al saldo disponibile
L’attività è annullata I crediti congelati vengono rilasciati I crediti vengono restituiti al saldo disponibile

Interrogare il saldo attuale e i crediti congelati:

Bash
-cmd">curl -X GET https://openapi.tripo3d.ai/v3/account/balance \
  -H "Authorization: Bearer {api_key}"
JSON
{
  "code": 0,
  "data": {
    "balance": 10000,
    "frozen": 200
  }
}

Raccomandazioni per i sondaggi

  • Intervallo di polling: interroga una volta ogni 1-2 secondi
  • Utilizzare il campo progress per visualizzare l’avanzamento: il valore è un numero intero compreso tra 0 e 100
  • Imposta un timeout: ti consigliamo di impostare una durata massima del polling, ad esempio 5 minuti. Se scade, chiedi all’utente di ricontrollare più tardi
  • Utilizza POST /v3/tasks/list per attività batch: riduce il numero di richieste

Python Esempio di polling

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 Esempio di polling

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