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

# Image Generation

> Generate and edit images using AI models through dedicated and chat completions endpoints

Requesty supports image generation through two different endpoints: the dedicated **Images API** (`/v1/images/generations` and `/v1/images/edits`) for standard image workflows, and the **Chat Completions API** (`/v1/chat/completions`) for models that return images alongside text.

<Note>
  **[Browse image models](https://app.requesty.ai/model-library)** in the Requesty Console.
</Note>

## Images API (`/v1/images/generations`)

The dedicated images endpoint follows the OpenAI Images API format and is the recommended way to generate images with supported models.

### Request Format

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -d '{
    "model": "azure/openai/gpt-image-1",
    "prompt": "A sunset over mountains with vibrant orange and purple skies",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto"
  }'
```

### Parameters

| Parameter         | Type    | Required | Description                                                    |
| ----------------- | ------- | -------- | -------------------------------------------------------------- |
| `model`           | string  | Yes      | The model to use for image generation                          |
| `prompt`          | string  | Yes      | A text description of the desired image                        |
| `n`               | integer | No       | Number of images to generate (default: 1)                      |
| `size`            | string  | No       | Image dimensions (e.g., `1024x1024`, `1536x1024`, `1024x1536`) |
| `quality`         | string  | No       | Image quality (`auto`, `high`, `medium`, `low`)                |
| `response_format` | string  | No       | Output delivery format: `url` or `b64_json` (default: `url`)   |
| `background`      | string  | No       | Background type: `auto`, `transparent`, or `opaque`            |
| `output_format`   | string  | No       | File format: `png`, `jpeg`, or `webp`                          |

### Response Format

The response returns a `data` array containing the generated images:

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

When `response_format` is set to `b64_json`:

```json theme={"dark"}
{
  "created": 1719000000,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ..."
    }
  ]
}
```

### Supported Models

| Model                        | Description                            |
| ---------------------------- | -------------------------------------- |
| `azure/openai/gpt-image-1`   | OpenAI's GPT Image 1 model via Azure   |
| `azure/openai/gpt-image-1.5` | OpenAI's GPT Image 1.5 model via Azure |

***

## Image Edits API (`/v1/images/edits`)

The image edits endpoint applies a text prompt to one or more input images. It is OpenAI compatible, so you can use `client.images.edit()` directly.

### Request Format

The endpoint accepts both `multipart/form-data` (the OpenAI SDK default for file uploads) and `application/json` (with image references as base64 data URLs or file IDs).

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -F "model=azure/openai/gpt-image-1" \
  -F "prompt=Make the sky a dramatic sunset" \
  -F "image[]=@./photo.png" \
  -F "size=1024x1024" \
  -F "quality=auto"
```

JSON variant:

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -d '{
    "model": "azure/openai/gpt-image-1",
    "prompt": "Make the sky a dramatic sunset",
    "images": [
      { "image_url": "data:image/png;base64,iVBORw0KGgo..." }
    ],
    "size": "1024x1024"
  }'
```

### Parameters

| Parameter            | Type                         | Required | Description                                                                                                                       |
| -------------------- | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `model`              | string                       | Yes      | The model to use for image editing                                                                                                |
| `prompt`             | string                       | Yes      | A text description of the desired edit                                                                                            |
| `image[]` / `images` | file\[] or ImageReference\[] | Yes      | The input images. Use `image[]` form fields for file uploads, or `images` with `file_id` or `image_url` in JSON. Up to 16 images. |
| `mask`               | file or ImageReference       | No       | Optional mask. Transparent pixels mark the area that will be regenerated.                                                         |
| `n`                  | integer                      | No       | Number of edited images to generate (default: 1)                                                                                  |
| `size`               | string                       | No       | Output size (`auto`, `1024x1024`, `1536x1024`, `1024x1536`)                                                                       |
| `quality`            | string                       | No       | Image quality (`auto`, `high`, `medium`, `low`)                                                                                   |
| `input_fidelity`     | string                       | No       | Fidelity to the input image (`high` or `low`)                                                                                     |
| `background`         | string                       | No       | Background type (`auto`, `transparent`, `opaque`)                                                                                 |
| `output_format`      | string                       | No       | File format (`png`, `jpeg`, `webp`)                                                                                               |
| `output_compression` | integer                      | No       | Compression level (0 to 100) for `webp` or `jpeg`                                                                                 |
| `response_format`    | string                       | No       | Output delivery format (`url` or `b64_json`)                                                                                      |

### Python Example

```python theme={"dark"}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_REQUESTY_API_KEY",
    base_url="https://router.requesty.ai/v1",
)

