> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation

> Generate and edit images with inline base64 results and per-model pricing.

Image models: [JSON](https://nomask.ai/images/models) · [Markdown](https://nomask.ai/images/models.md) · [Text](https://nomask.ai/images/models.txt)

> [card] [Try image generation](https://docs.nomask.ai/api-reference/image-generations.md)
>
> Build a text-to-image request.

> [card] [Try image editing](https://docs.nomask.ai/api-reference/image-edits.md)
>
> Add reference images and an editing prompt.

> [!NOTE]
>
> Use a current public model ID from [Models](https://nomask.ai/models) or `GET /models`. Example IDs and options must match the selected model's advertised capabilities and limits.

Generate or edit images with the same API key and credit balance you use for text requests.

Choose an image model in your [Models dashboard](https://nomask.ai/models), or query the authenticated [List models endpoint](https://docs.nomask.ai/api-reference/list-models.md) and find entries with `type: image`.

## Choose an image model

Open [Models](https://nomask.ai/models) and choose Images, or find entries with `type: image` from `GET /models`. Their `limits` list prompt length, reference counts, resolutions, aspect ratios and output formats. Image models use image endpoints; text models use `/chat/completions`.

A minimum of zero reference images allows generation from a prompt alone. A positive minimum requires that many reference images. Use the model's public `id` in requests.

## Generate an image

`POST /images/generations`

> [tab] curl
>
> ```bash theme={"system"}
> curl https://api.nomask.ai/v1/images/generations \
>   -H "Authorization: Bearer $NOMASK_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>   "model": "YOUR_IMAGE_MODEL",
>   "prompt": "A quiet mountain lake at sunrise",
>   "n": 1,
>   "response_format": "b64_json",
>   "output_format": "png"
> }'
> ```

> [tab] Python
>
> ```python theme={"system"}
> import base64
> import requests
>
> response = requests.post(
>     "https://api.nomask.ai/v1/images/generations",
>     headers={"Authorization": "Bearer YOUR_API_KEY"},
>     json={
>     "model": "YOUR_IMAGE_MODEL",
>     "prompt": "A quiet mountain lake at sunrise",
>     "n": 1,
>     "response_format": "b64_json",
>     "output_format": "png"
> },
> )
> response.raise_for_status()
> result = response.json()
> with open("image.png", "wb") as image:
>     image.write(base64.b64decode(result["data"][0]["b64_json"]))
> ```

> [!NOTE]
>
> Image requests return one completed JSON response. Streaming is currently unsupported, and `n` must be `1`.

## Edit with reference images

`POST /images/edits`

Send a PNG, JPEG or WebP file as multipart `image`, or repeated `image[]` fields for multiple references. Check the selected model's minimum and maximum before uploading.

```bash theme={"system"}
curl https://api.nomask.ai/v1/images/edits \
  -H "Authorization: Bearer $NOMASK_API_KEY" \
  -F 'model=YOUR_EDITING_MODEL' \
  -F 'prompt=Keep the subject and add warm studio lighting' \
  -F 'image=@reference.png' \
  -F 'n=1' \
  -F 'response_format=b64_json' \
  -F 'output_format=png'
```

For JSON, send `images` as an array of base64 image data URLs. The `image` alias accepts one data URL or an array. Remote image URLs and masks are unsupported. The generation endpoint also accepts JSON references when the model supports them.

```json theme={"system"}
{
  "model": "YOUR_EDITING_MODEL",
  "prompt": "Keep the subject and add warm studio lighting",
  "images": [
    "data:image/png;base64,BASE64_IMAGE"
  ],
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
```

## Request parameters

### `model`

**Type:** string · **Required**

The image model's public API ID.

### `prompt`

**Type:** string · **Required**

The instruction, within `limits.max_prompt_characters`.

### `n`

**Type:** integer · **Default:** `1`

Only one output image per request is supported.

### `response_format`

**Type:** string · **Default:** `b64_json`

Only `b64_json` is supported. Images are returned inline, without hosted URLs.

### `resolution`

**Type:** string

An advertised resolution tier from `limits.supported_resolutions`. Omit to use the default.

### `aspect_ratio`

**Type:** string

An advertised ratio from `limits.supported_aspect_ratios`. Omit to use the default.

### `size`

**Type:** string

An alias accepting `auto`, an advertised tier or a `WIDTHxHEIGHT` value that maps to a supported resolution and ratio. Prefer `resolution` and `aspect_ratio`; pixel dimensions are not a guarantee of exact output size.

### `output_format`

**Type:** string · **Default:** `png`

`png`, `jpg`, `jpeg` or `webp`, within the model's output formats. `jpeg` is an alias for `jpg`.

Image requests do not accept chat messages, function tools, reasoning controls, masks or a quality setting.

## Response and usage

Generation and editing return the same response structure. This example has no reported token counters:

```json theme={"system"}
{
  "created": 1793617200,
  "request_id": "req_example_image_request",
  "model": "YOUR_PER_IMAGE_MODEL",
  "data": [
    {
      "b64_json": "BASE64_IMAGE_BYTES",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "images": 1,
    "tokens_reported": false
  },
  "nomask": {
    "cost_usd": 0.04,
    "model_cost_usd": 0.04,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "output_format": "png",
    "reference_images": 0,
    "pricing_type": "resolution"
  }
}
```

Decode `data[0].b64_json` and save the bytes in your application. `mime_type`, `width` and `height` describe the actual returned image. `request_id` matches the `X-Request-Id` response header.

When token usage is reported, the same response includes the actual counters:

```json theme={"system"}
{
  "created": 1793617200,
  "request_id": "req_example_image_request",
  "model": "YOUR_PER_IMAGE_MODEL",
  "data": [
    {
      "b64_json": "BASE64_IMAGE_BYTES",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "prompt_tokens": 1000,
    "completion_tokens": 500,
    "total_tokens": 1500,
    "images": 1,
    "tokens_reported": true
  },
  "nomask": {
    "cost_usd": 0.04,
    "model_cost_usd": 0.04,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "output_format": "png",
    "reference_images": 0,
    "pricing_type": "resolution"
  }
}
```

`input_tokens` and `prompt_tokens` are the same input count; `output_tokens` and `completion_tokens` are the same output count. `total_tokens` is their sum, and `usage.images` is the returned image count. If counters are unavailable, `tokens_reported` is false and token fields are zero. Those zeros are not measured usage. Reported zero usage has `tokens_reported: true`.

`nomask.cost_usd` and `nomask.model_cost_usd` are the settled USD charge. `pricing_type` is `resolution` for per-image billing or `tokens` for token billing. Per-image models use the selected resolution's price; token-priced models use actual input and output counts and require reported usage before a charge can settle.

`nomask.resolution`, `aspect_ratio` and `output_format` show the resolved request options; `reference_images` counts uploaded references. Resolution is null when the model has no resolution tiers. The actual pixel dimensions are in `data`.

## Balance, limits and privacy

* API image requests are billed in USD from your credit balance and follow the calling key's monthly spending limit. Image Studio daily allowances do not apply.
* Per-image prices are reserved before generation, then settled once. Failed requests are refunded; abandoned reservations are recovered automatically.
* Image requests have requests per minute (RPM) and requests per day (RPD) limits. Usage is shared across your image models and API keys. Text API limits are separate; token limits do not apply to image requests.
* Check the model's `rate_limit` for `requests_per_minute` and `requests_per_day`. Switching models does not reset usage. Daily limits reset at midnight in Africa/Lagos.
* API history stores usage metadata without prompts or image bytes. Results are returned inline and are not hosted as downloadable URLs. Save the returned bytes in your own application.

| Response | What to check |
| - | - |
| 400 / 413 | Model, prompt length, reference count, file size, output options or an unsupported parameter. |
| 402 | Your available balance does not cover the request. |
| 409 | This idempotency key has already been accepted. Image responses are not cached for replay; keep your original response and use a new key for a new request. |
| 429 | Your RPM/RPD allowance or key's monthly spending limit. Follow `Retry-After` when present. See [rate-limit headers](https://docs.nomask.ai/rate-limits.md) for minute and daily balances. |
| 5xx | Image generation could not finish. Keep the response request ID when reporting the failure. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.