API REFERENCE

API documentation

Generate 3D models from images or text, and auto-rig GLB models, using the same engine that powers the to3D studio. Authenticate every request with an API key from your dashboard. Usage is billed from your account balance — top up on the billing page.

Get an API key

Authentication

Send your key in the x-api-key header. Keys are account-scoped; anyone holding a key can spend that account's balance, so keep it secret and revoke leaked keys immediately.

curl https://api.to3d.app/api/trellis/tasks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_type":"image-to-3d","input":{"image":"https://example.com/photo.png"}}'

Pricing

Endpoint	Task	Price per task
/api/trellis/tasks	image-to-3d · text-to-3d	$0.04
/api/skin_tokens/tasks	rig	$0.30

The charge is reserved when a task is accepted and refunded automatically if the task fails or is cancelled before completion.

3D generation — Trellis

POST /api/trellis/tasks

Create a generation task. Returns 202 with the task object.

{
  "task_type": "image-to-3d",        // or "text-to-3d"
  "input": {
    "image": "https://…/photo.png",  // image-to-3d: URL or base64; PNG/JPG/GIF, up to 128 MB
    "prompt": "a red vintage car",   // text-to-3d
    "seed": 42,                      // optional, default random
    "ss_sampling_steps": 12,         // optional advanced knobs
    "slat_sampling_steps": 12,
    "ss_guidance_strength": 7.5,
    "slat_guidance_strength": 3.0
  }
}

Response (same shape for every task endpoint):

{
  "id": "0b56a3fe-…",
  "status": "pending",               // pending → processing → succeeded | failed | canceled
  "task_type": "image-to-3d",
  "input": { … },
  "output": {                        // present once status = succeeded
    "model_file": "https://storage.to3d.app/tasks/…/model.glb",
    "no_background_image": "https://…",
    "combined_video": "https://…"
  },
  "error": { "code": "…", "message": "…" },   // present when failed
  "created_at": "…", "updated_at": "…"
}

GET /api/trellis/tasks/:id

Poll task status. Output files are stored permanently on our storage — the URLs do not expire.

POST /api/trellis/tasks/:id/cancel

Cancel a queued task. Tasks already completed cannot be cancelled (409).

Auto-rigging — Skin Tokens

POST /api/skin_tokens/tasks

Rig a humanoid GLB model with a skeleton. Typical processing takes several minutes.

{
  "task_type": "rig",
  "input": {
    "model": "https://…/model.glb",  // GLB URL or base64
    "bone_names": "mixamo",          // "original" | "mixamo" | "ue5"
    "seed": 42                       // optional
  }
}

GET /api/skin_tokens/tasks/:id and POST /api/skin_tokens/tasks/:id/cancel work the same way as the Trellis endpoints. The rigged model is returned as output.model_file.

Errors

Status	Code	Meaning
400	invalid_input	Malformed body, unsupported task_type, or bad parameters
401	—	Missing or invalid x-api-key
402	refund_debt_outstanding	The account owes a refunded balance — top up first
404	task_not_found	Unknown task id (tasks are visible only to their own account)
409	insufficient_credits	Balance too low — top up on the billing page
409	task_not_cancellable	Task already finished
413	invalid_input	Request body over 180 MB
503	unavailable / retryable errors	Transient upstream issue — retry with backoff

Quickstart

# 1. create a task
TASK=$(curl -s https://api.to3d.app/api/trellis/tasks \
  -H "x-api-key: $TO3D_KEY" -H "Content-Type: application/json" \
  -d '{"task_type":"image-to-3d","input":{"image":"https://example.com/photo.png"}}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 2. poll until it settles (typically ~90 s)
watch -n 5 "curl -s https://api.to3d.app/api/trellis/tasks/$TASK -H 'x-api-key: $TO3D_KEY' \
  | python3 -m json.tool | grep -E 'status|model_file'"

Need help integrating? Contact support.