# Trellis 2 API

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

Construit un élément 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 réglages 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.ru/v1/run/trellis-2`
- Quote: `POST https://api.doitong.ru/v1/quote/trellis-2`
- Docs page: https://doitong.com/fr-CA/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 |  |  | 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 demande 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 meilleure concordance 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, qui privilégie des effets de guidage plus forts avec des valeurs faibles et une sortie plus stable avec des valeurs élevées. |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Début de la fenêtre de guidage sans classifieur à l’étape 1 (structure clairsemée), exprimé comme fraction de réduction du bruit. Des valeurs plus basses commencent le guidage plus tôt ; seul l’intervalle de interval_start à interval_end utilise le guidage, le traitement étant sans guidage ailleurs. |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Seuil d’arrêt du guidage à l’étape 1 (structure clairsemée) : choisissez une valeur au moins égale à ss_guidance_interval_start. Cette valeur indique la fraction de réduction du bruit atteinte lorsque le guidage sans classifieur s’arrête. |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | Nombre de débruitages de la structure initiale : les gains de qualité potentiels liés aux étapes supplémentaires ralentissent le traitement. |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | Définit la netteté de la transition via le programme 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 pendant l’étape de forme. |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Point d’activation du guidage sans classifieur pour le raffinement de la forme à l’étape 2. Exprimé comme fraction de la progression de réduction du bruit, il définit interval_start ; le guidage opère uniquement dans la fenêtre délimitée par interval_start et interval_end. |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Seuil d’arrêt du guidage à l’étape 2 (raffinement de la forme) : choisissez une valeur au moins égale à shape_slat_guidance_interval_start. Cette valeur indique la fraction de réduction du bruit atteinte lorsque le guidage sans classifieur s’arrête. |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Nombre de débruitages 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éfinit la netteté des détails géométriques via le programme 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 meilleure adhérence aux couleurs de l’image d’entrée avec des valeurs élevées augmente l’éclat, mais peut entraîner 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 pendant 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 de réduction du bruit, il définit interval_start ; le guidage opère uniquement dans la fenêtre délimitée par interval_start et interval_end. |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | Seuil d’arrêt du guidage à l’étape 3 (texture) : choisissez une valeur au moins égale à tex_slat_guidance_interval_start. Cette valeur indique la fraction de réduction du bruit 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 nettes. |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Définit la netteté des détails de texture via le programme 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 et le mobile. Réduire la cible diminue les 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’adaptation à des usages ultérieurs comme l’animation ou l’impression 3D, au prix d’un traitement plus lent. |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Amplitude de déplacement lors de la reconstitution du maillage : un lissage supplémentaire peut sacrifier les détails fins lorsque cette valeur augmente. Le paramètre limite le déplacement des sommets par rapport à la surface originale. |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Intensité de projection pour ramener les sommets reconstitués sur la surface originale : 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 cartes UV en degrés, qui restreint la différence entre les normales de faces voisines au sein d’une carte. Augmenter la limite favorise des cartes moins nombreuses et plus grandes, au risque d’étirement ; la réduire favorise davantage de cartes et moins de distorsion. |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | Nombre de passes de raffinement local utilisées pour calculer les cartes UV. |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | L’équilibre des cartes UV peut être amélioré en augmentant le nombre de passes de regroupement global utilisées pour les calculer. |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | Ajuste l’intensité du lissage des bords des cartes 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.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} | 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.ru/v1/models/trellis-2