# gpt-image-1.5 API

This document introduces the input and output parameters for calling the `gpt-image-1.5` model API, providing you with a reference for understanding the meaning of the fields when using the interface.

---

## Request Parameters

### Request Body

| Field Name          | Type   | Required | Default Value | Description                                                                                                               |
| ------------------- | ------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| prompt              | string | Required | -             | Prompt                                                                                                                    |
| model               | string | Required | -             | The model name used for this request, which is `gpt-image-1.5`.                                                                 |
| n                   | int    | Optional | 1             | Number of images to generate, ranging from 1 to 4                                                                                                 |
| size                | string | Optional | "1024x1024"   | Resolution. GPT-image-1.5 supports `1024x1024`, `1024x1536`, `1536x1024`.                                                 |
| quality             | string | Optional | -             | Image quality, supporting `low`, `medium`, `high`; higher quality takes longer. Compared to version 1.0, generation speed is 4 times faster and costs are reduced by 20%. |
| output_format       | string | Optional | "png"         | Output image format, supporting `png`, `jpeg`, `webp`.                                                                                                |
| output_compression  | int    | Optional | 100           | Image compression intensity, values ranging from 0 to 100; `0` means no compression, `100` means maximum compression.                                                                      |

## Response Parameters

| Field Name   | Type      | Description                                                                                                                                                                                                                                                    |
| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created       | `integer` | Unix timestamp (in seconds) for the creation time of this request.                                                                                                                                                                                                                  |
| data          | `array`   | Information about the output image, including the URL for image download or Base64. The gpt-image-1.5 model returns base64 data.<br>• When specifying the return format of the generated image as url, the corresponding parameter subfield is url;<br>• When specifying the return format of the generated image as b64_json, the corresponding parameter subfield is b64_json.<br>Note: Links will expire within 7 days after generation, please save the images promptly. |
| error         | `Object`  | Error information object                                                                                                                                                                                                                                          |
| error.code    | `string`  | Error code                                                                                                                                                                                                                                                      |
| error.message | `string`  | Error message                                                                                                                                                                                                                                                |
| error.param   | `string`  | Request id                                                                                                                                                                                                                                                 |

## Example

### OPENAI Compatible Interface

`POST https://api.umodelverse.ai/v1/images/generations`

#### Synchronous Request

<!-- tabs:start -->
#### ** curl **
```bash
curl --location 'https://api.umodelverse.ai/v1/images/generations' \
  --header "Authorization: Bearer $MODELVERSE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-1.5",
    "prompt": "a beautiful flower",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "output_compression": 100
  }'
```

#### ** python **
```python
import os, base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.umodelverse.ai/v1",
    api_key=os.getenv("MODELVERSE_API_KEY", "YOUR_API_KEY")
)

res = client.images.generate(
    model="gpt-image-1.5",
    prompt="a beautiful flower",
    size="1024x1024",
    quality="high",
)

# gpt-image-1.5 returns base64 data
image_b64 = res.data[0].b64_json
raw = image_b64.split(",")[-1] if image_b64.startswith("data:") else image_b64
with open("image.png", "wb") as f:
    f.write(base64.b64decode(raw))
print("Saved to image.png")
```
<!-- tabs:end -->

### Image Editing

`POST https://api.umodelverse.ai/v1/images/edits`

gpt-image-1.5 supports more precise partial editing capabilities, allowing modifications to specific areas while maintaining consistent composition, tone, and character appearance in other areas, thereby avoiding complete re-drawing.

Use multipart/form-data for parameters, including at least the image to be edited, `image` (optional `mask`), as well as `model`, `prompt`, and other fields; the rest of the parameters such as `size`, `quality`, `output_format`, `output_compression` are consistent with the generation interface.

<!-- tabs:start -->
#### ** curl **
```bash
curl --location 'https://api.umodelverse.ai/v1/images/edits' \
  --header "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "image=@/path/to/your/image.png" \
  -F "mask=@/path/to/your/mask.png" \
  -F "model=gpt-image-1.5" \
  -F "prompt=Add a beach ball in the center" \
  -F "size=1024x1024" \
  -F "n=1" \
  -F "quality=high" \
  -F "output_format=png" \
  -F "output_compression=100"
```

#### ** python **
```python
import os, base64, requests

url = "https://api.umodelverse.ai/v1/images/edits"
headers = {"Authorization": f"Bearer {os.getenv('MODELVERSE_API_KEY', '$MODELVERSE_API_KEY')}"}

files = {
    "image": ("beach.png", open("beach.png", "rb"), "image/png"),
    # Optional: Provide a mask to limit the editing area
    # "mask": ("mask.png", open("mask.png", "rb"), "image/png"),
}

data = {
    "model": "gpt-image-1.5",
    "prompt": "Add a beach ball in the center",
    "size": "1024x1024",
    "n": "1",
    "quality": "high",
    "output_format": "png",
    "output_compression": "100",
}

r = requests.post(url, headers=headers, files=files, data=data)
r.raise_for_status()
resp = r.json()

image_b64 = resp["data"][0]["b64_json"]
raw = image_b64.split(",")[-1] if image_b64.startswith("data:") else image_b64
with open("edit.png", "wb") as f:
    f.write(base64.b64decode(raw))
print("Saved to edit.png")
```
<!-- tabs:end -->

### Response

```json
{
  "created": 1750667997,
  "data":
  [
    {
      "b64_json": "{image_base64_string}"
    }
  ],
  "usage":
  {
    "total_tokens": 4169,
    "input_tokens": 9,
    "output_tokens": 4160,
    "input_tokens_details":
    {
      "text_tokens": 9
    }
  }
}
```

```json
{
  "error": {
    "message": "error_message",
    "type": "error_type",
    "param": "request_id",
    "code": "error_code"
  }
}
```