Name: TRELLIS.2 API: Image to 3D Model Generator (GLB)
Brand: magicapi
SKU: api-magicapi-3d-structured-latents-generation-fishwowater-trellis2
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧊 Image-to-3D Model Generator API (Microsoft TRELLIS.2)

## Overview
TRELLIS.2 is an image-to-3D model from Microsoft. Its developer describes it as "Native and Compact Structured Latents for 3D Generation".

Send one `image` of an object. By default the model removes the background and crops the image, then generates a textured 3D model as a GLB file (`model_file`) and a rendered preview video (`video`). `pipeline_type` trades quality against speed (`512`, `1024`, `1024_cascade` default, `1536_cascade`). `decimation_target` sets the number of faces and `texture_size` the texture resolution of the GLB. Advanced users can tune the steps and guidance of the three generation stages (sparse structure, shape and texture).

## Features
- **Single image to 3D**: one input image produces a textured 3D model.
- **GLB output**: `generate_model` (default `true`) exports a GLB file with up to `decimation_target` faces (100,000 to 2,000,000, default 1,000,000) and textures of `texture_size` pixels (1024 to 8192, default 4096).
- **Preview video**: `generate_video` (default `true`) renders a video of the asset.
- **Automatic preprocessing**: `preprocess_image` removes the background and crops; `return_no_background` also returns that cleaned image.
- **Quality presets**: `pipeline_type` `512`, `1024`, `1024_cascade` or `1536_cascade`.
- **Stage controls**: steps (1 to 50), guidance strength, guidance rescale and rescale T for the sparse structure, shape and texture stages.
- **Seed**: `seed` (default `42`) or `randomize_seed` for a new result each time.

## Use Cases
1. **Game and AR assets**: turn concept art or product photos into GLB models.
2. **E-commerce 3D viewers**: create 3D versions of products from a single photo.
3. **Prototyping**: get a quick 3D draft of an object before modeling it by hand.
4. **Preview renders**: use the rendered video to present the generated object.

## Visual Examples
### Example Input
One object image with all settings at their defaults: `1024_cascade` pipeline, 12 steps per stage, 1,000,000 target faces and 4096-pixel textures, with both the GLB model and the preview video turned on.

![Example input image for TRELLIS.2](https://blog.api.market/wp-content/uploads/2026/10/trellis2-input-api-market.png)

```json
{
  "seed": 42,
  "image": "https://blog.api.market/wp-content/uploads/2026/10/trellis2-input-api-market.png",
  "texture_size": 4096,
  "pipeline_type": "1024_cascade",
  "generate_model": true,
  "generate_video": true,
  "randomize_seed": false,
  "tex_slat_steps": 12,
  "preprocess_image": true,
  "shape_slat_steps": 12,
  "decimation_target": 1000000,
  "tex_slat_rescale_t": 3,
  "return_no_background": false,
  "shape_slat_rescale_t": 3,
  "sparse_structure_steps": 12,
  "tex_slat_guidance_rescale": 0,
  "sparse_structure_rescale_t": 5,
  "tex_slat_guidance_strength": 1,
  "shape_slat_guidance_rescale": 0.5,
  "shape_slat_guidance_strength": 7.5,
  "sparse_structure_guidance_rescale": 0.7,
  "sparse_structure_guidance_strength": 7.5
}
```

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/trellis2-output-2-s0mzy5tt-api-market.mp4) (the rendered preview video).

