# Images

Generate images from text prompts using the image generation API. Requests are proxied to OpenAI's DALL-E API with automatic BYOK key resolution.

- **POST** `/v1/images/generations`
- **Auth:** `Authorization: Bearer <token>`
- **Drop-in compatible** with the OpenAI Images API.

---

## Quick start

```bash
curl -sS https://api.xantly.com/v1/images/generations \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A futuristic city skyline at sunset, digital art style",
    "n": 1,
    "size": "1024x1024"
  }'
```

---

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | `string` | Yes | Text description of the image to generate. |
| `model` | `string` | No | `"dall-e-3"` (default) or `"dall-e-2"`. |
| `n` | `integer` | No | Number of images to generate (`1`-`10`). DALL-E 3 only supports `n=1`. |
| `size` | `string` | No | Image size: `"1024x1024"` (default), `"1024x1792"`, `"1792x1024"` (DALL-E 3), or `"256x256"`, `"512x512"` (DALL-E 2). |
| `quality` | `string` | No | `"standard"` (default) or `"hd"`. DALL-E 3 only. |
| `style` | `string` | No | `"vivid"` (default) or `"natural"`. DALL-E 3 only. |
| `response_format` | `string` | No | `"url"` (default) or `"b64_json"`. |
| `user` | `string` | No | End-user identifier. |

---

## Response body

```json
{
  "created": 1741400000,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/...",
      "revised_prompt": "A futuristic city skyline at sunset..."
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `created` | `integer` | Unix epoch timestamp. |
| `data` | `array` | Generated images. |
| `data[].url` | `string` | URL of the generated image (when `response_format` is `"url"`). URLs expire after 1 hour. |
| `data[].b64_json` | `string` | Base64-encoded image data (when `response_format` is `"b64_json"`). |
| `data[].revised_prompt` | `string` | The prompt after DALL-E 3 revision (may differ from input). |

---

## Code examples

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XANTLY_API_KEY"],
    base_url="https://api.xantly.com/v1",
)

response = client.images.generate(
    model="dall-e-3",
    prompt="A cat wearing a space helmet, oil painting",
    size="1024x1024",
    quality="standard",
    n=1,
)
print(response.data[0].url)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XANTLY_API_KEY,
  baseURL: "https://api.xantly.com/v1",
});

const response = await client.images.generate({
  model: "dall-e-3",
  prompt: "A cat wearing a space helmet, oil painting",
  size: "1024x1024",
  quality: "standard",
  n: 1,
});
console.log(response.data[0].url);
```

---

## BYOK support

The images endpoint automatically resolves your organization's BYOK OpenAI key. If no BYOK key is configured, the platform key is used as a fallback.

---

## Errors

| HTTP | `error.type` | Typical trigger |
| --- | --- | --- |
| `400` | `invalid_request_error` | Missing prompt, invalid size, unsupported parameters. |
| `401` | `authentication_error` | Missing or invalid Bearer token. |
| `500` | `provider_error` | No OpenAI API key configured, or upstream error. |

---

## Next steps

- [Chat Completions](/docs/chat-completions), Main inference endpoint
- [Audio](/docs/audio), Speech-to-text and text-to-speech
- [Models](/docs/models), List available models