# Retexture API

New PBR textures on a model you have, from a reference picture of the look. Given words instead of a picture, a picture model paints the reference first (image_model, its price added). Keeps the shape.

Tool id `retexture` on the REST API (`POST https://3dvalley.com/api/v1/jobs`); MCP tool `edit_model` on https://3dvalley.com/mcp. Paid in credits (1 credit = $0.01), taken when the job starts and given back if it fails. The general rules (keys, idempotency, waiting, webhooks) are in [the API docs](https://3dvalley.com/docs/api).

## Models and prices

| Model | Name | Price | Time | What it is |
|---|---|---|---|---|
| `trellis-2-texture` (default) | TRELLIS.2 Standard | 5 credits | about 30 s | Base colour, roughness and metallic painted onto your mesh from one reference picture. Keeps your UVs, size and position. |
| `trellis-2-texture-pro` | TRELLIS.2 Pro | 10 credits | about 70 s | The same texturing at its highest settings: painted on a finer grid and baked into 4K textures. |
| `tripo-texture` | Tripo Standard | 20 credits | about 60 s | Tripo's texturing model: crisp, consistent PBR materials all the way round, from one reference picture or your words. |
| `tripo-texture-detailed` | Tripo Detailed | 40 credits | about 120 s | Tripo's texturing model at its detailed setting: finer surface detail in the textures, for a longer wait. |
| `meshy-texture` | Meshy 7 | 50 credits | about 690 s | Meshy's texturing model: PBR materials from a picture or straight from your words, on your own UVs. |

## Input

| Field | Required | |
|---|---|---|
| `mesh` | yes | A mesh (GLB, glTF, OBJ, PLY or STL) as an https URL, an upload id (upl_...), a library id (ph:wooden_barrel_01) or an earlier job (job_... or its asset id 3dv:...). |
| `image` | no | The look to paint on. A picture (PNG, JPEG or WebP) as an https URL, a data: URI, an upload id (upl_...) or an earlier job's picture (job_...). |
| `prompt` | no | The look in words, when there is no picture: "weathered bronze with green patina". |

## Options

| Option | Type | Values | |
|---|---|---|---|
| `seed` | integer | from 0 to 2147483647 | Fixes the randomness, so the same input makes the same result. |
| `image_model` | string | `flux-2-klein`, `muse-image`, `gpt-image-2-5` | Paints the reference picture when only a prompt is given. Default `flux-2-klein`. |

## Output

Files: `glb`.

## Example

```
curl -X POST https://3dvalley.com/api/v1/jobs \
  -H "Authorization: Bearer $THREEDVALLEY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=50" \
  -H "Content-Type: application/json" \
  -d '{"tool":"retexture","input":{"mesh":"ph:wooden_barrel_01","prompt":"weathered bronze with green patina"}}'
```

From an MCP client:

```
edit_model({"operation":"retexture","mesh":"ph:wooden_barrel_01","prompt":"weathered bronze with green patina"})
```

## Limits

- `max_image_bytes`: 10,485,760
- `max_mesh_bytes`: 62,914,560