快速开始

快速开始

API

MCP 服务
API 概览认证可用模型

指南

快速开始任务与轮询错误处理

计费与限制

定价与积分速率限制

集成

OpenAPI 规范与 SDK
API

任务与轮询

同步与异步模式、任务生命周期,以及如何正确轮询结果

任务与轮询

一次生成就是一个任务。用 POST /api/v1/3d/generations 创建,用 GET /api/v1/tasks/{taskId} 读取状态。

开工前只有一个选择要定:等它,还是轮询它。

同步 vs 异步

mode: "sync"mode: "async"(默认)
响应状态码200202 Accepted
模型已完成时直接返回完整结果(status: "completed")status: "pending",还没有结果
单次请求最长等待55 秒立即返回
模型耗时超过等待上限200 + status: "running"—
适合交互式工具、一次性脚本队列、批量作业、你自己有回调系统的场景

mode: "sync" 的上限是 55 秒。超时不算失败——响应会带 status: "running" 和一条 message 让你去轮询。也就是说同步模式照样得处理轮询逻辑, 大多数集成因此直接用 mode: "async"。

异步:先创建,再轮询

curl -X POST https://trellis2.app/api/v1/3d/generations \
  -H "Authorization: Bearer tr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/chair.jpg",
    "model": "trellis2",
    "mode": "async"
  }'
{
  "id": "task_abc123",
  "object": "task",
  "status": "pending",
  "created": 1723000000,
  "data": null
}
curl https://trellis2.app/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer tr_your_key"

同步:同一个任务,直接等

curl -X POST https://trellis2.app/api/v1/3d/generations \
  -H "Authorization: Bearer tr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/chair.jpg",
    "model": "trellis2",
    "mode": "sync"
  }'

若在 55 秒内完成,直接拿到完成态响应;否则:

{
  "id": "task_abc123",
  "object": "3d.generation",
  "status": "running",
  "created": 1723000000,
  "data": null,
  "message": "Task is still running. Poll GET /api/v1/tasks/task_abc123 to check status."
}

任务状态

pending ──▶ running ──▶ completed
                    └─▶ failed
status含义有 data 吗
pending已入队,尚未被领取无
running生成中无
completed已完成,模型地址在 data 里有
failed生成失败,看 error无

运行期间的响应还会带 progress(0–100)和 progress_stage(可读的阶段标签),足够驱动进度条。

读取结果

{
  "id": "task_abc123",
  "object": "3d.generation",
  "status": "completed",
  "progress": 100,
  "progress_stage": "Completed",
  "created": 1723000000,
  "completed_at": 1723000060,
  "data": {
    "model_url": "https://r2.example.com/model.glb",
    "format": "glb",
    "model": "trellis2"
  },
  "usage": {
    "credits_consumed": 10,
    "credits_remaining": 490
  }
}

data.model_url 是可下载地址,拿到就自己转存。不要把这个 URL 当成资产的唯一副本——它不保证永久有效。

读取失败

{
  "id": "task_abc123",
  "object": "3d.generation",
  "status": "failed",
  "progress": 40,
  "progress_stage": "Failed",
  "created": 1723000000,
  "completed_at": 1723000030,
  "error": {
    "message": "Provider rejected the input image",
    "type": "generation_error"
  },
  "data": null,
  "usage": {
    "credits_refunded": 10,
    "credits_remaining": 500
  }
}

失败的生成会退款,退款发生时 usage.credits_refunded 才会出现。余额一律以 usage.credits_remaining 为准,不要自己本地做减法。

轮询写法

接口没有 webhook 或回调,轮询是唯一的进度观察方式。建议间隔不小于 2 秒。

async function waitForTask(taskId: string, apiKey: string) {
  const deadline = Date.now() + 5 * 60 * 1000; // 5 分钟上限
  let interval = 2000;

  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, interval));

    const res = await fetch(
      `https://trellis2.app/api/v1/tasks/${taskId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    if (res.status === 429) {
      // 被限流就退避,别硬顶
      interval = Math.min(interval * 2, 15_000);
      continue;
    }
    if (!res.ok) throw new Error(`Polling failed: ${res.status}`);

    const task = await res.json();
    if (task.status === 'completed') return task.data;
    if (task.status === 'failed') throw new Error(task.error?.message);

    // 温和退避:2s → 3s → 4.5s,上限 10s
    interval = Math.min(Math.round(interval * 1.5), 10_000);
  }

  throw new Error('Timed out waiting for task');
}
import time, requests

def wait_for_task(task_id: str, api_key: str, timeout: int = 300) -> dict:
    deadline, interval = time.time() + timeout, 2.0
    headers = {"Authorization": f"Bearer {api_key}"}

    while time.time() < deadline:
        time.sleep(interval)
        r = requests.get(
            f"https://trellis2.app/api/v1/tasks/{task_id}",
            headers=headers, timeout=15,
        )
        if r.status_code == 429:
            interval = min(interval * 2, 15)
            continue
        r.raise_for_status()

        task = r.json()
        if task["status"] == "completed":
            return task["data"]
        if task["status"] == "failed":
            raise RuntimeError(task["error"]["message"])

        interval = min(interval * 1.5, 10.0)

    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

边界情况

  • 任务不存在或不属于你 → 404,type: "not_found_error"。任务按账号隔离,别人账号的 taskId 和不存在的 ID 表现完全一致。
  • 轮询过猛 → 429 带 Retry-After。每次轮询和创建生成共用同一个 60 次/分钟的额度,并发任务多了会把自己饿死。
  • 失败后重试是一次新任务,会重新扣积分——见 定价与积分。

查询任务状态

轮询端点的交互式参考

速率限制

轮询循环为什么会撞 429

错误处理

全部错误码与对应处置

快速开始

完整的分步指南,完成您的首次 3D 生成

错误处理

如何处理 API 错误和边界情况

目录

任务与轮询
同步 vs 异步
异步:先创建,再轮询
同步:同一个任务,直接等
任务状态
读取结果
读取失败
轮询写法
边界情况