# create_image

Check discovery first: this tool is served only where it is enabled and priced. It generates
one PNG from a text prompt. It takes no file: `input.kind` is `parameters`, so
pass the options directly and never put a prompt in a URL.

Options: `prompt` (required, up to 4000 characters), `preset` (`standard`, default, or
`reference_3d`: one isolated object from a three-quarter view with neutral lighting, the
framing `create_3d_model` uses for its own reference image), `aspect_ratio` (`1:1` 1024 × 1024,
`4:3` 1152 × 864, `3:4` 864 × 1152), `transparent_background` (default false; true keeps the
model's alpha channel and asks it for a transparent background), optional `seed`
(0–4294967295) for a reproducible result within the same profile version. `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: `image.png` (RGBA PNG when `transparent_background` is true, otherwise opaque RGB)
and `generation.json` (the options, the image digest and model revision, the effective prompt
template, seed, size, steps and timings). Download the image with `curl -fsSLo`;
`generation.json` can be read with `read_job_file`. The image can be passed to
`create_3d_model_from_image` as `job_file` `{job_id, name: "image.png"}` while it exists.

Price: read `pricing` in `GET /v1/tools` before starting the job. 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 '{"prompt": "a ceramic teapot with a blue glaze", "transparent_background": true}' > options.json
python scripts/mcpbytes.py run create_image --options-json options.json --out image/
python scripts/mcpbytes.py run create_image -o prompt="a red bicycle" -o aspect_ratio=4:3 --no-wait
python scripts/mcpbytes.py job j_...          # poll until succeeded, then download result.files[].url
```

Handle `invalid_output` (the generated image failed validation; the charge is refunded),
`invalid_alpha` (a transparent background was requested but the image came back opaque),
`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.