タスクのライフサイクル

Tripo API のすべての世代の 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

-cmd">curl -X GET https://openapi.tripo3d.ai/v3/account/balance \
  -H "Authorization: Bearer {api_key}"

JSON

{
  "code": 0,
  "data": {
    "balance": 10000,
    "frozen": 200
  }
}

投票の推奨事項

ポーリング間隔: 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`);
}