---
title: "Generate an image"
method: POST
path: "/images/generations"
tags: ["Images"]
---

# Generate an image

`POST /images/generations`

## Request

- Base URL: `https://api.textcortex.com/v1`
- URL: `https://api.textcortex.com/v1/images/generations`
- Auth: HTTP bearer

Generate one image from a prompt. `data[0].url` is a TextCortex resource URI
(`textcortex://images/<image_id>`), not a directly downloadable HTTP URL.
Keep `data[0].image_id` to reuse the image in another generation.
Check `GET /capabilities` for access. This is a separate image catalog:
`GET /models` lists chat models, not the image models below.

### Choose a model

Set `model` explicitly for predictable selection. Omit it to use
`gpt-image-2.5` on this deployment.

| Model ID | Size presets (pixels), or aspect ratios | image_size | Max reference images |
| --- | --- | --- | --- |
| `gpt-image-2.5` | 1024x1024, 1024x1536, 1536x1024, 1920x1072, 1072x1920, 3840x2160, 2160x3840 | Omit | 5 |
| `gpt-image-2` | 1024x1024, 1024x1536, 1536x1024, 1920x1072, 1072x1920, 3840x2160, 2160x3840 | Omit | 5 |
| `grok-imagine-image-quality` | 2048x2048, 2048x1152, 1152x2048, 2048x1536, 1536x2048, 1920x1280, 1280x1920, 1024x1024, 1024x576, 576x1024, 1024x768, 768x1024, 960x640, 640x960 | Omit | 3 |
| `nano-banana` | 1:1, 21:9, 16:9, 4:3, 3:2, 9:16, 3:4, 2:3, 5:4, 4:5 | Omit | 5 |
| `nano-banana-2` | 1:1, 21:9, 16:9, 4:3, 3:2, 9:16, 3:4, 2:3, 5:4, 4:5 | 2K, 4K | 5 |
| `gemini-3-pro-image` | 1:1, 21:9, 16:9, 4:3, 3:2, 9:16, 3:4, 2:3, 5:4, 4:5 | 2K, 4K | 5 |

The table lists presets, not every custom dimension supported by a provider.
Use one sizing control at a time: `size` for pixel dimensions or `aspect_ratio`
for a ratio. Omit both for the model default. For models supporting `image_size`,
combine it with `aspect_ratio` to select resolution. Unsupported values return 400.

### Use a reference image

Add `image_urls` containing publicly reachable HTTP(S) image URLs, or reuse
`image_ids` returned by a previous generation. File-upload IDs are not image IDs.
The model's reference limit applies to both arrays combined. Images must be
accessible to the caller; private-network URLs are rejected. Reference URLs must
serve JPEG, PNG or WEBP bytes, with a maximum download size of
6 MiB per image. GIF and SVG are not supported.

Each request returns one image: `n` must be 1 and `response_format` must be `url`.
Base64 output is not supported. The `url` response format names the response
field; it does not promise a public download URL or a retention period.

## Request body

- ApiPlatformImageGenerationRequest
  - `aspect_ratio` union: Width:height ratio, for example 16:9. Prefer omitting size when setting aspect_ratio.
    - string
    - unknown
  - `image_ids` union: Reference image IDs from previous image generations, not IDs from POST /api-platform/files. Combined with image_urls for the model's input limit.
    - string[]
    - unknown
  - `image_size` union: Resolution tier for models marked in the table: 2K or 4K. Omit for other models. This is not pixel dimensions.
    - string
    - unknown
  - `image_urls` union: Public HTTP(S) reference-image URLs. Combined with image_ids for the model's input limit; private-network destinations are rejected. JPEG, PNG or WEBP only; at most 6 MiB per image.
    - string[]
    - unknown
  - `model` union: Image model ID from the table above; GET /models lists chat models. Omit to use the documented deployment default.
    - string
    - unknown
  - `n` integer
  - `prompt` string, required
  - `response_format` 'url'
  - `size` union: Pixel dimensions as WIDTHxHEIGHT, for example 1024x1024. Use a preset for the chosen model. Prefer omitting aspect_ratio when setting size.
    - string
    - unknown

## Response `200`

Successful response

- ImageGenerationResponse
  - `created` integer, required: Unix timestamp in seconds.
  - `data` GeneratedImage[], required
    - `file_type` string: File extension, for example jpeg; not a MIME type.
    - `height` integer
    - `image_id` string, required
    - `model` string
    - `revised_prompt` string
    - `url` string, required: TextCortex resource URI (textcortex://images/<image_id>), not a downloadable HTTP URL.
    - `width` integer

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `402`: Insufficient funding
- `403`: Access denied
- `404`: Resource not found
- `422`: Request validation failed
- `500`: Server error
- `502`: Upstream provider failed

## Changes

- **2026-10-08** `254204fd17bd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/textcortex/apis/textcortex-api/changes/images/generations/post.md)

---

[API](https://skmtc.dev/textcortex/apis/textcortex-api.md) - [All operations](https://skmtc.dev/textcortex/apis/textcortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/textcortex/apis/textcortex-api/revisions/b27459bd3c96?raw)