Trellis 2 Image To 3d API Documentation

Playground

Try it on WaveSpeedAI!

TRELLIS.2 turns a single image into a textured 3D GLB with PBR materials.

Features

TRELLIS.2 turns a single image into a textured 3D GLB with PBR materials.

Upload a clear image of one object to create a 3D asset for games, visualization or further editing.

Inputs

image: one image URL, data URI or base64 image. Text and multi-view inputs are not supported.
resolution: 512, 1024 or 1536; defaults to 1024.
texture_size: 1024, 2048 or 4096; defaults to 2048.
target_face_count: approximate simplification target, 10,000–1,000,000; defaults to 200,000.
remove_background: remove background before generation; enabled by default.
seed: optional fixed seed; -1 uses a random seed.

Output

One downloadable GLB with embedded UVs, base-color and metallic/roughness textures. Fine lettering, faces and small parts can vary from the input. The mesh is not guaranteed to be watertight.

Pricing

Per successful generation: 512 $0.10, 1024 $0.20, 1536 $0.40. Selecting 4096-pixel textures adds $0.05. Higher resolution and complex objects take longer to generate.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "resolution": "1024",
  "texture_size": 2048,
  "target_face_count": 200000,
  "remove_background": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/trellis-2/image-to-3d" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Parameter	Type	Required	Default	Range	Description
image	string	Yes		-	Single input image URL, data URI or base64 image.
resolution	string	No	1024	512, 1024, 1536	Geometry resolution. Higher resolution takes more time and memory.
texture_size	integer	No	2048	1024, 2048, 4096	PBR texture resolution in pixels.
target_face_count	integer	No	200000	10000 ~ 1000000	Target mesh face count after simplification. The final count is approximate.
remove_background	boolean	No	true	-	Remove the image background before generation. Disable to use existing image alpha.
seed	integer	No	-	-	Random seed. Use -1 for a random seed.
enable_base64_output	boolean	No	false	-	If set to `true`, the prediction's `output` strings are returned as naked base64 (no `data:<mime>;base64,` prefix). When `false` (default), outputs are returned as URLs pointing to our CDN.

Response Parameters

Parameter	Type	Description
code	integer	HTTP status code (e.g., 200 for success)
message	string	Status message (e.g., “success”)
data.id	string	Unique identifier for the prediction, Task Id
data.model	string	Model ID used for the prediction
data.outputs	array	Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not `completed`)
data.urls	object	Object containing related API endpoints
data.status	string	Task status. `completed` is successful; `failed`, `cancelled`, `timeout`, and `deleted` are failure terminal statuses.
data.created_at	string	ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.error	string	Error message (empty if no error occurred)
data.timings	object	Object containing timing details
data.timings.inference	integer	Inference time in milliseconds

Result Request Parameters

Parameter	Type	Required	Default	Description
id	string	Yes	-	Task ID

Result Response Parameters

Parameter	Type	Description
code	integer	HTTP status code (e.g., 200 for success)
message	string	Status message (e.g., “success”)
data	object	The prediction data object containing all details
data.id	string	Unique identifier for the prediction
data.model	string	Model ID used for the prediction
data.outputs	array<string \| object>	Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.
data.urls	object	Object containing related API endpoints
data.status	string	Status: `completed` is successful; `failed`, `cancelled`, `timeout`, and `deleted` are failure terminal statuses
data.created_at	string	ISO timestamp of when the request was created
data.error	string	Error message (empty if no error occurred)
data.timings	object	Object containing timing details
data.timings.inference	integer	Inference time in milliseconds

Overview