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

# Images API

> Generate images, choose a size tier and set the right timeouts

Orvado implements the OpenAI Images API. Create an image from a text prompt with `POST /v1/images/generations`.

## Generate an image

```bash theme={null}
curl https://orvado.dev/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $ORVADO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "flat-lay of a ceramic coffee set on linen, soft morning light",
    "size": "1536x1024"
  }'
```

### Request fields

| Field | Required | Notes |
| - | - | - |
| `model` | Yes | A model ID from [Models and pricing](/models-and-pricing) |
| `prompt` | Yes | What to draw |
| `size` | No | Any size is accepted. It sets the price tier and the aspect ratio. See below. Default is 1K |
| `quality` | No | GPT Image 2.5 only: `low`, `medium`, `high`, `xhigh`, `max` or `auto`. Does not change the price |
| `response_format` | No | `url` (default) or `b64_json` |
| `n` | No | Images per request. Send `1` and run requests in parallel for more |

### Response

```json theme={null}
{
  "created": 1792500000,
  "data": [
    { "url": "https://..." }
  ]
}
```

With `"response_format": "b64_json"`, each item has `b64_json` instead of `url`. Read whichever field is present, then save the file to your own storage. Do not use the returned link as long-term hosting.

## Sizes and price tiers

The price depends on the tier, and the tier depends on the longest side of `size`:

| Tier | Longest side | Examples |
| - | - | - |
| 1K | under 1800 px, or `auto` | `1024x1024`, `1536x1024`, `1024x1536` |
| 2K | 1800 to 2999 px | `2048x2048`, `2048x1152` |
| 4K | 3000 px and up | `3840x2160`, `4096x2304` |

The aspect ratio follows the size: `1536x1024` gives a 3:2 image, `2048x1152` gives 16:9. You can also send `1k`, `2k` or `4k` for a square image at that tier.

The price is flat per image for the tier, whatever the `quality`. Prices are in [Models and pricing](/models-and-pricing). Some models offer 1K only.

## Edit an image

Image edits (`POST /v1/images/edits`) are coming soon. Today every model supports generations only.

## Response time and timeouts

Image calls are synchronous: the connection stays open until the image is ready.

* Nano Banana images usually arrive in 10 to 60 seconds.
* GPT Image 2.5 takes about 30 to 70 seconds per image. 2K and 4K are at the slow end.
* Busy periods can take longer.
* Orvado waits up to 10 minutes for a job before it returns an error.
* **Set your client timeout to at least 180 seconds; 600 seconds is safest.** The official OpenAI SDKs already default to 10 minutes. Check any proxy, load balancer or serverless function between your app and Orvado, since many cut requests at 30 to 60 seconds.

> [!WARNING]
>
> Do not retry a request just because your client timed out or disconnected. The job can keep running and is charged when it finishes, so a blind retry may create a second paid image. Retry only after an error response such as `502` or `503`.

For many images, send requests in parallel instead of waiting for each one in turn.


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