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

# Image Generation

## Common Params

LLMGrid supports **OpenAI-compatible image generation** and forwards provider-specific fields when applicable.

**Base URL:** `https://api.llmgrid.ai/v1`\
**Endpoint:** `POST /images/generations`\
**Auth:** `Authorization: Bearer <LLMGRID_API_KEY>`

***

## Usage

```python theme={null}
import os
from openai import OpenAI

# set env variables
os.environ["LLMGRID_API_KEY"] = "your-llmgrid-virtual-key"

client = OpenAI(
  api_key=os.environ["LLMGRID_API_KEY"],
  base_url="https://api.llmgrid.ai/v1"
)

response = client.images.generate(
  model="gpt-image-1",
  prompt="A modern retail storefront with colorful product displays, high detail, soft lighting",
  size="1024x1024",
  n=1,
  response_format="url"
)

print(response.data[0].url)
```

cURL

```Shell theme={null}

curl -X POST "https://api.llmgrid.ai/v1/images/generations" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A modern retail storefront with colorful product displays, high detail, soft lighting",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

Input Params

```python theme={null}
  def image_generation(
    prompt: str,
    # Optional OpenAI-compatible params
    model: str | None = None,
    n: int | None = None,
    size: str | None = None,
    quality: str | None = None,
    style: str | None = None,
    response_format: str | None = None,  # "url" or "b64_json"
    user: str | None = None,
    timeout: int | float | None = None,
    # Optional gateway/provider passthrough
    **kwargs,
):
    ...
```

### Required Fields

* `prompt`: *string* — Text description of the image you want to generate.

### Optional Fields

* `model`: *string (optional)* — Image model to use (depends on your enabled providers/models).
* `n`: *integer (optional)* — Number of images to generate (commonly `1–10`, model-dependent).
* `size`: *string (optional)* — Output dimensions (model-dependent).
  * Common values: `1024x1024`, plus portrait/landscape variants if supported.
* `quality`: *string (optional)* — Output quality (supported values vary by model/provider).
* `style`: *string (optional)* — Style hint (if supported).
* `response_format`: *string (optional)* — Output format:
  * `"url"` → returned `data[].url`
  * `"b64_json"` → returned `data[].b64_json` (base64-encoded image)
* `user`: *string (optional)* — End-user identifier for tracking and governance.
* `timeout`: *number (optional)* — Request timeout (seconds).

:::note Any **non-standard parameters** (fields not part of the OpenAI-compatible schema) are treated as **provider-specific** and forwarded in the request body as-is. :::

***

## Response

A typical response includes a `data` array containing either `url` or `b64_json` depending on `response_format`.

### URL Response Example

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

### Base64 Response Example (b64\_json)

```JSON theme={null}
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ]
}
```

### Decode b64\_json (Python)

```Python theme={null}
import base64

b64 = response.data[0].b64_json
img_bytes = base64.b64decode(b64)

with open("output.png", "wb") as f:
    f.write(img_bytes)
```

## Prompt Tips

* Be explicit about **subject + environment + style + lighting + composition**
* Add constraints like **camera angle**, **color palette**, **branding**, or **background**
* If output needs to be consistent, specify **same style** and **repeatable structure**

**Example prompt**

```Plain Text theme={null}
A high-resolution product hero shot of a premium tea box on a wooden table,
soft natural light from the left, shallow depth of field, clean background,
photorealistic, studio quality
```

## Common Errors

* **400** — Invalid payload / unsupported params for chosen model/provider
* **401** — Missing/invalid Virtual Key
* **403** — Key lacks access to the model/provider
* **429** — Rate limit / quota exceeded (retry with backoff)
* **5xx** — Transient error (retry with backoff)