# auray-serverless/microsoft/trellis-2-4b

`POST https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b` submits; the response carries a `request_id` and the three URLs to use next.

`POST https://auray.run/auray-serverless/microsoft/trellis-2-4b` is the same request run synchronously: the connection is held and the response is the model's OUTPUT, the same document the result URL would have answered. A request that usually takes longer than a run may hold its connection is refused `400 model_not_synchronous` there before anything is charged, naming `expected_seconds` and `wait_ceiling_seconds` — submit it to the queue instead. Past the deadline a run is `504 run_timed_out` with `X-Auray-Request-Timeout-Type: user` — the request is still alive, running and charged or, while it waits to start, not yet charged (`charged` says which) — so poll `status_url` rather than resending, or resend with the same `idempotency_key` to be handed this request again instead of a second one. A run holds one of the connections this platform, this product and your account may keep waiting; with all of them in use it is refused `429 wait_capacity` with `Retry-After` before anything is charged (`charged: false`), and retrying after that pause is safe.

One of Auray's catalogue models, billed once in credits. Whether it runs right now is `GET /v1/catalogue`'s `addresses` (no key needed): `connected` runs; `described` answers `501 model_not_connected` and `paused` `503 model_disabled`, both before anything is charged.

Price: Credits per call (counted as `settings.shapeSlat.steps+settings.sparseStructure.steps+settings.texSlat.steps@36*settings.decimationTarget@500000*settings.textureSize@2048`): 2.669 for settings.resolution=1536; 3 for settings.resolution=512; settings.resolution=1024. Each band has its own least and most a request is counted at. Quoted when you submit, at the most the request can cost; the charge settles to what the job cost and never above the quote.

Fields as published for this model.

Every error code is explained at https://auray.ai/docs/api/errors.

Address: auray-serverless/microsoft/trellis-2-4b
Servers: https://queue.auray.run · https://auray.run
Scope:   3d:write
Auth:    Authorization: Bearer auray_sk_…
API enabled: yes

## Input

