# create_3d_model

Check discovery first: this tool is served only where it is enabled and priced. It turns a
text description into a textured 3D model (`model.glb`) plus a matching picture of the object
(`reference.png`). It takes no file: `input.kind` is `parameters`. Geometry is unitless: no
physical size, rigging, watertightness or print readiness is inferred, and hidden sides are
invented.

Options: `description` (required, up to 4000 characters: one object, its materials and
colours; avoid scenes and text), `quality` (`economy`, default, or `high`),
`texture_resolution` (fixed by the quality: 1024 for economy, 2048 for high), optional `target_faces` (high only: 100000, 300000 or 1000000 faces kept before
textures are baked; default 1000000), optional `seed` (0–4294967295). `idempotency_key` is **required**: repeating the same request with the same
key returns the same job instead of paying again.

The job is accepted asynchronously with a one-hour deadline from creation, including queueing and execution. `wait_seconds` is at most 45, so poll `get_job` with `wait_seconds: 45`
until the status is final; the job reports `workflow.stage` and `workflow.deadline`. Do not
start the job again while it runs. While the job advertises `capabilities.can_cancel`,
`cancel_job` cancels and refunds it.

Outputs: `model.glb` (self-contained glTF binary, one mesh, PBR material, opaque rendering),
`model.web.glb` (the same model with Draco geometry and WebP textures for browsers and engines),
`reference.png` (RGBA) and `generation.json` (options, image digests, model revisions, seeds,
effective settings, validation counts and timings). Download binaries with
`curl -fsSLo`; `generation.json` can be read with `read_job_file`. `model.glb` can be passed to
`optimize_3d_model` as `job_file` while it exists; `split_3d_model`, `inspect_3d_model` and
`simplify_3d_model` take no `job_file`, so download it and upload it.

Price: read the selected quality's `pricing.variants` entry in `GET /v1/tools`. The charge is made before
generation starts; a job that fails or is canceled is refunded.
Free limits: 20 jobs per rolling 24 hours (3 until the account's first credit purchase).

Without MCP:

```bash
printf '{"description": "a wooden rocking horse with a red saddle", "quality": "economy"}' > options.json
python scripts/mcpbytes.py run create_3d_model --options-json options.json --out model/
python scripts/mcpbytes.py run create_3d_model -o description="a brass compass" -o quality=high --no-wait
python scripts/mcpbytes.py job j_...          # poll until succeeded, then download result.files[].url
```

Handle `invalid_image` (the generated reference had no usable foreground), `invalid_output`,
`out_of_memory`, `timeout` and `capacity_exhausted` (budget exhausted at creation, HTTP 503, or
before charging a queued job) using the returned message. Do not repeat a failed request unchanged.