작업 수명주기

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

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