Ciclo de vida de la tarea

Todas las generaciones API en Tripo API utilizan un patrón de tarea asincrónico. Después de enviar una solicitud, API devuelve un task_id. Luego puede sondear el estado y el resultado de la tarea.

Máquina de estados

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

Descripciones de estado

Estado	Descripción	progreso
`queued`	La tarea ha sido creada y está esperando en la cola.	0
`running`	La tarea está siendo procesada.	0-100
`success`	La tarea está completa y el campo `output` está disponible	100
`failed`	La tarea falló, generalmente debido a un problema del lado del servidor. Contactar con soporte	-
`banned`	El contenido de entrada viola la política de contenido.	-
`expired`	La tarea ha caducado y los archivos de salida ya no están disponibles	-
`cancelled`	La tarea ha sido cancelada.	-

Flujo de tareas

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

Modelo de congelación de crédito

Tripo utiliza un modelo de crédito de “congelación y luego deducción” para garantizar que no se cobre a los usuarios por tareas fallidas:

etapa	Cambio de crédito	Descripción
Creación de tareas	Congelar los créditos requeridos	Los créditos se preautorizan a partir del saldo disponible y se trasladan a un estado congelado
La tarea tiene éxito	Los créditos congelados pasan a ser créditos consumidos	Los créditos se deducen formalmente.
La tarea falla	Se liberan los créditos congelados	Los créditos se devuelven al saldo disponible.
La tarea está cancelada	Se liberan los créditos congelados	Los créditos se devuelven al saldo disponible.

Consulta del saldo actual y créditos congelados:

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

Recomendaciones de encuestas

Intervalo de sondeo: consulta una vez cada 1-2 segundos
Utilice el campo progress para mostrar el progreso: El valor es un número entero de 0 a 100
Establecer un tiempo de espera: recomendamos establecer una duración máxima de sondeo, como 5 minutos. Si se agota el tiempo de espera, dígale al usuario que vuelva a comprobarlo más tarde.
Utilice POST /v3/tasks/list para tareas por lotes: reduzca el número de solicitudes

Ejemplo de sondeo 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")

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