Tasks & Polling
Sync vs async generation, task lifecycle, and how to poll for results
Tasks & Polling
Every generation is a task. You create it with POST /api/v1/3d/generations, then read its state with GET /api/v1/tasks/{taskId}.
The one decision that matters up front is whether you wait for it or poll for it.
Sync vs async
mode: "sync" | mode: "async" (default) | |
|---|---|---|
| Response status | 200 | 202 Accepted |
| Response when the model is ready | Full result (status: "completed") | status: "pending", no result yet |
| Longest a single request waits | 55 seconds | returns immediately |
| When the model takes longer than the wait | 200 with status: "running" | — |
| Good for | interactive tools, one-shot scripts | queues, batch jobs, anything behind a webhook you control |
mode: "sync" is capped at 55 seconds. Generations that take longer do
not fail — the response comes back with status: "running" and a message
telling you to poll. Your client must still handle polling in sync mode,
which is why most integrations just start with mode: "async".
Async: create, then poll
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"Sync: the same task, awaited
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"
}'If the model finishes inside the 55-second window you get the completed payload directly. Otherwise:
{
"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."
}Task states
pending ──▶ running ──▶ completed
└─▶ failedstatus | Meaning | Has data? |
|---|---|---|
pending | Queued, not picked up yet | no |
running | Generation in progress | no |
completed | Finished; the model URL is in data | yes |
failed | Generation failed; see error | no |
While a task is in flight the response also carries progress (0–100) and
progress_stage (a human-readable stage label), which is enough to drive a
progress bar.
Reading a result
{
"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 is a downloadable URL — fetch it and store the file wherever
you need it. It is not guaranteed to stay valid forever, so don't persist the
URL as your only copy of the asset.
Reading a failure
{
"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
}
}A failed generation is refunded, and usage.credits_refunded is present when
the refund happened. Treat the refund as best-effort bookkeeping: always read
the balance from usage.credits_remaining rather than subtracting locally.
Polling pattern
Poll no faster than once every 2 seconds — the API has no webhook or callback, so polling is the only way to observe progress.
async function waitForTask(taskId: string, apiKey: string) {
const deadline = Date.now() + 5 * 60 * 1000; // 5 minute ceiling
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) {
// Back off on rate limiting instead of hammering the endpoint.
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);
// gentle backoff: 2s → 3s → 4.5s, capped at 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")Edge cases
- Task not found or not yours →
404withtype: "not_found_error". Tasks are scoped to the API key's account, so another account'staskIdis indistinguishable from a nonexistent one. - Polling too fast →
429withRetry-After. Each poll counts against the same 60 requests/minute budget as your generation calls, so a tight poll loop on many concurrent tasks will starve itself. - Retrying a failed generation is a new task and consumes credits again — see Pricing & Credits.