# Trellis 2 API

> Chuyển một hình ảnh duy nhất thành lưới 3D GLB có kết cấu với cấu trúc, hình dạng, kết cấu và thiết lập UV có thể điều chỉnh

Tạo tài sản 3D từ một hình ảnh (`image_url`) và trả về tệp GLB. `resolution` là 512, 1024 hoặc 1536, còn `texture_size` là 1024, 2048 hoặc 4096. Mỗi giai đoạn trong ba giai đoạn (cấu trúc, hình dạng, kết cấu) có các điều khiển hướng dẫn và số bước lấy mẫu riêng. `decimation_target` đặt số đỉnh của lưới (5,000 đến 2,000,000), đồng thời cung cấp các tùy chọn tạo lại lưới và tháo UV.

- Model id: `trellis-2`
- Made by: Microsoft
- Category: Image to 3D
- Output: 3d
- Price: from $0.25 / request (cheapest run $0.25 (250 API credits))
- Run: `POST https://api.doitong.ru/v1/run/trellis-2`
- Quote: `POST https://api.doitong.ru/v1/quote/trellis-2`
- Docs page: https://doitong.com/vi/developers/models/trellis-2

## Pricing

Price: **from $0.25 / request** (the lowest tier; the quote prices your exact input). Billed once per request.

Price rules (the first rule that matches the input wins; a parameter you leave out counts as its default):

- When `resolution` = 1024: $0.30 (300 API credits) / request
- When `resolution` = 1536: $0.35 (350 API credits) / request

