Getting Started

Getting Started

API

MCP Server

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 status200202 Accepted
Response when the model is readyFull result (status: "completed")status: "pending", no result yet
Longest a single request waits55 secondsreturns immediately
When the model takes longer than the wait200 with status: "running"—
Good forinteractive tools, one-shot scriptsqueues, 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
                    └─▶ failed
statusMeaningHas data?
pendingQueued, not picked up yetno
runningGeneration in progressno
completedFinished; the model URL is in datayes
failedGeneration failed; see errorno

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 → 404 with type: "not_found_error". Tasks are scoped to the API key's account, so another account's taskId is indistinguishable from a nonexistent one.
  • Polling too fast → 429 with Retry-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.

Get Task Status

Interactive reference for the polling endpoint

Rate Limits

Why a poll loop can hit 429

Error Handling

Every error code and what to do about it

Table of Contents

Tasks & Polling
Sync vs async
Async: create, then poll
Sync: the same task, awaited
Task states
Reading a result
Reading a failure
Polling pattern
Edge cases