Trellis v2 API Documentation

https://gateway.pixazo.ai/trellis-2-image-to-3d/v1/trellis-2-image-to-3d-request

Authentication

All requests require an API key passed via header.

Header	Type	Required	Description
Ocp-Apim-Subscription-Key	string	Yes	Your API subscription key

Trellis 2 Image to 3D generate request - Trellis 2 Image to 3D API

Request Code

POST https://gateway.pixazo.ai/trellis-2-image-to-3d/v1/trellis-2-image-to-3d-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png",
  "resolution": 1024,
  "ss_guidance_strength": 7.5,
  "ss_guidance_rescale": 0.7,
  "ss_sampling_steps": 12,
  "ss_rescale_t": 5,
  "shape_slat_guidance_strength": 7.5,
  "shape_slat_guidance_rescale": 0.5,
  "shape_slat_sampling_steps": 12,
  "shape_slat_rescale_t": 3,
  "tex_slat_guidance_strength": 1,
  "tex_slat_sampling_steps": 12,
  "tex_slat_rescale_t": 3,
  "decimation_target": 500000,
  "texture_size": 2048,
  "remesh": true,
  "remesh_band": 1
}

import requests

url = "https://gateway.pixazo.ai/trellis-2-image-to-3d/v1/trellis-2-image-to-3d-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png",
    "resolution": 1024,
    "ss_guidance_strength": 7.5,
    "ss_guidance_rescale": 0.7,
    "ss_sampling_steps": 12,
    "ss_rescale_t": 5,
    "shape_slat_guidance_strength": 7.5,
    "shape_slat_guidance_rescale": 0.5,
    "shape_slat_sampling_steps": 12,
    "shape_slat_rescale_t": 3,
    "tex_slat_guidance_strength": 1,
    "tex_slat_sampling_steps": 12,
    "tex_slat_rescale_t": 3,
    "decimation_target": 500000,
    "texture_size": 2048,
    "remesh": True,
    "remesh_band": 1
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const url = 'https://gateway.pixazo.ai/trellis-2-image-to-3d/v1/trellis-2-image-to-3d-request';

const data = {
  image_url: 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png',
  resolution: 1024,
  ss_guidance_strength: 7.5,
  ss_guidance_rescale: 0.7,
  ss_sampling_steps: 12,
  ss_rescale_t: 5,
  shape_slat_guidance_strength: 7.5,
  shape_slat_guidance_rescale: 0.5,
  shape_slat_sampling_steps: 12,
  shape_slat_rescale_t: 3,
  tex_slat_guidance_strength: 1,
  tex_slat_sampling_steps: 12,
  tex_slat_rescale_t: 3,
  decimation_target: 500000,
  texture_size: 2048,
  remesh: true,
  remesh_band: 1
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

curl -X POST "https://gateway.pixazo.ai/trellis-2-image-to-3d/v1/trellis-2-image-to-3d-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png",
    "resolution": 1024,
    "ss_guidance_strength": 7.5,
    "ss_guidance_rescale": 0.7,
    "ss_sampling_steps": 12,
    "ss_rescale_t": 5,
    "shape_slat_guidance_strength": 7.5,
    "shape_slat_guidance_rescale": 0.5,
    "shape_slat_sampling_steps": 12,
    "shape_slat_rescale_t": 3,
    "tex_slat_guidance_strength": 1,
    "tex_slat_sampling_steps": 12,
    "tex_slat_rescale_t": 3,
    "decimation_target": 500000,
    "texture_size": 2048,
    "remesh": true,
    "remesh_band": 1
  }'

Output

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "trellis-2-image-to-3d",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.glb"
    ],
    "media_type": "model/glb"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "trellis-2-image-to-3d",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Trellis 2 Image to 3D generate request