The request also returned a GLB model file in `model_file` (about 36 MB with the default 1,000,000 faces and 4096-pixel textures). `no_background_image` was `null` because `return_no_background` was off.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Image URL (jpeg, png, gif or webp) to generate the 3D asset from |
| `seed` | integer | No | `42` |  | Random seed for generation |
| `randomize_seed` | boolean | No | `false` |  | Use a random seed instead of seed |
| `preprocess_image` | boolean | No | `true` |  | Preprocess the image: remove the background and crop |
| `return_no_background` | boolean | No | `false` |  | Also return the preprocessed image without its background |
| `generate_video` | boolean | No | `true` |  | Generate a rendered preview video |
| `generate_model` | boolean | No | `true` |  | Generate the 3D model file (GLB) |
| `pipeline_type` | string | No | `1024_cascade` | `512`, `1024`, `1024_cascade`, `1536_cascade` | Pipeline type: trades quality against speed |
| `sparse_structure_steps` | integer | No | `12` | `1` to `50` | Sparse structure sampling steps. More steps give better quality but are slower |
| `sparse_structure_guidance_strength` | number | No | `7.5` | `0` to `15` | Sparse structure guidance strength |
| `sparse_structure_guidance_rescale` | number | No | `0.7` | `0` to `1` | Sparse structure guidance rescale |
| `sparse_structure_rescale_t` | number | No | `5` | `1` to `6` | Sparse structure rescale T |
| `shape_slat_steps` | integer | No | `12` | `1` to `50` | Shape SLat sampling steps |
| `shape_slat_guidance_strength` | number | No | `7.5` | `0` to `15` | Shape SLat guidance strength |
| `shape_slat_guidance_rescale` | number | No | `0.5` | `0` to `1` | Shape SLat guidance rescale |
| `shape_slat_rescale_t` | number | No | `3` | `1` to `6` | Shape SLat rescale T |
| `tex_slat_steps` | integer | No | `12` | `1` to `50` | Texture SLat sampling steps |
| `tex_slat_guidance_strength` | number | No | `1` | `0` to `15` | Texture SLat guidance strength |
| `tex_slat_guidance_rescale` | number | No | `0` | `0` to `1` | Texture SLat guidance rescale |
| `tex_slat_rescale_t` | number | No | `3` | `1` to `6` | Texture SLat rescale T |
| `decimation_target` | integer | No | `1000000` | `100000` to `2000000` | Target number of faces after decimation. Used only when generate_model is true |
| `texture_size` | integer | No | `4096` | `1024` to `8192` | Texture size in pixels for the GLB export. Used only when generate_model is true |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $1.26 per API unit.
- **1 API unit = 1 request with up to 810 seconds of processing time.** A request that takes longer is billed one unit per started 810-second block (for example, 900 seconds of processing is 2 units, $2.52).
- Higher-quality pipelines, more steps and larger textures take longer and can push a request past 810 seconds.
- **Example cost**: the example (default settings) took 303.8 seconds of processing: 1 API unit = **$1.26**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/3d-structured-latents-generation-fishwowater-trellis2`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 5 seconds and an overall timeout of 1800 seconds (30 minutes) work well. Generation takes minutes: the example took about 304 seconds of processing.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/3d-structured-latents-generation-fishwowater-trellis2/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "52e1ad6852599ea10ce8e257635a3c11485cba51c181ea5173e34d9b2955b226",
    "input": {
      "seed": 42,
      "image": "https://blog.api.market/wp-content/uploads/2026/10/trellis2-input-api-market.png",
      "texture_size": 4096,
      "pipeline_type": "1024_cascade",
      "generate_model": true,
      "generate_video": true,
      "randomize_seed": false,
      "tex_slat_steps": 12,
      "preprocess_image": true,
      "shape_slat_steps": 12,
      "decimation_target": 1000000,
      "tex_slat_rescale_t": 3,
      "return_no_background": false,
      "shape_slat_rescale_t": 3,
      "sparse_structure_steps": 12,
      "tex_slat_guidance_rescale": 0,
      "sparse_structure_rescale_t": 5,
      "tex_slat_guidance_strength": 1,
      "shape_slat_guidance_rescale": 0.5,
      "shape_slat_guidance_strength": 7.5,
      "sparse_structure_guidance_rescale": 0.7,
      "sparse_structure_guidance_strength": 7.5
    }
  }'
```

