# gpt-image-2 API
This document introduces the input and output parameters for calling the `gpt-image-2` model API, which you can refer to 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-2`. |
| n | int | Optional | 1 | Number of images to generate, ranging from 1 to 10 |
| size | string | Optional | "auto" | Resolution. GPT‑image‑2 supports arbitrary resolutions: both width and height must be multiples of 16 pixels; maximum supported resolution is 3840 pixels (4K); maximum aspect ratio is 3:1; total pixel count ranges from 655,360 to 8,294,400. Recommended: `1024x1024`, `1024x1536`, `1536x1024`, `2048x2048`, `2048x1152`, `2160x3840`. |
| quality | string | Optional | - | Image quality, supporting `low`, `medium`, `high`; higher quality takes longer. |
| output_format | string | Optional | "png" | Output image format, supporting `png`, `jpeg`. |
| 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-2 model returns base64 data.
• When specifying the return format of the generated image as url, the corresponding parameter sub-field is url;
• When specifying the return format of the generated image as b64_json, the corresponding parameter sub-field is b64_json.
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 |
## Examples
### OPENAI Compatible Interface
`POST https://api-us-ca.umodelverse.ai/v1/images/generations`
#### Synchronous Request
#### ** curl **
```bash
curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \
--header "Authorization: Bearer $MODELVERSE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2",
"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-us-ca.umodelverse.ai/v1",
api_key=os.getenv("MODELVERSE_API_KEY", "YOUR_API_KEY")
)
res = client.images.generate(
model="gpt-image-2",
prompt="a beautiful flower",
size="1024x1024",
quality="high",
)
# gpt-image-2 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")
```
### Image Editing
`POST https://api-us-ca.umodelverse.ai/v1/images/edits`
gpt-image-2 supports two editing modes:
- **Partial Edit**: Modifies specific areas of a single image while maintaining consistent composition, tone, and character appearance in other areas, avoiding complete re-drawing. Use the `mask` field to restrict the editing area.
- **Multi-Image Synthesis**: Pass multiple reference images via the repeatable `image[]` field, and the model blends all images into one new image. Suitable for gift box combinations, product collages, scene compositing, and similar use cases.
Use multipart/form-data for parameters, including at least the image(s) to be edited — `image` (single image) or `image[]` (multiple images, repeatable) — 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.
#### ** curl **
```bash
curl --location 'https://api-us-ca.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-2" \
-F "prompt=Add a beach ball in the center" \
-F "size=1024x1024" \
-F "n=1" \
-F "quality=low" \
-F "output_format=png" \
-F "output_compression=100"
```
#### ** python **
```python
import os, base64, requests
url = "https://api-us-ca.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-2",
"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")
```
#### Multi-Image Synthesis Example
Combine multiple product images into a single gift basket display image by passing multiple images via the repeatable `image[]` field:
**Input Images (4 images)**
| body-lotion.png | bath-bomb.png | incense-kit.png | soap.png |
|:---:|:---:|:---:|:---:|
|  |  |  |  |
**Output Image**
#### ** curl **
```bash
curl --location 'https://api-us-ca.umodelverse.ai/v1/images/edits' \
--header "Authorization: Bearer $MODELVERSE_API_KEY" \
-F "model=gpt-image-2" \
-F "image[]=@./body-lotion.png" \
-F "image[]=@./bath-bomb.png" \
-F "image[]=@./incense-kit.png" \
-F "image[]=@./soap.png" \
-F "prompt=a beautiful gift basket containing all these products arranged elegantly"
```
#### ** python **
```python
import os, base64, requests
url = "https://api-us-ca.umodelverse.ai/v1/images/edits"
headers = {"Authorization": f"Bearer {os.getenv('MODELVERSE_API_KEY', '$MODELVERSE_API_KEY')}"}
image_paths = [
"body-lotion.png",
"bath-bomb.png",
"incense-kit.png",
"soap.png",
]
# image[] repeatable field must be passed as a list
files = [("image[]", (p, open(p, "rb"), "image/png")) for p in image_paths]
data = {
"model": "gpt-image-2",
"prompt": "a beautiful gift basket containing all these products arranged elegantly",
}
r = requests.post(url, headers=headers, files=files, data=data)
r.raise_for_status()
resp = r.json()
image_b64 = resp["data"][0]["b64_json"]
with open("output.png", "wb") as f:
f.write(base64.b64decode(image_b64))
print("Saved to output.png")
```
> **Note**: No `mask` is needed for multi-image synthesis; output size is automatically determined by the model and may not be square.
### 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"
}
}
```