Parameter	Required	Type	Default	Allowed values / range	Description
image_url	Yes	string	—	—	URL of the input 2D image to convert into a 3D model. Must be publicly accessible.
seed	No	integer	—	—	Random seed for reproducibility. Omit for a random result; reuse the same seed with identical inputs to regenerate the same 3D model.
resolution	No	integer	1024	512, 1024, 1536	Output resolution of the initial 3D generation pass. Higher values are slower but more detailed.
ss_guidance_strength	No	number	7.5	0–10	How closely the initial 3D structure follows the input image. Higher values are more faithful but can look noisier.
ss_guidance_rescale	No	number	0.7	0–1	Dampens artifacts caused by strong guidance in the structure stage. Higher values stabilise the output; lower values let the guidance act more strongly.
ss_guidance_interval_start	No	number	0.6	0–1	Fraction of the denoising process at which guidance starts for the structure stage. Guidance is applied only between the start and end values.
ss_guidance_interval_end	No	number	1	0–1	Fraction of the denoising process at which guidance ends for the structure stage. Must be greater than or equal to ss_guidance_interval_start.
ss_sampling_steps	No	integer	12	1–50	Number of denoising steps used to build the model's basic shape. More steps improve quality but take longer.
ss_rescale_t	No	number	5	1–6	Controls the sharpness of the noise schedule for structure generation. Higher values produce sharper transitions.
shape_slat_guidance_strength	No	number	7.5	0–10	How closely the detailed geometry follows the input image. Higher values add more detail but may introduce noise.
shape_slat_guidance_rescale	No	number	0.5	0–1	Dampens artifacts caused by strong guidance in the shape stage. Increase it if the geometry looks noisy.
shape_slat_guidance_interval_start	No	number	0.6	0–1	Fraction of the denoising process at which guidance starts for the shape-refinement stage.
shape_slat_guidance_interval_end	No	number	1	0–1	Fraction of the denoising process at which guidance ends for the shape-refinement stage. Must be greater than or equal to shape_slat_guidance_interval_start.
shape_slat_sampling_steps	No	integer	12	1–50	Number of denoising steps used while refining the model's shape. More steps give smoother geometry but take longer.
shape_slat_rescale_t	No	number	3	1–6	Controls the sharpness of the noise schedule for shape refinement. Higher values produce sharper geometric detail.
tex_slat_guidance_strength	No	number	1	0–10	How closely the texture follows the colours of the input image. Higher values are more vivid but can look oversaturated.
tex_slat_guidance_rescale	No	number	0	0–1	Dampens artifacts caused by strong guidance in the texture stage. Increase it if textures look noisy or show colour banding.
tex_slat_guidance_interval_start	No	number	0.6	0–1	Fraction of the denoising process at which guidance starts for the texture stage.
tex_slat_guidance_interval_end	No	number	0.9	0–1	Fraction of the denoising process at which guidance ends for the texture stage. Must be greater than or equal to tex_slat_guidance_interval_start.
tex_slat_sampling_steps	No	integer	12	1–50	Number of denoising steps used to generate the surface texture. More steps give cleaner textures but take longer.
tex_slat_rescale_t	No	number	3	1–6	Controls the sharpness of the noise schedule for texture generation. Higher values produce sharper texture detail.
decimation_target	No	integer	500000	5000–2000000	Target number of vertices in the final mesh. Lower values produce smaller files with less detail; 500,000 suits most uses, 20,000–50,000 is better for web or mobile.
texture_size	No	integer	2048	1024, 2048, 4096	Resolution of the texture image baked onto the mesh. Higher values capture finer surface detail but produce larger files.
remesh	No	boolean	true	true, false	Rebuilds the mesh topology for cleaner triangles. Slower, but usually better for downstream use such as animation or 3D printing.
remesh_band	No	number	1	0–4	How far remeshing may move vertices from the original surface. Higher values allow more smoothing but can lose fine detail.
remesh_project	No	number	0	0–1	How much the remeshed vertices are projected back onto the original surface. 0 = no projection (smoother), 1 = full projection (preserves detail).
uv_unwrap_angle_threshold_deg	No	number	90	0–180	Maximum angle (in degrees) between adjacent faces allowed within a single UV chart. Lower values create more charts with less distortion.
uv_unwrap_refine_iterations	No	integer	0	0–10	Number of local refinement passes when computing UV charts. Higher values give cleaner chart boundaries but add processing time.
uv_unwrap_global_iterations	No	integer	1	1–10	Number of global clustering passes when computing UV charts. More passes produce more balanced charts.
uv_unwrap_smooth_strength	No	number	1	0–10	Smoothing strength applied to UV chart boundaries. Higher values reduce visible seams but may distort the UV layout.

Content Item Types & Limits

Type	Max	Format / Size	Description
image	1	JPG, PNG, WEBP	2D image to convert to 3D.

Example Request

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png",
  "resolution": 1024,
  "ss_guidance_strength": 7.5,
  "ss_guidance_rescale": 0.7,
  "ss_sampling_steps": 12,
  "ss_rescale_t": 5,
  "shape_slat_guidance_strength": 7.5,
  "shape_slat_guidance_rescale": 0.5,
  "shape_slat_sampling_steps": 12,
  "shape_slat_rescale_t": 3,
  "tex_slat_guidance_strength": 1,
  "tex_slat_sampling_steps": 12,
  "tex_slat_rescale_t": 3,
  "decimation_target": 500000,
  "texture_size": 2048,
  "remesh": true,
  "remesh_band": 1
}

Response

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

Header	Value
Content-Type	application/json
Cache-Control	no-cache
Ocp-Apim-Subscription-Key	YOUR_SUBSCRIPTION_KEY

Response Handling

Common status codes.

Code	Meaning
202	Accepted — Request queued
400	Bad Request
401	Unauthorized
402	Insufficient Balance
403	Forbidden
429	Too Many Requests
500	Internal Server Error

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'trellis-2-image-to-3d' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "trellis-2-image-to-3d",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

cURL Example

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "trellis-2-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "trellis-2-image-to-3d",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/trellis-2-image-to-3d_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Field	Type	Description
request_id	string	Unique request identifier
status	string	QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_id	string	Model that processed the request
error	string\|null	Error message if failed
output.media_url	array	URLs to generated media (R2 CDN)
output.media_type	string	MIME type of the output
created_at	string	When request was created
completed_at	string\|null	When request completed
polling_url	string	Status URL (initial response only)

Status Values

Status	Description
QUEUED	Request accepted, waiting to be processed
PROCESSING	Being processed by the model
COMPLETED	Done — output contains the result
FAILED	Failed — check error field
ERROR	System error — not charged

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

Send a generate request to the API endpoint
Save the request_id from the response
Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Trellis 2 API, Trellis 3D API: Pricing, Documentation

Models Version

Get $5 Free Credit on First Payment