# Image generation

Send a text prompt to `POST /v1/images/generations`. The V1 handler uses its configured image service; the request's `model` field does not select arbitrary image backends.

## Generate an image

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/images/generations \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small lighthouse at dawn, watercolor illustration",
    "n": 1,
    "size": "1024x1024"
  }'
~~~

The configured model in the documented V1 handler is `stable-diffusion-xl-base-v10`. This is a configuration fact, not confirmation of current upstream availability.

## Request fields

| Field | Behavior |
| --- | --- |
| `prompt` | Required, nonempty text |
| `n` | Defaults to 1; maximum 4; V1 normalizes nonpositive values to 1 |
| `size` | Accepted and defaults to 1024x1024 locally, but is not forwarded by V1; it does not control generated dimensions |
| `model` | Does not change the V1 configured image backend |
| `response_format` | Optional, forwarded; response support depends on the service |

Multiple requested images are generated sequentially in V1. Do not assume a request for four images takes the same time as one.

## Handle the response

The response has a `created` timestamp and `data` array. Each entry can contain a URL or base64 image data:

~~~json
{
  "created": 1789380000,
  "data": [
    {"url": "https://api.simplellm.eu/images/EXAMPLE_IMAGE_ID"}
  ]
}
~~~

The URL above illustrates the response shape; always use the returned URL rather than constructing one. When `b64_json` is returned, decode it as base64 image bytes.

The V1 image proxy stores returned URL mappings with a 24-hour expiry. Download needed results promptly and store them in your application; do not treat generated links as permanent asset hosting.

## Cost and failures

The V1 implementation checked on 2026-09-14 charges 5 SC per generated image. A four-image request therefore has a configured cost of 20 SC; verify current pricing before a larger job.

Handle `402` as insufficient credits and upstream errors as a failed request, not an image result. Avoid uncontrolled retries: image generation is a new operation each time.

See [Image generation API](/docs/reference/createImage.html) for the schema and [vision inputs](/docs/vision.html) if your goal is to analyze an existing image instead.