with open("photo.png", "rb") as image_file:
    response = client.images.edit(
        model="azure/openai/gpt-image-1",
        prompt="Make the sky a dramatic sunset",
        image=image_file,
        size="1024x1024",
    )

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

### JavaScript/TypeScript Example

```javascript theme={"dark"}
import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'YOUR_REQUESTY_API_KEY',
  baseURL: 'https://router.requesty.ai/v1',
});

const response = await client.images.edit({
  model: 'azure/openai/gpt-image-1',
  prompt: 'Make the sky a dramatic sunset',
  image: fs.createReadStream('./photo.png'),
  size: '1024x1024',
});

console.log(response.data[0].url);
```

### Masked Edits

Pass a `mask` image to restrict edits to a specific region. Transparent pixels in the mask mark the area that will be regenerated.

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -F "model=azure/openai/gpt-image-1" \
  -F "prompt=Replace the background with a forest" \
  -F "image[]=@./portrait.png" \
  -F "mask=@./mask.png" \
  -F "size=1024x1024"
```

### Supported Models

| Model                        | Description                            |
| ---------------------------- | -------------------------------------- |
| `azure/openai/gpt-image-1`   | OpenAI's GPT Image 1 model via Azure   |
| `azure/openai/gpt-image-1.5` | OpenAI's GPT Image 1.5 model via Azure |

***

## Chat Completions API (`/v1/chat/completions`)

Google Gemini image models generate images natively through the standard chat completions endpoint. Images are returned alongside text in the response, and you can control aspect ratio and resolution with the `image_config` parameter.

### Request Format

```bash theme={"dark"}
curl https://router.requesty.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -d '{
    "model": "vertex/google/gemini-2.5-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "Generate an image of a sunset over mountains"
      }
    ],
    "image_config": {
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'
```

### Parameters

All standard [chat completions parameters](/api-reference/endpoint/chat-completions-create) apply. The additional `image_config` object controls the generated image output:

| Parameter                   | Type   | Required | Description                                                                                                                 |
| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `image_config`              | object | No       | Controls the aspect ratio and resolution of generated images                                                                |
| `image_config.aspect_ratio` | string | No       | Aspect ratio of the output image. Supported values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `image_config.image_size`   | string | No       | Resolution tier. Supported values: `1K` (default), `2K`, `4K`                                                               |

<Note>
  When `image_config` is omitted, the model defaults to a `1:1` aspect ratio at `1K` resolution.
</Note>

### Response Format

The response includes both the standard text content and an array of generated images:

```json theme={"dark"}
{
  "model": "vertex/google/gemini-2.5-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I've generated an image of a sunset over mountains as requested.",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,your_base64_image"
            }
          }
        ]
      }
    }
  ]
}
```

### Python Example

```python theme={"dark"}
import base64
from io import BytesIO
from PIL import Image
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_REQUESTY_API_KEY",
    base_url="https://router.requesty.ai/v1",
)

response = client.chat.completions.create(
    model="vertex/google/gemini-2.5-flash-image-preview",
    messages=[
        {
            "role": "user",
            "content": "Generate a futuristic cityscape at night"
        }
    ],
    extra_body={
        "image_config": {
            "aspect_ratio": "16:9",
            "image_size": "2K"
        }
    }
)

# Extract the generated image
message = response.choices[0].message
if hasattr(message, 'images') and message.images:
    for i, image_data in enumerate(message.images):
        # Extract base64 data from data URL
        # Format: "data:image/png;base64,actual_base64_data"
        base64_str = image_data['image_url']['url'].split(',')[1]
        image_bytes = base64.b64decode(base64_str)
        
        # Open with PIL
        image = Image.open(BytesIO(image_bytes))
        
        # Save the image
        image.save(f'generated_image_{i}.png')
        print(f"Image saved as generated_image_{i}.png")

