# create_3d_model_from_image

Check discovery first: this tool is served only where it is enabled and priced. It
reconstructs a textured 3D model (`model.glb`) from one PNG or JPEG.
Files are uploaded to MCPBytes. Geometry is unitless: no physical size, rigging,
watertightness or print readiness is inferred from a picture, and hidden sides are invented.

Give `upload_id`, a public HTTPS `url` (with `filename` if needed), or `job_file`
`{job_id, name}` for one of the user's own unexpired outputs. `idempotency_key` is
**required**: repeating the same request with the same key returns the same job instead
of paying again. Options: `quality` (`economy`, default: a roughly 40,000-face paint budget;
or `high`, with a configurable face target), `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), optional `seed` (0–4294967295) for a reproducible result
within the same profile version. A transparent background gives the cleanest silhouette;
opaque images are segmented first.

The job is accepted asynchronously with a one-hour deadline from creation, including queueing
and execution. Completion time depends on worker availability, input and quality. `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 it and refunds it; cleanup or the refund may still be pending right after.

Outputs: `model.glb` (self-contained glTF binary, one mesh, PBR material with base colour
and metal/roughness textures, opaque rendering), `model.web.glb` (the same model with Draco
geometry and WebP textures for browsers and engines) and `generation.json` (the options, image
digest and model revision, seeds, effective settings, validation counts and timings).
Download `model.glb` 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 reconstruction 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), images up to 20 MB and 25 megapixels.

Without MCP:

```bash
python scripts/mcpbytes.py run create_3d_model_from_image photo.png -o quality=economy --out model/
python scripts/mcpbytes.py run create_3d_model_from_image https://example.com/object.png --filename object.png --no-wait
python scripts/mcpbytes.py job j_...          # poll until succeeded, then download result.files[].url
```

Handle `invalid_image` (not a decodable PNG/JPEG, animated, over the limits, or no visible
foreground), `invalid_output`, `out_of_memory`, `timeout` and `capacity_exhausted`
(the budget was exhausted at creation, HTTP 503, or before charging a queued job) using the returned message. Do not repeat a failed input
unchanged.