Response (201 Created):
```json
{
  "id": "s0mzy5tt49rna0d1ccnt6nmc98",
  "version": "52e1ad6852599ea10ce8e257635a3c11485cba51c181ea5173e34d9b2955b226",
  "status": "starting",
  "created_at": "2026-10-22T10:32:28.134Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/3d-structured-latents-generation-fishwowater-trellis2/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "s0mzy5tt49rna0d1ccnt6nmc98",
  "status": "succeeded",
  "output": {
    "model_file": "URL of the generated .glb file",
    "no_background_image": null,
    "video": "https://blog.api.market/wp-content/uploads/2026/10/trellis2-output-2-s0mzy5tt-api-market.mp4"
  },
  "error": null,
  "created_at": "2026-10-22T10:32:28.134Z",
  "started_at": "2026-10-22T11:09:21.142Z",
  "completed_at": "2026-10-22T11:14:24.971Z"
}
```

`output` is an object with three fields: `model_file` (URL of the .glb 3D model), `video` (URL of the MP4 preview) and `no_background_image` (URL of the preprocessed image). A field is `null` when that output was turned off.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image`, a `pipeline_type` that is not in the list or a `texture_size` above 8192.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/3d-structured-latents-generation-fishwowater-trellis2";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "52e1ad6852599ea10ce8e257635a3c11485cba51c181ea5173e34d9b2955b226", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 1800000;
  const pollInterval = 5000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 30 minutes");
}

createAndWaitForPrediction({
    "seed": 42,
    "image": "https://blog.api.market/wp-content/uploads/2026/10/trellis2-input-api-market.png",
    "texture_size": 4096,
    "pipeline_type": "1024_cascade",
    "generate_model": true,
    "generate_video": true,
    "randomize_seed": false,
    "tex_slat_steps": 12,
    "preprocess_image": true,
    "shape_slat_steps": 12,
    "decimation_target": 1000000,
    "tex_slat_rescale_t": 3,
    "return_no_background": false,
    "shape_slat_rescale_t": 3,
    "sparse_structure_steps": 12,
    "tex_slat_guidance_rescale": 0,
    "sparse_structure_rescale_t": 5,
    "tex_slat_guidance_strength": 1,
    "shape_slat_guidance_rescale": 0.5,
    "shape_slat_guidance_strength": 7.5,
    "sparse_structure_guidance_rescale": 0.7,
    "sparse_structure_guidance_strength": 7.5
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/3d-structured-latents-generation-fishwowater-trellis2"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "52e1ad6852599ea10ce8e257635a3c11485cba51c181ea5173e34d9b2955b226", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 1800
    poll_interval = 5
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 30 minutes")


print(create_and_wait_for_prediction({
    "seed": 42,
    "image": "https://blog.api.market/wp-content/uploads/2026/10/trellis2-input-api-market.png",
    "texture_size": 4096,
    "pipeline_type": "1024_cascade",
    "generate_model": True,
    "generate_video": True,
    "randomize_seed": False,
    "tex_slat_steps": 12,
    "preprocess_image": True,
    "shape_slat_steps": 12,
    "decimation_target": 1000000,
    "tex_slat_rescale_t": 3,
    "return_no_background": False,
    "shape_slat_rescale_t": 3,
    "sparse_structure_steps": 12,
    "tex_slat_guidance_rescale": 0,
    "sparse_structure_rescale_t": 5,
    "tex_slat_guidance_strength": 1,
    "shape_slat_guidance_rescale": 0.5,
    "shape_slat_guidance_strength": 7.5,
    "sparse_structure_guidance_rescale": 0.7,
    "sparse_structure_guidance_strength": 7.5
}))
```

## FAQ
- **What file format is the 3D model?**
  - GLB (binary glTF), returned as a URL in `model_file`.
- **How do I make the model file smaller?**
  - Lower `decimation_target` (minimum 100,000 faces) and `texture_size` (minimum 1024). With the defaults the example GLB was about 36 MB.
- **Do I need to remove the background myself?**
  - No. `preprocess_image` (default `true`) removes the background and crops the image. Set `return_no_background` to `true` to get that image back.
- **Can I skip the video or the model?**
  - Yes. Set `generate_video` or `generate_model` to `false`; the matching output field is then `null`.
- **How long does a request take?**
  - Minutes. The example with default settings took about 304 seconds of processing. Poll every few seconds and allow up to 30 minutes.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Generate a textured GLB 3D model and a rendered preview video from a single image with TRELLIS.2, with quality, face count and texture size controls.