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

# Generate Images

> Generate text-to-image and image-to-image outputs through NanoGPT's normalized Image API endpoint

## Overview

Use `POST /api/v1/images` to generate images through NanoGPT's normalized Image API. The endpoint accepts JSON only and supports text-to-image and image-to-image requests for models that expose those capabilities.

Discover model-specific parameters first with:

* `GET /api/v1/images/models`
* `GET /api/v1/images/models/{modelId}/endpoints`

## Authentication

Use either header:

* `Authorization: Bearer YOUR_API_KEY`
* `x-api-key: YOUR_API_KEY`

## Request

```http theme={null}
POST /api/v1/images
Content-Type: application/json
```

## Text-To-Image Example

```bash theme={null}
curl https://api.nano-gpt.com/api/v1/images \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NANOGPT_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2.5/flare/text-to-image",
    "prompt": "A clean product photo of a matte black espresso machine on a white counter",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'
```

## Image-To-Image Example

```json theme={null}
{
  "model": "openai/gpt-image-2.5/flare/text-to-image",
  "prompt": "Make this look like a polished studio product photo",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.png"
      }
    }
  ],
  "resolution": "1k",
  "quality": "high",
  "n": 1
}
```

## Request Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Image model ID from `GET /api/v1/images/models`. |
| `prompt` | string | Usually | Text prompt or edit instruction. Model requirements can vary. |
| `n` | integer | No | Number of output images. Internally normalized to `nImages`; if both are supplied, `nImages` takes precedence. |
| `resolution` | string | No | Output resolution when supported by the model. |
| `aspect_ratio` | string | No | Output aspect ratio when supported by the model. |
| `quality` | string | No | Quality tier when supported by the model. |
| `output_format` | string | No | Output format when supported by the model. |
| `seed` | integer | No | Optional model-specific seed that may improve reproducibility where supported by the model/provider route. Identical results are not guaranteed. Check the selected model's `supported_parameters` metadata before using this field. |
| `input_references` | array | No | Image references for image-to-image models. |

NanoGPT exposes many model-specific parameters. Treat parameter support as discoverable through `supported_parameters`, not globally available.

## Input References

`input_references` accepts an array of image references.

Supported entries:

```json theme={null}
[
  "https://example.com/image.png",
  "data:image/png;base64,...",
  {
    "type": "image_url",
    "image_url": {
      "url": "https://example.com/image.png"
    }
  }
]
```

Do not mix `input_references` with legacy image aliases such as `imageDataUrl`, `imageDataUrls`, `image_url`, or `images` in the same request. The route returns `conflicting_image_inputs` if both styles are supplied.

## Unsupported Features

`stream: true` is not supported yet.

Provider selection and provider passthrough are not supported yet. Non-empty `provider` objects return `unsupported_provider_options`.

## Common Errors

| Code | Description |
| - | - |
| `missing_model` | `model` is required. |
| `invalid_content_type` | `POST /api/v1/images` accepts `application/json` requests only. |
| `invalid_input_references` | `input_references` must be an array of image URL strings, data URLs, or `image_url` objects. |
| `conflicting_image_inputs` | Use `input_references` or legacy image input aliases, not both. |
| `unsupported_stream` | `stream: true` is not supported yet. |
| `unsupported_provider_options` | Provider selection and passthrough options are not supported yet. |

## Notes

* Use `n` for output count. If your request also sends `nImages`, `nImages` takes precedence.
* Use [Image API](/api-reference/image-generation) for the full guide and error response examples.


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