# Trellis 2 API

> Convierte una sola imagen en una malla 3D GLB texturizada con ajustes configurables de estructura, forma, textura y UV

Construye un recurso 3D a partir de una imagen (`image_url`) y devuelve un archivo GLB. `resolution` es 512, 1024 o 1536, y `texture_size` es 1024, 2048 o 4096. Cada una de las tres etapas (estructura, forma y textura) tiene sus propios controles de guía y pasos de muestreo. `decimation_target` define la cantidad de vértices de la malla (5,000 a 2,000,000), y se exponen opciones de remallado y desenvoltura 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/es-MX/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 |  |  | Semilla utilizada para una generación aleatoria reproducible. |
| `resolution` |  | enum (integer) | no | `1024` | `512`, `1024`, `1536` | Resolución de la salida; aumentarla agrega detalles, pero requiere más tiempo. |
| `ss_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Control de fidelidad de la estructura 3D inicial: aumentarlo favorece una mayor correspondencia con la imagen de entrada, a costa de ruido adicional. |
| `ss_guidance_rescale` |  | number | no | `0.7` | 0 – 1 | Control de artefactos de guía de la etapa 1; los valores bajos favorecen efectos de guía más intensos y los altos una salida más estable. |
| `ss_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Límite inicial de la ventana de orientación sin clasificador en la etapa 1 (estructura dispersa), expresado como una fracción de eliminación de ruido. Los valores menores comienzan la orientación antes; solo el intervalo de interval_start a interval_end usa orientación, y el procesamiento sin orientación se realiza fuera de él. |
| `ss_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Límite de orientación para la etapa 1 (estructura dispersa): elige un valor al menos tan grande como ss_guidance_interval_start. El valor identifica la fracción de eliminación de ruido alcanzada cuando se detiene la orientación sin clasificador. |
| `ss_sampling_steps` |  | integer | no | `12` | 1 – 50 | Cantidad de pasos de eliminación de ruido de la estructura inicial: las posibles mejoras de calidad de pasos adicionales implican un procesamiento más lento. |
| `ss_rescale_t` |  | number | no | `5` | 1 – 6 | Establece la nitidez de la transición mediante el programa de ruido de generación de estructura: aumentar este valor hace más nítidas las transiciones. |
| `shape_slat_guidance_strength` |  | number | no | `7.5` | 0 – 10 | Control de fidelidad de la geometría detallada: aumentar la correspondencia con la imagen de entrada agrega detalles, con riesgo de ruido adicional. |
| `shape_slat_guidance_rescale` |  | number | no | `0.5` | 0 – 1 | Aumenta esta configuración cuando la geometría se vea ruidosa: reduce los artefactos causados por una guía intensa durante la etapa de forma. |
| `shape_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Punto de activación de la orientación sin clasificador para el refinamiento de forma en la etapa 2. Expresado como una fracción del progreso de eliminación de ruido, establece interval_start; la orientación opera solo dentro de la ventana delimitada por interval_start y interval_end. |
| `shape_slat_guidance_interval_end` |  | number | no | `1` | 0 – 1 | Límite de orientación para la etapa 2 (refinamiento de forma): elige un valor al menos tan grande como shape_slat_guidance_interval_start. El valor identifica la fracción de eliminación de ruido alcanzada cuando se detiene la orientación sin clasificador. |
| `shape_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Cantidad de pasos de eliminación de ruido para el refinamiento de forma: una geometría potencialmente más uniforme reduce la velocidad cuando se usan pasos adicionales. |
| `shape_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Establece la nitidez de los detalles geométricos mediante el programa de ruido de refinamiento de forma; aumentar este valor produce detalles más nítidos. |
| `tex_slat_guidance_strength` |  | number | no | `1` | 0 – 10 | Control de fidelidad del color de la textura: una mayor correspondencia con los colores de la imagen de entrada en valores altos aumenta la viveza, pero puede causar sobresaturación. |
| `tex_slat_guidance_rescale` |  | number | no | `0` | 0 – 1 | Aumenta esta configuración para corregir texturas ruidosas o bandas de color: reduce los artefactos causados por una guía intensa durante la etapa de textura. |
| `tex_slat_guidance_interval_start` |  | number | no | `0.6` | 0 – 1 | Punto de activación de la orientación sin clasificador para la generación de texturas en la etapa 3. Expresado como una fracción del progreso de eliminación de ruido, establece interval_start; la orientación opera solo dentro de la ventana delimitada por interval_start y interval_end. |
| `tex_slat_guidance_interval_end` |  | number | no | `0.9` | 0 – 1 | Límite de orientación para la etapa 3 (textura): elige un valor al menos tan grande como tex_slat_guidance_interval_start. El valor identifica la fracción de eliminación de ruido alcanzada cuando se detiene la orientación sin clasificador. |
| `tex_slat_sampling_steps` |  | integer | no | `12` | 1 – 50 | Cantidad de pasos de eliminación de ruido utilizados para generar texturas. Aumentarla requiere más tiempo, pero puede producir texturas más limpias. |
| `tex_slat_rescale_t` |  | number | no | `3` | 1 – 6 | Establece la nitidez de los detalles de textura mediante el programa de ruido de generación de texturas; aumentar este valor produce detalles más nítidos. |
| `decimation_target` |  | integer | no | `500000` | 5,000 – 2,000,000 | Objetivo de cantidad de vértices de la malla, con 500k recomendado para uso general y 20k–50k para web/móvil. Reducir el objetivo intercambia detalle de malla por archivos más pequeños. |
| `texture_size` |  | enum (integer) | no | `2048` | `1024`, `2048`, `4096` | Resolución de textura de la malla para el horneado. Un mayor detalle de superficie implica archivos más grandes cuando se aumenta esta resolución. |
| `remesh` |  | boolean | no | `true` |  | Reconstrucción de la topología que crea triángulos de malla más limpios y normalmente mejora la adecuación para usos posteriores, como animación o impresión 3D, a cambio de un procesamiento más lento. |
| `remesh_band` |  | number | no | `1` | 0 – 4 | Margen de movimiento del remallado: un suavizado adicional puede sacrificar detalles finos al aumentar este valor. La configuración limita el desplazamiento de los vértices respecto de la superficie original. |
| `remesh_project` |  | number | no | `0` | 0 – 1 | Intensidad de proyección para devolver los vértices remallados a la superficie original: 1 conserva los detalles mediante una proyección completa, mientras que 0 desactiva la proyección para obtener un resultado más suave. |
| `uv_unwrap_angle_threshold_deg` |  | number | no | `90` | 0 – 180 | Límite de ángulo de las cartas UV en grados, que restringe cuánto pueden diferir las normales de caras vecinas dentro de una carta. Aumentar el límite favorece menos cartas más grandes, con riesgo de estiramiento; reducirlo favorece más cartas y menos distorsión. |
| `uv_unwrap_refine_iterations` |  | integer | no | `0` | 0 – 10 | Cantidad de pasadas de refinamiento local usadas para calcular las cartas UV. |
| `uv_unwrap_global_iterations` |  | integer | no | `1` | 1 – 10 | El equilibrio de las cartas UV puede mejorar al aumentar esta cantidad de pasadas de agrupación global usadas para calcularlas. |
| `uv_unwrap_smooth_strength` |  | number | no | `1` | 0 – 10 | Ajusta la intensidad con la que se suavizan los bordes de las cartas UV; configuraciones más altas reducen las costuras visibles, pero implican riesgo de distorsión UV. |
| `image_url` | `image` | string (image URL) | yes |  |  | URL que apunta a la imagen de origen para la conversión 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} | Modelo 3D generado en formato 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