# Trellis 2 API

> ایک تصویر کو ٹیکسچر شدہ GLB 3D میش میں تبدیل کرتا ہے، ساخت، شکل، ٹیکسچر اور UV سیٹنگز کے قابل ایڈجسٹ کنٹرولز کے ساتھ

ایک تصویر (`image_url`) سے 3D اثاثہ بناتا ہے اور GLB فائل واپس کرتا ہے۔ `resolution` 512، 1024 یا 1536 ہے، جبکہ `texture_size` 1024، 2048 یا 4096 ہے۔ تینوں مراحل (ساخت، شکل، ٹیکسچر) کے لیے الگ رہنمائی اور سیمپلنگ-مرحلے کے کنٹرولز ہیں۔ `decimation_target` میش کے ورٹیکس کی تعداد مقرر کرتا ہے (5,000 سے 2,000,000)، جبکہ ری میشنگ اور 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.com/v1/run/trellis-2`
- Quote: `POST https://api.doitong.com/v1/quote/trellis-2`
- Docs page: https://doitong.com/ur/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.com/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۔ |
| `resolution` |  | enum (integer) | no | `1024` | `512`, `1024`, `1536` | آؤٹ پٹ کا ریزولوشن؛ اسے بڑھانے سے تفصیل میں اضافہ ہوتا ہے مگر زیادہ وقت لگتا ہے۔ |
| `ss_guidance_strength` |  | number | no | `7.5` | 0 – 10 | ابتدائی 3D ساخت کی fidelity control؛ اسے بڑھانے سے اضافی noise کے خطرے کے ساتھ ان پٹ تصویر سے زیادہ مشابہت حاصل ہوتی ہے۔ |
| `ss_guidance_rescale` |  | number | no | `0.7` | 0 – 1 | مرحلہ 1 کی guidance-artifact control؛ کم ترتیبات پر مضبوط گائیڈنس اثرات اور زیادہ ترتیبات پر زیادہ مستحکم آؤٹ پٹ کے درمیان توازن۔ |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | مرحلہ 1 (sparse structure) میں classifier-free guidance ونڈو کی ابتدائی حد، denoising fraction کے طور پر۔ کم سیٹنگ guidance جلد شروع کرتی ہے؛ صرف interval_start سے interval_end تک کا وقفہ guidance استعمال کرتا ہے، باقی جگہ unguided processing ہوتی ہے۔ |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | مرحلہ 1 (sparse structure) کے لیے guidance cutoff: ایسی قدر منتخب کریں جو ss_guidance_interval_start سے کم نہ ہو۔ یہ قدر اس denoising fraction کی نشاندہی کرتی ہے جہاں classifier-free guidance رکتی ہے۔ |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | ابتدائی ساخت کی ڈینوائزنگ تعداد؛ اضافی اسٹیپس سے ممکنہ معیار میں بہتری کے ساتھ پروسیسنگ سست ہو جاتی ہے۔ |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | ساخت تخلیق کرنے والے noise schedule کے ذریعے transition sharpness مقرر کریں؛ قدر بڑھانے سے transitions زیادہ تیز ہوتے ہیں۔ |
| `shape_slat_guidance_strength` |  | number | no | `7.5` | 0 – 10 | تفصیلی جیومیٹری کی fidelity control؛ ان پٹ تصویر سے زیادہ مطابقت اضافی noise کے خطرے کے ساتھ مزید تفصیل پیدا کرتی ہے۔ |
| `shape_slat_guidance_rescale` |  | number | no | `0.5` | 0 – 1 | جب جیومیٹری noisy نظر آئے تو یہ ترتیب بڑھائیں؛ یہ shape مرحلے میں مضبوط گائیڈنس سے پیدا ہونے والے artifacts کم کرتی ہے۔ |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | مرحلہ 2 میں shape refinement کے لیے classifier-free guidance کا activation point۔ denoising progress کے fraction کے طور پر interval_start مقرر کرتا ہے؛ guidance صرف interval_start اور interval_end کی حدود والی ونڈو میں چلتی ہے۔ |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | مرحلہ 2 (shape refinement) کے لیے guidance cutoff: ایسی قدر منتخب کریں جو shape_slat_guidance_interval_start سے کم نہ ہو۔ یہ وہ denoising fraction ہے جہاں classifier-free guidance رکتی ہے۔ |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Shape-refinement ڈینوائزنگ تعداد؛ اضافی اسٹیپس استعمال کرنے پر ممکنہ طور پر ہموار جیومیٹری کے بدلے رفتار کم ہوتی ہے۔ |
| `shape_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Shape-refinement noise schedule کے ذریعے جیومیٹرک تفصیل کی sharpness مقرر کریں؛ قدر بڑھانے سے تفصیلات زیادہ تیز ہوتی ہیں۔ |
| `tex_slat_guidance_strength` |  | number | no | `1` | 0 – 10 | ٹیکسچر کے رنگ کی fidelity control؛ زیادہ ترتیبات پر ان پٹ تصویر کے رنگوں سے زیادہ مطابقت vividness بڑھاتی ہے مگر oversaturation پیدا کر سکتی ہے۔ |
| `tex_slat_guidance_rescale` |  | number | no | `0` | 0 – 1 | شور والے ٹیکسچرز یا color banding سے نمٹنے کے لیے یہ ترتیب بڑھائیں؛ یہ ٹیکسچر مرحلے میں مضبوط گائیڈنس سے پیدا ہونے والے artifacts کم کرتی ہے۔ |
| `tex_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | مرحلہ 3 میں texture تخلیق کے لیے classifier-free guidance کا activation point۔ denoising progress کے fraction کے طور پر interval_start مقرر کرتا ہے؛ guidance صرف interval_start اور interval_end کے درمیان چلتی ہے۔ |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | مرحلہ 3 (texture) کے لیے guidance cutoff: ایسی قدر منتخب کریں جو tex_slat_guidance_interval_start سے کم نہ ہو۔ یہ وہ denoising fraction ہے جہاں classifier-free guidance رکتی ہے۔ |
| `tex_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | ٹیکسچرز تخلیق کرنے کے لیے استعمال ہونے والے ڈینوائزنگ اسٹیپس کی تعداد۔ تعداد بڑھانے سے زیادہ وقت لگتا ہے مگر صاف تر ٹیکسچرز حاصل ہو سکتے ہیں۔ |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | ٹیکسچر تخلیق کے noise schedule کے ذریعے ٹیکسچر تفصیل کی sharpness مقرر کریں؛ قدر بڑھانے سے تفصیلات زیادہ تیز ہوتی ہیں۔ |
| `decimation_target` |  | integer | no | `500000` | 5,000 – 2,000,000 | Mesh vertex-count کا ہدف؛ عمومی استعمال کے لیے 500k اور web/mobile کے لیے 20k–50k تجویز کردہ ہیں۔ ہدف کم کرنے سے mesh detail کے بدلے چھوٹی فائلیں بنتی ہیں۔ |
| `texture_size` |  | enum (integer) | no | `2048` | `1024`, `2048`, `4096` | بیکنگ کے لیے mesh ٹیکسچر ریزولوشن۔ ریزولوشن بڑھانے پر سطح کی باریک تفصیل کے ساتھ بڑی فائلیں بنتی ہیں۔ |
| `remesh` |  | boolean | no | `true` |  | Topology rebuilding، جو زیادہ صاف mesh triangles بناتی ہے اور عموماً animation یا 3D printing جیسے بعد کے استعمال کے لیے موزونیت بہتر کرتی ہے، مگر پروسیسنگ سست ہو جاتی ہے۔ |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Remeshing movement allowance؛ قدر بڑھانے سے اضافی smoothing باریک تفصیل کم کر سکتی ہے۔ یہ سیٹنگ اصل سطح کے مقابلے میں vertex displacement محدود کرتی ہے۔ |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Remeshed vertices کو اصل سطح پر واپس لانے کی projection strength: 1 مکمل projection کے ذریعے detail برقرار رکھتا ہے، جبکہ 0 projection بند کر کے زیادہ ہموار نتیجہ دیتا ہے۔ |
| `uv_unwrap_angle_threshold_deg` |  | number | no | `90` | 0 – 180 | UV chart angle limit، ڈگری میں؛ ایک chart کے اندر پڑوسی face normals کے فرق کو محدود کرتا ہے۔ حد بڑھانے سے کم اور بڑے charts بنتے ہیں مگر stretching کا خطرہ بڑھتا ہے؛ کم کرنے سے زیادہ charts اور کم distortion بنتی ہے۔ |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | UV charts کا حساب کرنے کے لیے استعمال ہونے والے local refinement passes کی تعداد۔ |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | UV chart بیلنس کو charts کے حساب کے لیے استعمال ہونے والے global clustering passes کی تعداد بڑھا کر بہتر کیا جا سکتا ہے۔ |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | UV chart edges کی smoothing کی شدت ایڈجسٹ کریں؛ زیادہ سیٹنگ پر کم نمایاں seams کے ساتھ UV distortion کا خطرہ ہوتا ہے۔ |
| `image_url` | `image` | string (image URL) | yes |  |  | 3D تبدیلی کے لیے ماخذ تصویر کی طرف اشارہ کرنے والا URL۔ |

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.com/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.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/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.com/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.com/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.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `model_glb` | object {url, content_type, file_name, file_size} | GLB فارمیٹ میں تیار کردہ 3D ماڈل۔ |

## 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.com/v1/models/trellis-2