# Generate images

Create and edit images using owned references.

## POST /api/generate/image

Requires **generate** scope and `Idempotency-Key`. Returns a [media task](/docs/api/tasks): HTTP `202` for new work, `200` for an accepted replay.

## Request

| Field | Type | Notes |
| --- | --- | --- |
| `model` | string, required | Image ID from [discovery](/docs/api/models), up to 150 characters. |
| `prompt` | string, required | Envelope limit 30,000 characters; generator/model limits may be lower. |
| `parameters` | object | Defaults to `{}`. Accepted generator inputs depend on the model. |
| `referenceAssetIds` | string[] | Up to 10 owned asset IDs; model limits can be lower. Defaults to `[]`. |
| `maxGems` | integer | Optional request ceiling, 0–1,000,000,000. |

Unknown top-level fields and unsupported parameter names are rejected. Provider routing is selected by Lets Gen: do not include `parameters.provider`, `model`, `prompt`, or `sourceTool`.

## Common parameters

| Parameter | Use |
| --- | --- |
| `ratio` | Supported aspect ratio from the model's capabilities. |
| `resolution` | Supported model resolution. |
| `outputCount` | Image count, 1–4, subject to model constraints. |
| `negativePrompt` | Optional negative prompt, up to 1,000 characters where supported. |
| `magicPrompt` | Optional prompt optimization; defaults to false for public API images. |
| `sourceImage` | Owned source asset ID for an edit model requiring a source image. |
| `background` | `auto`, `transparent`, or `opaque` for supporting models. |
| `variant` | Model-specific variant for supporting models. |

Specialized style/reference/LoRA inputs are model-specific. The service remains authoritative; unknown options are not silently forwarded to providers.

## Example

```json
{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "prompt": "A watercolor illustration of a quiet harbor",
  "parameters": {"outputCount": 1, "magicPrompt": false},
  "maxGems": 10
}
```

Upload images with [Upload assets](/docs/api/assets). Pass returned owned IDs in `referenceAssetIds` for visual guidance, or `parameters.sourceImage` where the chosen editing model requires it. Remote reference URLs are not accepted. Reference ownership and readiness are checked before generation.

Read [Budgets and retries](/docs/budgets-and-retries) before adding automatic retries.