Жизненный цикл задачи

Все поколения API в Tripo API используют шаблон асинхронных задач. После отправки запроса API возвращает task_id. Затем вы можете опросить статус задачи и результат.

Государственная машина

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

Описание статуса

Статус	Описание	прогресс
`queued`	Задача создана и ожидает в очереди	0
`running`	Задача находится в обработке	0-100
`success`	Задача выполнена, поле `output` доступно.	100
`failed`	Задача не выполнена, обычно из-за проблемы на стороне сервера. Связаться со службой поддержки	-
`banned`	Входной контент нарушает политику в отношении контента	-
`expired`	Срок действия задачи истек, и выходные файлы больше не доступны.	-
`cancelled`	Задача отменена	-

Поток задач

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

Модель замораживания кредита

Tripo использует модель кредита «заморозить, а затем списать», чтобы гарантировать, что с пользователей не взимается плата за невыполненные задачи:

Этап	Изменение кредита	Описание
Создание задачи	Заморозить необходимые кредиты	Кредиты предварительно авторизуются из доступного баланса и переводятся в замороженное состояние.
Задача выполнена успешно	Замороженные кредиты становятся израсходованными кредитами	Кредиты формально списываются
Задача не выполнена	Замороженные кредиты освобождены	Кредиты возвращаются на доступный баланс
Задача отменена	Замороженные кредиты освобождены	Кредиты возвращаются на доступный баланс

Запрос текущего баланса и замороженных кредитов:

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

Рекомендации по опросу

Интервал опроса: запрос каждые 1–2 секунды.
Используйте поле progress для отображения прогресса: значение представляет собой целое число от 0 до 100.
Установите тайм-аут. Мы рекомендуем установить максимальную продолжительность опроса, например 5 минут. Если время ожидания истекло, попросите пользователя проверить еще раз позже.
Используйте POST /v3/tasks/list для пакетных задач: сократите количество запросов.

Пример опроса 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")

Пример опроса 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`);
}