# Trellis 2 API

> Transforma ina singula imagina en ina mesh 3D GLB cun textur e configuraziuns regulablas per structura, furma, textur e UV

Construiescha in asset 3D d'ina imagina (`image_url`) e returnescha ina datoteca GLB. `resolution` è 512, 1024 u 1536; `texture_size` è 1024, 2048 u 4096. Mintgina da las trais staziuns (structura, furma, textur) ha controlls agens per guidance e pass da sampling. `decimation_target` definescha il dumber da vertizels da la mesh (5,000 to 2,000,000); remeshing e deballagi UV èn disponibels.

- 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/rm/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 utilisà per ina generaziun casuala reproducibla. |
| `resolution` |  | enum (integer) | no | `1024` | `512`, `1024`, `1536` | Resoluziun dal output; augmentar ella agiunta detagls, ma dovra dapli temp. |
| `ss_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Controlla la fidelitad da la structura 3D iniziala: augmentar ella favurisescha ina concordanza pli gronda cun il maletg input, cun il ristg da dapli ramur. |
| `ss_guidance_rescale` |  | number | no | `0.7` | 0 – 1 | Controlla ils artifacts da guida dal stadi 1, cun effects da guida pli ferms tar configuraziuns bassas e in output pli stabil tar configuraziuns autas. |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Limita d'inizi da la fanestra da guidance senza classificader en la fasa 1 (structura sparsa), exprimida sco fracziun da reducziun dal ramur. Configuraziuns pli bassas cumenzan la guidance pli baud; mo l'interval tranter interval_start e interval_end utilisescha guidance, entant che l'elavuraziun è senza guidance en il rest. |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Limita da guidance per la fasa 1 (structura sparsa): tscherna ina valur almain uschè gronda sco ss_guidance_interval_start. La valur inditgescha la fracziun da reducziun dal ramur cuntanschida cura che la guidance senza classificader sa fermescha. |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | Dumber da pass da denoising da la structura iniziala: ils pussibels avantatgs da qualitad da pass supplementars vegnan cun in processament pli lent. |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | Definescha la nettezza da la transiziun tras il noise schedule da la generaziun da la structura: augmentar questa valur fa las transiziuns pli nettas. |
| `shape_slat_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Controlla la fidelitad da la geometria detagliada: ina aderenza pli gronda al maletg input dat dapli detagl, cun il ristg da ramur supplementara. |
| `shape_slat_guidance_rescale` |  | number | no | `0.5` | 0 – 1 | Augmenta questa configuraziun sche la geometria para ramurusa: ella reducescha ils artifacts chaschunads da la guida ferma durant il stadi da la furma. |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Punct d'activaziun da la guidance senza classificader per la raffinaziun da la furma en la fasa 2. Exprimì sco fracziun dal progress da reducziun dal ramur, fixescha el interval_start; la guidance funcziuna mo en la fanestra limitada da interval_start e interval_end. |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Limita da guidance per la fasa 2 (raffinaziun da la furma): tscherna ina valur almain uschè gronda sco shape_slat_guidance_interval_start. La valur inditgescha la fracziun da reducziun dal ramur cuntanschida cura che la guidance senza classificader sa fermescha. |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Dumber da pass da denoising per il meglierament da la furma: ina geometria eventualmain pli glischa custa spertadad sch'i vegnan duvrads pass supplementars. |
| `shape_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Definescha la nettezza dal detagl geometric tras il noise schedule dal meglierament da la furma; augmentar questa valur dat detagls pli nets. |
| `tex_slat_guidance_strength` |  | number | no | `1` | 0 – 10 | Controlla la fidelitad da la colur da la textura: ina aderenza pli gronda a las colurs dal maletg input tar configuraziuns autas augmenta la vivacitad, ma po chaschunar sursaturaziun. |
| `tex_slat_guidance_rescale` |  | number | no | `0` | 0 – 1 | Augmenta questa configuraziun per tractar texturas ramurusas u bandas da colur: ella reducescha ils artifacts chaschunads da la guida ferma durant il stadi da la textura. |
| `tex_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Punct d'activaziun da la guidance senza classificader per la generaziun da textura en la fasa 3. Exprimì sco fracziun dal progress da reducziun dal ramur, fixescha el interval_start; la guidance funcziuna mo en la fanestra limitada da interval_start e interval_end. |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | Limita da guidance per la fasa 3 (textura): tscherna ina valur almain uschè gronda sco tex_slat_guidance_interval_start. La valur inditgescha la fracziun da reducziun dal ramur cuntanschida cura che la guidance senza classificader sa fermescha. |
| `tex_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Dumber da pass da denoising utilisads per generar texturas. Augmentar il dumber da pass dovra dapli temp, ma po producir texturas pli nettas. |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Definescha la nettezza dal detagl da la textura tras il noise schedule da la generaziun da texturas; augmentar questa valur dat detagls pli nets. |
| `decimation_target` |  | integer | no | `500000` | 5,000 – 2,000,000 | Finamira dal dumber da vertizels da la rait, cun 500k recumandà per l'ultilisaziun generala e 20k–50k per web/mobile. La reducziun da la finamira baratta detagls da la rait cunter datotecas pli pitschnas. |
| `texture_size` |  | enum (integer) | no | `2048` | `1024`, `2048`, `4096` | Resoluziun da la textura dal mesh per il baking. Detagl da surfatscha pli fin dat datotecas pli grondas sch'igl vegn augmentada questa resoluziun. |
| `remesh` |  | boolean | no | `true` |  | Reconstrucziun da la topologia che crea trianguls da la rait pli nets, normalmain meglierond l'adattaziun a diever posteriur sco animaziun u stampa 3D, a cust da l'elavuraziun pli lenta. |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Margine da moviment per il remeshing: ina glisada supplementara po sacrificar detagls fins sch'esta valur vegn augmentada. La configuraziun limitescha il spustament dals vertizels en relaziun cun la surfatscha originala. |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Forza da la proiecziun per turnar ils vertizels remeshed a la surfatscha originala: 1 mantegna ils detagls tras proiecziun cumpletta, entant che 0 deactivescha la proiecziun per in resultat pli lom. |
| `uv_unwrap_angle_threshold_deg` |  | number | no | `90` | 0 – 180 | Limita d'angul dals charts UV en grads, che limitescha quant fitg che las normallas da fatschas vischinas pon sa differenziar entaifer in chart. Ina limita pli auta preferescha damain charts pli gronds, cun il ristg da stender; ina limita pli bassa preferescha dapli charts e damain distorsiun. |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | Dumber da pass da raffinaziun locals utilisads per calcular charts UV. |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | L'equiliber dal chart UV po vegnir meglierà augmentond quest dumber da pass da clustering globals utilisads per calcular ils charts. |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | Adattescha quant ferm che ils urs dals charts UV vegnan glisads; configuraziuns pli autas reduceschan las giunturas visiblas, ma cun il ristg da distorsiun UV. |
| `image_url` | `image` | string (image URL) | yes |  |  | URL che mussa sin il maletg da funtauna per la conversiun 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.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} | Model 3D generà en format 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.com/v1/models/trellis-2