> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Images API
> OpenAI-compatible image generation through GoModel, routed by model with the same access rules, budgets, rate limits, and cost tracking as chat.
## Overview
GoModel exposes the **OpenAI-compatible image generation endpoint**. Clients and
SDKs that already call OpenAI's `/v1/images/generations` can point at GoModel
unchanged.
Requests route **by model** through the same registry used for chat and
embeddings, so `model` selection, `provider` hints, virtual models, per-key model
access rules ([user paths](/docs/features/user-path)), [budgets](/docs/features/budgets),
and [rate limits](/docs/features/rate-limits) all apply. Image generation is served by
OpenAI and the OpenAI-compatible providers that implement the endpoint
(Azure OpenAI, OpenRouter, [xAI](/docs/providers/xai)). A provider without image
support returns a clear `model "…" does not support image generation` error
rather than mis-routing, and image-only models are hidden from `/v1/models` for
such providers.
## Supported endpoints
| Endpoint | Behavior |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/images/generations` | Generate images from a text prompt. Accepts a JSON body and returns the OpenAI images envelope (`created`, `data[]`, optional `usage`). |
## Generate an image
```bash curl theme={null}
curl https://your-gateway/v1/images/generations \
-H "Authorization: Bearer $GOMODEL_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1",
"prompt": "A watercolor painting of a lighthouse at dawn",
"n": 1,
"size": "1024x1024",
"quality": "medium"
}'
```
```python Python theme={null}
import base64
import os
from openai import OpenAI
client = OpenAI(
base_url="https://your-gateway/v1",
api_key=os.environ["GOMODEL_KEY"],
)
result = client.images.generate(
model="gpt-image-1",
prompt="A watercolor painting of a lighthouse at dawn",
size="1024x1024",
quality="medium",
)
with open("lighthouse.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
```
```javascript JavaScript theme={null}
import { writeFile } from "node:fs/promises";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://your-gateway/v1",
apiKey: process.env.GOMODEL_KEY,
});
const result = await client.images.generate({
model: "gpt-image-1",
prompt: "A watercolor painting of a lighthouse at dawn",
size: "1024x1024",
quality: "medium",
});
await writeFile("lighthouse.png", Buffer.from(result.data[0].b64_json, "base64"));
```
`model` and `prompt` are required. Every other field — `n`, `size`, `quality`,
`style`, `response_format`, `background`, `output_format`, `output_compression`,
`moderation`, `user`, and any future parameter — is **forwarded to the provider
unchanged**, so model-specific options work without a gateway update. The
provider decides which values it accepts and returns its own error otherwise.
The response is the OpenAI images envelope. `data[]` entries carry either a
hosted `url` (DALL·E, `response_format: "url"`) or inline `b64_json`
(`gpt-image-1` always returns base64). GoModel adds a `provider` field naming the
provider type that served the request; everything else is passed through,
including the `usage` block and echoed output parameters `gpt-image-1` reports.
Use a `provider/model` selector (for example `"model": "openai/dall-e-3"`) or
the `"provider"` hint when the same model ID is configured on several
providers, exactly as with chat.
## Cost tracking
Image calls are recorded in [usage tracking](/docs/features/cost-tracking) under the
`/v1/images/generations` endpoint:
* **Token-billed models** (`gpt-image-1` and similar) report `usage` in the
response; GoModel stores the input/output token counts and prices them with the
model's `input_per_mtok` / `output_per_mtok` rates.
* **Per-image models** (DALL·E, `grok-2-image`) report no tokens. GoModel records
the number of returned images (`images` in the raw usage data) and prices it
with the model's `per_image` rate.
Set `per_image` through a [pricing override](/docs/features/cost-tracking#override-pricing)
or in `config.yaml` when the model catalog has no price for an image model:
```yaml theme={null}
providers:
openai:
type: openai
api_key: "${OPENAI_API_KEY}"
models:
- id: dall-e-3
metadata:
pricing:
currency: USD
per_image: 0.04
```
## Limitations
The images endpoint is a thin, model-routed pass to the provider and **does not
run through the full inference orchestrator**. Compared with `/v1/chat/completions`:
* **No failover, guardrails, or response cache** — these stages are skipped.
Requests are still authorized, budget-checked, rate-limited, metered, and
written to the [audit log](/docs/advanced/admin-endpoints).
* **No streaming** — `stream: true` is rejected with a `400` because streamed
image generation is delivered as server-sent events, which this endpoint does
not relay. Omit `stream` (or set it to `false`) to receive the complete JSON
response.
* **Edits and variations** (`/v1/images/edits`, `/v1/images/variations`) are not
exposed. Use the [passthrough API](/docs/features/passthrough-api)
(`/p/{provider}/v1/images/...`) to reach them on a specific provider.
* **OpenAI request shape in, OpenAI-compatible providers out** — providers whose
native image API differs from OpenAI's (for example Gemini Imagen) are not
translated behind this endpoint; use passthrough for those.
## Audit logging
Image requests appear in the audit log like any other model interaction. When
`LOGGING_LOG_BODIES` is enabled the JSON request and response are captured;
responses larger than the 1 MB capture limit (typical for `b64_json` output)
are stored truncated and flagged `response_body_too_big_to_handle`.