API
任务与轮询
同步与异步模式、任务生命周期,以及如何正确轮询结果
任务与轮询
一次生成就是一个任务。用 POST /api/v1/3d/generations 创建,用 GET /api/v1/tasks/{taskId} 读取状态。
开工前只有一个选择要定:等它,还是轮询它。
同步 vs 异步
mode: "sync" | mode: "async"(默认) | |
|---|---|---|
| 响应状态码 | 200 | 202 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
└─▶ failedstatus | 含义 | 有 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 次/分钟的额度,并发任务多了会把自己饿死。 - 失败后重试是一次新任务,会重新扣积分——见 定价与积分。