- inputs.image (url, required) — Image input (an http(s) URL; upload a local file first and send its read URL).
- inputs.meshFile (url, optional) — 3D model to re-texture (an http(s) URL; upload a local file first and send its read URL). Skips geometry generation and applies new textures using the reference image.
- seed (integer, optional) — Random seed for reproducible generation. When not provided, a random seed is generated in the unsigned 32-bit range. Documented range: 0 to 9,223,372,036,854,776,000.
- settings.resolution (integer, optional, default: 1024, one of: 512, 1024, 1536) — Voxel grid resolution for 3D generation. Higher values capture finer geometric detail.
- settings.alphaMode (string, optional, default: "OPAQUE", one of: "OPAQUE", "BLEND", "MASK") — Material alpha mode for the output mesh.
- settings.decimationTarget (integer, optional, default: 500000) — Target polygon count for mesh simplification. Lower values produce lighter models at the cost of geometric detail. Documented range: 5,000 to 1,000,000.
- settings.dracoCompression.enabled (boolean, optional) — Compress the output GLB geometry with Draco.
- settings.dracoCompression.level (integer, optional, default: 7) — Encoding effort for Draco compression. Higher values reduce file size further but encode more slowly. Documented range: 0 to 10.
- settings.dracoCompression.quantizationNormal (integer, optional, default: 14) — Quantization bits for vertex normals. Higher values produce smoother shading at the cost of file size. Documented range: 8 to 30.
- settings.dracoCompression.quantizationPosition (integer, optional, default: 16) — Quantization bits for vertex positions. Higher values preserve more positional detail at the cost of file size. Documented range: 8 to 30.
- settings.dracoCompression.quantizationTexCoord (integer, optional, default: 14) — Quantization bits for texture coordinates. Higher values keep textures sharper at UV seams at the cost of file size. Documented range: 8 to 30.
- settings.meshCluster.globalIterations (integer, optional, default: 1) — Global iterations for chart clustering. Documented range: 0 to 64.
- settings.meshCluster.refineIterations (integer, optional, default: 0) — Local refinement iterations for chart clustering. Documented range: 0 to 64.
- settings.meshCluster.smoothStrength (integer, optional, default: 1) — Smoothing strength applied during chart clustering. Documented range: 0 to 10.
- settings.meshCluster.thresholdConeHalfAngleRad (number, optional, default: 1.5707963267948966) — Cone half-angle threshold in radians used during UV chart clustering. Documented range: 0 to 3.142.
- settings.remesh (boolean, optional, default: true) — Whether to remesh the output for cleaner topology.
- settings.remeshBand (number, optional, default: 1) — Narrow-band width in voxels used for dual-contouring remeshing. Documented range: up to 16.
- settings.remeshProject (number, optional, default: 0) — Projection factor for snapping remeshed vertices back to the original surface. Documented range: up to 1.
- settings.shapeSlat.steps (integer, optional, default: 12) — Number of denoising steps. More steps improve quality but increase generation time. Documented range: 1 to 50.
- settings.shapeSlat.guidanceIntervalEnd (number, optional, default: 1) — End of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.shapeSlat.guidanceIntervalStart (number, optional, default: 0.6) — Start of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.shapeSlat.guidanceRescale (number, optional, default: 0.5) — Dampens oversaturation from high guidance values. Lower values apply more correction. Documented range: 0 to 1.
- settings.shapeSlat.guidanceStrength (number, optional, default: 7.5) — How closely the output follows the input image. Higher values enforce stricter adherence to the visible geometry. Documented range: 1 to 10.
- settings.shapeSlat.rescaleT (number, optional, default: 3) — Timestep rescaling factor for the sampling schedule. Controls how guidance strength is distributed across steps. Documented range: 1 to 6.
- settings.sparseStructure.steps (integer, optional, default: 12) — Number of denoising steps. More steps improve quality but increase generation time. Documented range: 1 to 50.
- settings.sparseStructure.guidanceIntervalEnd (number, optional, default: 1) — End of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.sparseStructure.guidanceIntervalStart (number, optional, default: 0.6) — Start of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.sparseStructure.guidanceRescale (number, optional, default: 0.7) — Dampens oversaturation from high guidance values. Lower values apply more correction. Documented range: 0 to 1.
- settings.sparseStructure.guidanceStrength (number, optional, default: 7.5) — How closely the output follows the input image. Higher values enforce stricter adherence to the visible geometry. Documented range: 1 to 10.
- settings.sparseStructure.rescaleT (number, optional, default: 5) — Timestep rescaling factor for the sampling schedule. Controls how guidance strength is distributed across steps. Documented range: 1 to 6.
- settings.texSlat.steps (integer, optional, default: 12) — Number of denoising steps. More steps improve quality but increase generation time. Documented range: 1 to 50.
- settings.texSlat.guidanceIntervalEnd (number, optional, default: 0.9) — End of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.texSlat.guidanceIntervalStart (number, optional, default: 0.6) — Start of the sampling schedule fraction over which guidance is applied. Documented range: 0 to 1.
- settings.texSlat.guidanceRescale (number, optional, default: 0) — Dampens oversaturation from high guidance values. Lower values apply more correction. Documented range: 0 to 1.
- settings.texSlat.guidanceStrength (number, optional, default: 1) — How closely the output follows the input image. Higher values enforce stricter adherence to the visible geometry. Documented range: 1 to 10.
- settings.texSlat.rescaleT (number, optional, default: 3) — Timestep rescaling factor for the sampling schedule. Controls how guidance strength is distributed across steps. Documented range: 1 to 6.
- settings.textureFormat (string, optional, default: "WEBP", one of: "WEBP", "PNG") — Texture format for the output mesh.
- settings.textureSize (integer, optional, default: 2048) — Resolution of the output texture map in pixels. Higher values produce finer surface detail. Documented range: 1,024 to 4,096.
- outputType (string, optional, default: "URL", one of: "URL") — 3D output type.
- outputFormat (string, optional, default: "GLB", one of: "GLB") — Specifies the file format of the generated output. The available values depend on the task type and the specific model's capabilities. - \`JPG\`: Best for photorealistic images with smaller file sizes (no transparency). - \`PNG\`: Lossless compression, supports high quality and transparency (alpha channel). - \`WEBP\`: Modern format providing superior compression and transparency support. - \`MP4\`: Widely supported video container (H.264), recommended for general use. - \`WEBM\`: Optimized for web delivery. - \`MOV\`: QuickTime format, common in professional workflows (Apple ecosystem). - \`GIF\`: Animated image format (no audio), suitable for short loops or previews. - \`MP3\`: Compressed audio, smaller file size. - \`WAV\`: Uncompressed, high-quality audio. - \`FLAC\`: Lossless compression. - \`OGG\`: Open-source compressed audio format (Vorbis codec). - \`SVG\`: Scalable Vector Graphics. - \`TIFF\`: High-quality output supporting layers. - \`GLB\`: Binary glTF format for 3D models, including geometry, textures, and PBR materials. > [!NOTE] > \*\*Transparency\*\*: If you are using features like background removal or LayerDiffuse that require transparency, you must select a format that supports an alpha channel (e.g., \`PNG\`, \`WEBP\`, \`TIFF\`). \`JPG\` does not support transparency.
- idempotency_key (string, optional) — Your own name for this request. Send the same one twice and the second call is answered with the first request rather than charged again. `Idempotency-Key:` as a header is accepted as an alias — that is the spelling a retrying proxy replays, and the one to use when running a model on `auray.run`, where a request that outlives its connection is answered 504 and recovered by replay. Omit it and the platform mints one.

## Rules

Across fields, as the model's documentation states them; judged before any charge, and warned (Deprecation) until enforcement starts.

