# Trellis 2 API

> Transforme une image unique en maillage 3D GLB texturé avec réglages ajustables de structure, de forme, de texture et d’UV

Construit une ressource 3D à partir d’une image (`image_url`) et renvoie un fichier GLB. `resolution` vaut 512, 1024 ou 1536, et `texture_size` vaut 1024, 2048 ou 4096. Chacune des trois étapes (structure, forme, texture) possède ses propres contrôles de guidage et d’étapes d’échantillonnage. `decimation_target` définit le nombre de sommets du maillage (5,000 à 2,000,000), et des options de remeshing et de dépliage UV sont disponibles.

- 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/fr/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 |  |  | Graine utilisée pour une génération aléatoire reproductible. |
| `resolution` |  | enum (integer) | no | `1024` | `512`, `1024`, `1536` | Résolution de la sortie ; l’augmenter ajoute des détails mais prend plus de temps. |
| `ss_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Contrôle initial de fidélité de la structure 3D : l’augmenter favorise une correspondance plus étroite avec l’image d’entrée au risque d’ajouter du bruit. |
| `ss_guidance_rescale` |  | number | no | `0.7` | 0 – 1 | Contrôle des artefacts de guidage de l’étape 1, privilégiant des effets de guidage plus forts avec des réglages faibles et une sortie plus stable avec des réglages élevés. |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Début de la fenêtre de guidage sans classifieur de l’étape 1 (structure clairsemée), exprimé comme fraction du débruitage. Des valeurs plus faibles commencent le guidage plus tôt ; seul l’intervalle de interval_start à interval_end utilise le guidage, le reste étant traité sans guidage. |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Limite du guidage de l’étape 1 (structure clairsemée) : choisissez une valeur au moins égale à ss_guidance_interval_start. Elle indique la fraction du débruitage atteinte lorsque le guidage sans classifieur s’arrête. |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | Nombre d’étapes de débruitage de la structure initiale : les gains de qualité potentiels liés à des étapes supplémentaires s’accompagnent d’un traitement plus lent. |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | Définissez la netteté des transitions via le calendrier de bruit de génération de la structure : augmenter cette valeur rend les transitions plus nettes. |
| `shape_slat_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Contrôle de fidélité de la géométrie détaillée : une meilleure adhérence à l’image d’entrée produit davantage de détails, avec un risque de bruit supplémentaire. |
| `shape_slat_guidance_rescale` |  | number | no | `0.5` | 0 – 1 | Augmentez ce paramètre lorsque la géométrie semble bruitée : il réduit les artefacts causés par un guidage fort lors de l’étape de forme. |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Point d’activation du guidage sans classifieur pour l’affinement de la forme à l’étape 2. Exprimé comme fraction de la progression du débruitage, il définit interval_start ; le guidage ne s’applique que dans la fenêtre délimitée par interval_start et interval_end. |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Limite du guidage de l’étape 2 (affinement de la forme) : choisissez une valeur au moins égale à shape_slat_guidance_interval_start. Elle indique la fraction du débruitage atteinte lorsque le guidage sans classifieur s’arrête. |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Nombre d’étapes de débruitage du raffinement de la forme : une géométrie potentiellement plus lisse se fait au détriment de la vitesse lorsque des étapes supplémentaires sont utilisées. |
| `shape_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Définissez la netteté des détails géométriques via le calendrier de bruit du raffinement de la forme ; augmenter cette valeur produit des détails plus nets. |
| `tex_slat_guidance_strength` |  | number | no | `1` | 0 – 10 | Contrôle de fidélité des couleurs de texture : une adhérence plus étroite aux couleurs de l’image d’entrée avec des réglages élevés augmente l’intensité, mais peut provoquer une sursaturation. |
| `tex_slat_guidance_rescale` |  | number | no | `0` | 0 – 1 | Augmentez ce paramètre pour corriger les textures bruitées ou les bandes de couleur : il réduit les artefacts causés par un guidage fort lors de l’étape de texture. |
| `tex_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Point d’activation du guidage sans classifieur pour la génération de texture à l’étape 3. Exprimé comme fraction de la progression du débruitage, il définit interval_start ; le guidage ne s’applique que dans la fenêtre délimitée par interval_start et interval_end. |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | Limite du guidage de l’étape 3 (texture) : choisissez une valeur au moins égale à tex_slat_guidance_interval_start. Elle indique la fraction du débruitage atteinte lorsque le guidage sans classifieur s’arrête. |
| `tex_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Nombre d’étapes de débruitage utilisées pour générer les textures. Augmenter ce nombre prend plus de temps, mais peut produire des textures plus propres. |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Définissez la netteté des détails de texture via le calendrier de bruit de génération de texture ; augmenter cette valeur produit des détails plus nets. |
| `decimation_target` |  | integer | no | `500000` | 5,000 – 2,000,000 | Nombre cible de sommets du maillage : 500k est recommandé pour une utilisation générale et 20k–50k pour le web/mobile. Réduire la cible sacrifie des détails du maillage au profit de fichiers plus petits. |
| `texture_size` |  | enum (integer) | no | `2048` | `1024`, `2048`, `4096` | Résolution de texture du maillage pour la cuisson. Une résolution accrue offre des détails de surface plus fins, mais produit des fichiers plus volumineux. |
| `remesh` |  | boolean | no | `true` |  | Reconstruction de la topologie créant des triangles de maillage plus propres, ce qui améliore généralement l’utilisation ultérieure, comme l’animation ou l’impression 3D, au prix d’un traitement plus lent. |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Marge de déplacement du rem maillage : un lissage supplémentaire peut sacrifier les détails fins lorsque cette valeur augmente. Le réglage limite le déplacement des sommets par rapport à la surface d’origine. |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Intensité de projection des sommets rem aillés vers la surface d’origine : 1 préserve les détails grâce à une projection complète, tandis que 0 désactive la projection pour un résultat plus lisse. |
| `uv_unwrap_angle_threshold_deg` |  | number | no | `90` | 0 – 180 | Limite d’angle des chartes UV en degrés, restreignant l’écart entre les normales de faces voisines au sein d’une charte. Une limite plus élevée favorise des chartes moins nombreuses et plus grandes, au risque d’étirements ; une limite plus faible favorise davantage de chartes et moins de distorsion. |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | Nombre de passes d’affinement local utilisées pour calculer les chartes UV. |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | L’équilibre des chartes UV peut être amélioré en augmentant ce nombre de passes de regroupement global utilisées pour calculer les chartes. |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | Ajuste l’intensité du lissage des bords des chartes UV ; des raccords moins visibles avec des valeurs élevées comportent un risque de distorsion UV. |
| `image_url` | `image` | string (image URL) | yes |  |  | URL pointant vers l’image source pour la conversion 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} | Modèle 3D généré au 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