The full example input below costs $0.30 = 300 API credits (1 request × 300 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/trellis-2` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `seed` |  | integer \| null | no |  |  | Seed dùng để tạo ngẫu nhiên có thể tái tạo. |
| `resolution` |  | enum (integer) | no | `1024` | `512`, `1024`, `1536` | Độ phân giải đầu ra; tăng giá trị sẽ thêm chi tiết nhưng mất nhiều thời gian hơn. |
| `ss_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Điều khiển độ trung thực của cấu trúc 3D ban đầu: tăng giá trị giúp bám sát hình ảnh đầu vào hơn nhưng có nguy cơ tạo thêm nhiễu. |
| `ss_guidance_rescale` |  | number | no | `0.7` | 0 – 1 | Điều khiển hiện tượng do điều hướng ở giai đoạn 1, đánh đổi giữa hiệu ứng điều hướng mạnh hơn ở giá trị thấp và đầu ra ổn định hơn ở giá trị cao. |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Biên bắt đầu của cửa sổ hướng dẫn không dùng bộ phân loại trong giai đoạn 1 (cấu trúc thưa), biểu thị dưới dạng phân số khử nhiễu. Thiết lập thấp hơn sẽ bắt đầu hướng dẫn sớm hơn; chỉ khoảng từ interval_start đến interval_end sử dụng hướng dẫn, các phần còn lại được xử lý không hướng dẫn. |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Điểm dừng hướng dẫn cho giai đoạn 1 (cấu trúc thưa): chọn giá trị ít nhất bằng ss_guidance_interval_start. Giá trị này xác định phân số khử nhiễu đạt được khi hướng dẫn không dùng bộ phân loại dừng. |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | Số lần khử nhiễu của cấu trúc ban đầu: thêm bước có thể cải thiện chất lượng nhưng làm chậm quá trình xử lý. |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | Đặt độ sắc nét của chuyển cảnh thông qua lịch nhiễu tạo cấu trúc: tăng giá trị sẽ làm chuyển cảnh sắc nét hơn. |
| `shape_slat_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Điều khiển độ trung thực của hình học chi tiết: tăng mức bám sát hình ảnh đầu vào sẽ thêm chi tiết nhưng có nguy cơ tạo thêm nhiễu. |
| `shape_slat_guidance_rescale` |  | number | no | `0.5` | 0 – 1 | Tăng thiết lập này khi hình học bị nhiễu: thiết lập làm giảm các hiện tượng do điều hướng mạnh trong giai đoạn tạo hình dạng. |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Điểm kích hoạt hướng dẫn không dùng bộ phân loại cho việc tinh chỉnh hình dạng ở giai đoạn 2. Được biểu thị dưới dạng phân số tiến trình khử nhiễu, giá trị này đặt interval_start; hướng dẫn chỉ hoạt động trong cửa sổ giới hạn bởi interval_start và interval_end. |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Điểm dừng hướng dẫn cho giai đoạn 2 (tinh chỉnh hình dạng): chọn giá trị ít nhất bằng shape_slat_guidance_interval_start. Giá trị này xác định phân số khử nhiễu đạt được khi hướng dẫn không dùng bộ phân loại dừng. |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Số lần khử nhiễu tinh chỉnh hình dạng: thêm bước có thể tạo hình học mượt hơn nhưng làm giảm tốc độ. |
| `shape_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Đặt độ sắc nét của chi tiết hình học thông qua lịch nhiễu tinh chỉnh hình dạng; tăng giá trị sẽ tạo chi tiết sắc nét hơn. |
| `tex_slat_guidance_strength` |  | number | no | `1` | 0 – 10 | Điều khiển độ trung thực màu kết cấu: ở thiết lập cao hơn, việc bám sát màu trong hình ảnh đầu vào làm tăng độ sống động nhưng có thể gây bão hòa quá mức. |
| `tex_slat_guidance_rescale` |  | number | no | `0` | 0 – 1 | Tăng thiết lập này để xử lý kết cấu bị nhiễu hoặc dải màu: thiết lập làm giảm các hiện tượng do điều hướng mạnh trong giai đoạn tạo kết cấu. |
| `tex_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Điểm kích hoạt hướng dẫn không dùng bộ phân loại cho việc tạo kết cấu ở giai đoạn 3. Được biểu thị dưới dạng phân số tiến trình khử nhiễu, giá trị này đặt interval_start; hướng dẫn chỉ hoạt động trong cửa sổ giới hạn bởi interval_start và interval_end. |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | Điểm dừng hướng dẫn cho giai đoạn 3 (kết cấu): chọn giá trị ít nhất bằng tex_slat_guidance_interval_start. Giá trị này xác định phân số khử nhiễu đạt được khi hướng dẫn không dùng bộ phân loại dừng. |
| `tex_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Số bước khử nhiễu dùng để tạo kết cấu. Tăng số bước mất nhiều thời gian hơn nhưng có thể tạo kết cấu sạch hơn. |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Đặt độ sắc nét của chi tiết kết cấu thông qua lịch nhiễu tạo kết cấu; tăng giá trị sẽ tạo chi tiết sắc nét hơn. |
| `decimation_target` |  | integer | no | `500000` | 5,000 – 2,000,000 | Mục tiêu số đỉnh lưới, khuyến nghị 500k cho mục đích chung và 20k–50k cho web/mobile. Giảm mục tiêu sẽ đánh đổi chi tiết lưới để có tệp nhỏ hơn. |
| `texture_size` |  | enum (integer) | no | `2048` | `1024`, `2048`, `4096` | Độ phân giải kết cấu mesh để baking. Tăng độ phân giải tạo chi tiết bề mặt tinh hơn nhưng làm tệp lớn hơn. |
| `remesh` |  | boolean | no | `true` |  | Tái xây dựng topology để tạo các tam giác lưới sạch hơn, thường cải thiện khả năng sử dụng cho các mục đích sau như hoạt hình hoặc in 3D, nhưng xử lý chậm hơn. |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Mức cho phép dịch chuyển khi tạo lại lưới: tăng giá trị này có thể hy sinh chi tiết nhỏ do làm mượt nhiều hơn. Thiết lập này giới hạn độ dịch chuyển của đỉnh so với bề mặt gốc. |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Cường độ chiếu để đưa các đỉnh đã tạo lại lưới về bề mặt gốc: 1 giữ lại chi tiết qua phép chiếu đầy đủ, còn 0 tắt phép chiếu để có kết quả mượt hơn. |
| `uv_unwrap_angle_threshold_deg` |  | number | no | `90` | 0 – 180 | Giới hạn góc chart UV tính bằng độ, hạn chế mức chênh lệch giữa các pháp tuyến mặt kề nhau trong một chart. Tăng giới hạn ưu tiên ít chart lớn hơn nhưng có nguy cơ kéo giãn; giảm giới hạn ưu tiên nhiều chart hơn và ít biến dạng hơn. |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | Số lượt tinh chỉnh cục bộ dùng để tính các chart UV. |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | Có thể cải thiện sự cân bằng chart UV bằng cách tăng số lượt gom cụm toàn cục dùng để tính chart. |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | Điều chỉnh mức làm mượt các cạnh chart UV; thiết lập cao hơn giúp đường nối ít thấy hơn nhưng có nguy cơ gây biến dạng UV. |
| `image_url` | `image` | string (image URL) | yes |  |  | URL trỏ đến hình ảnh nguồn để chuyển đổi 3D. |

File parameters (`image`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "image": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

A fuller example:

```json
{
  "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/trellis-2?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/trellis-2?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/trellis-2", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "trellis-2",
      "input": {
        "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "trellis-2",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 300,
    "usd": "0.30",
    "charged": 300,
    "refunded": 0
  },
  "input": {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  },
  "output": {
    "model_glb": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `model_glb` | object {url, content_type, file_name, file_size} | Mô hình 3D được tạo ở định dạng GLB. |

## Related models

- [Trellis 2 · Retexture](https://doitong.com/developers/models/trellis-2/retexture.md) (`trellis-2/retexture`): from $0.20 / request
- [Trellis](https://doitong.com/developers/models/trellis.md) (`trellis`): $0.02 / request
- [Trellis · Multi](https://doitong.com/developers/models/trellis/multi.md) (`trellis/multi`): $0.02 / request
- [TRELLIS.2 LoRA Inference](https://doitong.com/developers/models/trellis-2-lora.md) (`trellis-2-lora`): from $0.25 / request
- [Hi3D Image to 3D](https://doitong.com/developers/models/hitem3d/hi3d/image-to-3d.md) (`hitem3d/hi3d/image-to-3d`): $0.50 / run
- [Hi3D Image to 3D · v3.0](https://doitong.com/developers/models/hitem3d/hi3d/v3.0/image-to-3d.md) (`hitem3d/hi3d/v3.0/image-to-3d`): from $1.80 / run
- [Hi3D Multiview to 3D · Multi View to 3D](https://doitong.com/developers/models/hitem3d/hi3d/multi-view-to-3d.md) (`hitem3d/hi3d/multi-view-to-3d`): $0.50 / run
- [Hi3D Multiview to 3D · v3.0 · Multi View to 3D](https://doitong.com/developers/models/hitem3d/hi3d/v3.0/multi-view-to-3d.md) (`hitem3d/hi3d/v3.0/multi-view-to-3d`): from $1.80 / run

## Links

- HTML page: https://doitong.com/developers/models/trellis-2
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=trellis-2
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/trellis-2