# gpt-image-1-mini API This document introduces the input and output parameters for calling the `gpt-image-1-mini` 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 word | | model | string | Required | - | The model name used for this request, which is `gpt-image-1-mini`. | | n | int | Optional | 1 | Number of images generated, with a range of 1 to 10 | | size | string | Optional | `1024x1536` | Resolution. Supports `1024x1024`, `1024x1536`, `1536x1024`. | | quality | string | Optional | - | Image quality, supports `low`, `medium`, `high`; higher quality takes longer time. | | background | string | Optional | `auto` | Background transparency, supports `transparent`, `opaque`, `auto`. When set to `transparent`, use together with `output_format=png`. | | moderation | string | Optional | `auto` | Content moderation level, supports `auto` (default), `low` (lenient). | | output_format | string | Optional | `png` | Output image format, supports `png`, `jpeg`. | | output_compression | int | Optional | - | Image compression strength, with a range of 0 to 100; `0` means no compression, `100` means maximum compression. Only applies to `jpeg` format. | | user | string | Optional | - | End-user identifier, passed through to upstream for abuse detection, does not affect generation results. | ## Response Parameters | Field Name | Type | Description | | ----------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | created | `integer` | Unix timestamp (seconds) when the request was created. | | background | `string` | The background type of the generated image, corresponding to the request parameter `background`, e.g. `opaque`, `transparent`. | | output_format | `string` | The format of the generated image, corresponding to the request parameter `output_format`, e.g. `png`, `jpeg`. | | quality | `string` | The quality of the generated image, corresponding to the request parameter `quality`, e.g. `low`, `medium`, `high`. | | size | `string` | The resolution of the generated image, corresponding to the request parameter `size`, e.g. `1024x1024`. | | data | `array` | Information about the output image. The gpt-image-1-mini model returns base64 data.
• `b64_json`: Base64-encoded image data; decoding it yields the raw image file. | | usage | `object` | Token usage for this request. | | usage.input_tokens | `integer` | Total number of tokens consumed by the input. | | usage.input_tokens_details.text_tokens | `integer` | Number of tokens consumed by the text prompt in the input. | | usage.input_tokens_details.image_tokens | `integer` | Number of tokens consumed by images in the input (has a value when images are passed via the image editing interface; 0 for text-to-image generation). | | usage.output_tokens | `integer` | Total number of tokens consumed by the output. | | usage.output_tokens_details.image_tokens | `integer` | Number of tokens consumed by the output image. | | usage.total_tokens | `integer` | Total number of tokens consumed by this request. | | 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-1-mini", "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-1-mini", prompt="a beautiful flower", size="1024x1024", quality="high", ) # gpt-image-1-mini 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` Use multipart/form-data to pass parameters, which include at least `image` (optional `mask`) to be edited, along with fields such as `model`, `prompt`, etc. Other parameters like `size`, `quality`, `output_format`, `output_compression` are consistent with the generation interface. > **mask note**: mask is an optional parameter used to specify the area of the image to be edited (transparent area = area to edit, opaque area = area to preserve). The following two conditions must be met when using it: > 1. Must be in **PNG format with an alpha channel (RGBA mode)**; plain RGB PNG or JPEG is not supported. > 2. The dimensions must be **exactly the same** as the source `image`. #### ** 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-1-mini" \ -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-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 specify the editing area # "mask": ("mask.png", open("mask.png", "rb"), "image/png"), } data = { "model": "gpt-image-1-mini", "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") ``` ### Response ```json { "created": 1748484857, "background": "opaque", "output_format": "png", "quality": "low", "size": "1024x1024", "data": [ { "b64_json": "{image_base64_string}" } ], "usage": { "total_tokens": 280, "input_tokens": 8, "output_tokens": 272, "input_tokens_details": { "image_tokens": 0, "text_tokens": 8 }, "output_tokens_details": { "image_tokens": 272, "text_tokens": 0 } } } ``` ```json { "error": { "message": "error_message", "type": "error_type", "param": "request_id", "code": "error_code" } } ```