> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.singularityapi.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.singularityapi.dev/_mcp/server.

# Image Generation

Generate images with the OpenAI-compatible images endpoint. Four models are available: two FLUX models billed per megapixel, and two GPT Image models billed per image at a fixed quality × size price. See [Models & Pricing](/get-started/models-pricing) for the full price tables.

Requests are non-streaming: one `POST`, one JSON response.

**`cURL`**

```bash title="cURL"
curl https://api.singularityapi.dev/v1/images/generations \
  -H "Authorization: Bearer $SINGULARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-schnell",
    "prompt": "a lighthouse at dawn, minimalist",
    "size": "1024x1024"
  }'
```

**`Python (OpenAI SDK)`**

```python title="Python (OpenAI SDK)"
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.singularityapi.dev/v1",
)

image = client.images.generate(
    model="gpt-image-2",
    prompt="a lighthouse at dawn, minimalist",
    size="1024x1024",
    quality="low",
)
```

**`JavaScript (OpenAI SDK)`**

```javascript title="JavaScript (OpenAI SDK)"
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.singularityapi.dev/v1",
});

const image = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a lighthouse at dawn, minimalist",
  size: "1024x1024",
  quality: "low",
});
```

## Response shape

FLUX models return hosted URLs (JPEG); GPT Image models return base64 (`b64_json`). The response follows the OpenAI images schema:

```json
{
  "created": 1756600000,
  "data": [
    { "url": "https://v3b.fal.media/files/..." }
  ],
  "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 }
}
```

> **Note**
>
> The `usage` block is not meaningful for image generation — images are billed per megapixel or per image, never by tokens. The exact charge for every request is on its [receipt](/api/models-receipts).

## Parameters

| Parameter            | FLUX models                                                                                                           | GPT Image models                                                              |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `model`              | required                                                                                                              | required                                                                      |
| `prompt`             | required, 1–32,000 characters                                                                                         | required, 1–32,000 characters                                                 |
| `size`               | any `WIDTHxHEIGHT` — each side 256–2560 px, area at most 4 megapixels (`1792x1024` and `1024x1792` are not available) | `1024x1024`, `1024x1536`, or `1536x1024`                                      |
| `quality`            | not supported — the model's default always applies                                                                    | `low`, `medium`, or `high`                                                    |
| `n`                  | 1 only                                                                                                                | 1–4 (each image billed at the grid price)                                     |
| `response_format`    | `url` only (the default)                                                                                              | not applicable — always `b64_json`                                            |
| `output_format`      | —                                                                                                                     | `png` (default), `jpeg`, or `webp`                                            |
| `output_compression` | —                                                                                                                     | 0–100; requires `output_format` `jpeg` or `webp`                              |
| `background`         | —                                                                                                                     | `auto`, `opaque`, or `transparent` (`transparent` cannot combine with `jpeg`) |
| `moderation`         | —                                                                                                                     | `auto` or `low`                                                               |
| `user`               | —                                                                                                                     | optional string, 1–256 characters                                             |

Omitted `size` and `quality` (and the literal value `"auto"`) resolve to `1024x1024` and `high` on GPT Image models; the substitution is recorded in the request's `transformed_fields` on its receipt.

`stream` is not supported on this endpoint. Unknown or unsupported parameters are rejected with a `400` before any charge is reserved.

## Billing

Image generation charges are **deterministic**: the price is fixed by the request itself at admission, before the provider is called, and the receipt settles at exactly that amount.

* **FLUX models** bill `ceil(width × height / 2²⁰)` megapixels per image at the model's per-megapixel rate — a `1024x1024` image is 1 MP, a `1600x1024` image rounds up to 2 MP.
* **GPT Image models** bill the fixed per-image price for the requested `quality` × `size` cell, multiplied by `n`.

The [route receipt](/platform/receipts-billing) for an image request shows the surface `images_generations` and the exact prepaid charge; token usage is shown as not applicable.