- When `inputs.meshFile` is sent, do not send a request where `settings.shapeSlat` is sent, or where `settings.sparseStructure` is sent, or where `settings.decimationTarget` is sent, or where `settings.remesh` is sent, or where `settings.remeshBand` is sent, or where `settings.remeshProject` is sent, or where `settings.meshCluster` is sent.
- Unless `settings.dracoCompression.enabled` is true, do not send `settings.dracoCompression.level`. Unless `settings.dracoCompression.enabled` is true, do not send `settings.dracoCompression.quantizationNormal`. Unless `settings.dracoCompression.enabled` is true, do not send `settings.dracoCompression.quantizationPosition`. Unless `settings.dracoCompression.enabled` is true, do not send `settings.dracoCompression.quantizationTexCoord`.

## Response

A submit answers the status document (`status`: IN_QUEUE, IN_PROGRESS or COMPLETED; `request_id`;
`queue_position` while queued; `logs`; `metrics`) and then, beside it:
- product (string) — Which of this platform's products ran it.
- provider_job_id (string) — The id the job runs under, once it has been handed to its model — possibly while still `queued`; null before. Quote it to support.
- model (string) — The address that ran it, echoed back.
- engine (string) — The service's own name for the model that ran, where it reports one — a catalogue model's is its `id` on GET /v1/models; null otherwise. What `model` carried before it carried the address.
- attribution (string) — The credit line the model's licence requires you to show; null where none is required.
- credits_charged (integer) — What this job cost. 0 on a replay, or when a pass or a promotion paid for it (`coverage` says which).
- credits_quoted (integer) — What this job costs, in credits: the price it was quoted at submit. Equal to `credits_charged` once it has been charged; while it waits in the queue to start, `credits_charged` is 0 and this is what it will be charged when it starts (a cancel before then costs nothing) — and a replay of a job still waiting quotes the body that job was queued with, which is the one it runs, not the replay's. For a catalogue model it is the hold, and the settle may give part of it back — a settled read's `credits_charged` says what it finally cost.
- coverage (object) — Present when a pass or a promotion paid for this job — `{"by": "pass", "pass": "seedance-2-5"}` or `{"by": "promotion"}`, and `credits_charged` is 0 — or when you hold a pass for this model that did not cover this job: `{"by": null, "miss": {"pass": "video", "why": "door"}}`, `why` being `door` (the pass does not work here) or `shape` (it does not cover this kind of job). Absent otherwise. Send `X-Auray-Covered-Only: 1` to run a job only if a pass or a promotion pays for it.
- credits_remaining (integer) — The balance after it.
- expected_seconds (integer) — A rough render time, for a progress bar; 0 where nothing is published.
- give_up_after_seconds (integer) — The longest this job may take from its submit: the longest it may wait to start (your X-Auray-Request-Timeout, or the product's queue deadline) plus the longest it may run before it is stopped and refunded. Waiting longer is waiting for nothing; the official clients wait this long by default. For a catalogue model the part it may run is its own reap as its registry row states it (`lifecycle.stall_ceiling_seconds` on GET /v1/models); otherwise these are the published limits: we may lengthen them during an incident, never shorten them.
- replayed (boolean) — `true` when your `idempotency_key` matched a job this platform already had. Nothing was charged and nothing was rendered twice.
- waited (boolean) — Present when `wait` was asked for. The rest of this group comes with it.
- timed_out (boolean) — The wait ran out before the job settled. Still a 2xx, never a 408 or 504 — a library that retries on those would resubmit and you would pay twice. Poll `status_url`.
- wait_declined (string) — No seat was free to hold the connection with, so the request was answered at once. `platform_busy`: no product would have helped. `product_busy`: another product's queue might. `account_busy`: you are already waiting on every seat your plan's lanes allow. The job is running either way; poll it.
- status_url (string) — Poll this.
- response_url (string) — Fetch the result from this once the status is COMPLETED.
- cancel_url (string) — `PUT` to this to ask for a cancellation.
Poll `status_url`, fetch `response_url` once COMPLETED, `PUT` `cancel_url` to stop it.

## Price

Price: Credits per call (counted as `settings.shapeSlat.steps+settings.sparseStructure.steps+settings.texSlat.steps@36*settings.decimationTarget@500000*settings.textureSize@2048`): 2.669 for settings.resolution=1536; 3 for settings.resolution=512; settings.resolution=1024. Each band has its own least and most a request is counted at. Quoted when you submit, at the most the request can cost; the charge settles to what the job cost and never above the quote.

## Paths

POST https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b
  Run auray-serverless/microsoft/trellis-2-4b
GET https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b/requests/{request_id}
  The result
GET https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b/requests/{request_id}/status
  The status
PUT https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b/requests/{request_id}/cancel
  Ask for a cancellation

## Example

```bash
curl -X POST https://queue.auray.run/auray-serverless/microsoft/trellis-2-4b \
  -H 'Authorization: Bearer auray_sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"image":"https://v3b.auray.media/examples/samples/still-life.jpg"}}'
```

## Full contract

https://api.auray.ai/v1/models/auray-serverless/microsoft/trellis-2-4b/openapi.json