# Access the text response
print(message.content)
```

### JavaScript/TypeScript Example

```javascript theme={"dark"}
import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'YOUR_REQUESTY_API_KEY',
  baseURL: 'https://router.requesty.ai/v1',
});

async function generateImage() {
  const response = await client.chat.completions.create({
    model: 'vertex/google/gemini-2.5-flash-image-preview',
    messages: [
      {
        role: 'user',
        content: 'Generate a serene landscape with a lake'
      }
    ],
    image_config: {
      aspect_ratio: '16:9',
      image_size: '2K'
    }
  });

  const message = response.choices[0].message;
  
  // Handle generated images
  if (message.images && message.images.length > 0) {
    message.images.forEach((imageData, index) => {
      // Extract base64 data from data URL
      // Format: "data:image/png;base64,actual_base64_data"
      const base64Data = imageData.image_url.url.split(',')[1];
      const imageBuffer = Buffer.from(base64Data, 'base64');
      
      // Save to file
      fs.writeFileSync(`generated_image_${index}.png`, imageBuffer);
      console.log(`Image saved as generated_image_${index}.png`);
    });
  }

  // Access the text response
  console.log(message.content);
}

generateImage();
```

### Supported Models

| Model                                          | Description                                     |
| ---------------------------------------------- | ----------------------------------------------- |
| `vertex/google/gemini-2.5-flash-image-preview` | Gemini 2.5 Flash image generation via Vertex AI |
| `vertex/gemini-3.1-flash-image-preview`        | Gemini 3.1 Flash image generation via Vertex AI |
| `vertex/google/gemini-3-pro-image-preview`     | Gemini 3 Pro image generation via Vertex AI     |

### Supported Aspect Ratios & Resolutions

| Aspect Ratio | 1K        | 2K        | 4K        |
| ------------ | --------- | --------- | --------- |
| `1:1`        | 1024×1024 | 2048×2048 | 4096×4096 |
| `2:3`        | 848×1264  | 1696×2528 | 3392×5056 |
| `3:2`        | 1264×848  | 2528×1696 | 5056×3392 |
| `3:4`        | 896×1200  | 1792×2400 | 3584×4800 |
| `4:3`        | 1200×896  | 2400×1792 | 4800×3584 |
| `4:5`        | 928×1152  | 1856×2304 | 3712×4608 |
| `5:4`        | 1152×928  | 2304×1856 | 4608×3712 |
| `9:16`       | 768×1376  | 1536×2752 | 3072×5504 |
| `16:9`       | 1376×768  | 2752×1536 | 5504×3072 |
| `21:9`       | 1584×672  | 3168×1344 | 6336×2688 |

These match the aspect ratios and resolutions supported by Google's Gemini image models.

***

## Choosing an Endpoint

| Feature                | Images Generate            | Images Edit            | Chat Completions API                        |
| ---------------------- | -------------------------- | ---------------------- | ------------------------------------------- |
| Endpoint               | `/v1/images/generations`   | `/v1/images/edits`     | `/v1/chat/completions`                      |
| OpenAI SDK support     | `client.images.generate()` | `client.images.edit()` | `client.chat.completions.create()`          |
| Accepts input images   | No                         | Yes (up to 16)         | Yes (as chat content)                       |
| Mask support           | No                         | Yes                    | No                                          |
| Text + image response  | No                         | No                     | Yes                                         |
| Conversational context | No                         | No                     | Yes                                         |
| Aspect ratio control   | No                         | No                     | Yes (`image_config.aspect_ratio`)           |
| Resolution control     | Via `size`                 | Via `size`             | Yes (`image_config.image_size`: 1K, 2K, 4K) |
| Background control     | Yes                        | Yes                    | No                                          |
| Output format control  | Yes (png, jpeg, webp)      | Yes (png, jpeg, webp)  | No                                          |

<Note>
  Image generation models may have different pricing compared to text models. Check the [model library](https://app.requesty.ai/model-list) for specific pricing information.
</Note>

## Limitations

* Image size and resolution depend on the specific model capabilities
* Some models may have content filtering or safety restrictions
* Response size limits apply to the combined text and image data