> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# AI image generation

Generate images from a text prompt or use existing workspace assets as visual
references. Model capabilities, accepted settings, and pricing vary, so discover
the model before submitting a job.

## 1. Choose a model and capability

```bash
simplified ai-image:models
simplified ai-image:models --capability prompt
simplified ai-image:models --model-id "MODEL_ID" --capability prompt
```

Replace `MODEL_ID` with an ID from the catalog. The model detail describes its
fields and any available pricing metadata. Check the supported aspect ratios and
required inputs rather than assuming every model accepts the same settings.

| Capability        | Input                                                                       |
| ----------------- | --------------------------------------------------------------------------- |
| `prompt`          | A text description.                                                         |
| `reference_image` | A prompt and a reference asset UUID.                                        |
| `multiple_images` | A prompt and multiple reference asset UUIDs, on a model that supports them. |

## 2. Generate a first image

```bash
simplified ai-image:generate \
  --model "MODEL_ID" --capability prompt \
  --prompt "Studio photograph of a ceramic mug on warm linen, soft window light, no text." \
  --aspect-ratio 1:1 --count 1 --wait
```

Choose values supported by the selected model. `--wait` keeps the command running
until the job completes or the client reaches its waiting limit. A successful
wait returns an array of image results containing asset identifiers and URLs.
Generation can consume workspace credits; use a single image while refining a prompt.

## 3. Use a reference image

[Upload your reference](/cli/assets-and-uploads), wait until it is ready, and copy
its asset UUID. Then discover a reference-capable model and submit:

```bash
simplified ai-image:models --capability reference_image
simplified ai-image:generate \
  --model "REFERENCE_MODEL_ID" --capability reference_image \
  --reference-images "ASSET_UUID" \
  --prompt "Keep the product recognizable and place it on a clean studio backdrop." \
  --count 1 --wait
```

Use comma-separated UUIDs for `multiple_images`. These inputs are asset IDs,
not file paths or public image URLs.

## 4. Refine supported settings

The CLI exposes `--negative-prompt`, `--seed`, and comma-separated style slugs
through `--properties`, in addition to aspect ratio and count. Their effect
depends on the model. A seed can help compare variations on models that support
it; it is not a guarantee of identical output across providers or model updates.

## 5. Track a longer job

Omit `--wait` when you want to submit now and check later:

```bash
simplified ai-image:generate --model "MODEL_ID" \
  --prompt "A ceramic mug on a warm neutral background." --count 1
```

Save the response, especially `art_variation_id`, then poll:

```bash
simplified ai-image:status --id "ART_VARIATION_ID"
```

Image generation uses `job_status` values such as `DONE` and `FAILED`. With
`--wait`, the CLI polls every three seconds for up to 180 seconds. A client timeout
does not prove that the remote job failed; check the existing variation before
submitting another job.

## 6. Put the image to work

Review the result, then use its URL in a [social draft](/cli/social-publishing) or
an [image-editing command](/cli/image-editing). Keep the asset ID when you need to
retrieve a fresh URL or use the image as a later generation reference.