How to call gpt-image-1 with configuration

GPT-Image-1 model exposes certain request parameters—such as quality, size, and background—that are missing from the DIAL chat completion request.

However, DIAL supports passing these model-specific parameters through the custom_fields.configuration field in the chat completion request.

This notebook demonstrates how to call the GPT-Image-1 model with those additional parameters using DIAL’s configuration mechanics.

View Jupyter Notebook

Setup

Install the necessary dependencies and import the libraries we are going to use.

!pip install -q openai==1.43.0
!pip install -q httpx==0.27.2
!pip install -q pillow==11.1.0
!pip install -q python-dotenv==1.0.1

import openai # OpenAI Python library to make API calls to DIAL Chat Completion API
import httpx # HTTP client library to make API calls to DIAL File API
from PIL import Image  # used to print images
from dotenv import load_dotenv # used to pick up DIAL credential from the local .env file if it exists
from json import dumps # better json print

def jprint(x):
   print(dumps(x, indent=2))

load_dotenv(override=True)

Set the DIAL URL and your API key either by setting them in the local .env file or by setting the variables in the notebook explicitly.

import os

dial_url = os.environ.get("DIAL_URL") or "YOUR_DIAL_URL"
dial_api_key = os.environ.get("DIAL_API_KEY") or "YOUR_DIAL_API_KEY"
dial_deployment = os.environ.get("GPT_IMAGE_4_DEPLOYMENT_NAME") or "YOUR_GPT_IMAGE_4_DEPLOYMENT_NAME"
api_version = os.environ.get("GPT_IMAGE_4_API_VERSION") or "2025-04-01-preview"

Configure HTTP client to call the DIAL API:

http_client = httpx.Client(base_url=dial_url, headers={"api-key": dial_api_key})

Listing metadata

First of all, we need to make sure that the given deployment does actually exist and is available for us to use.

This could be done by inspecting the listing information for this deployment:

listing_response = http_client.get(f"/openai/deployments/{dial_deployment}")
listing_response.raise_for_status()
deployment_metadata = listing_response.json()
jprint(deployment_metadata)

{
  "id": "gpt-image-1",
  "model": "gpt-image-1",
  "display_name": "gpt-image-1",
  "description": "",
  "reference": "gpt-image-1",
  "owner": "organization-owner",
  "object": "model",
  "status": "succeeded",
  "created_at": 1774012607205,
  "updated_at": 1774441059651,
  "features": {
    "rate": false,
    "tokenize": false,
    "truncate_prompt": false,
    "configuration": true,
    "system_prompt": true,
    "tools": false,
    "seed": false,
    "url_attachments": false,
    "folder_attachments": false,
    "allow_resume": true,
    "accessible_by_per_request_key": true,
    "content_parts": false,
    "temperature": true,
    "cache": false,
    "auto_caching": false,
    "parallel_tool_calls": true,
    "assistant_attachments_in_request": false
  },
  "defaults": {},
  "description_keywords": [],
  "max_retry_attempts": 1,
  "lifecycle_status": "generally-available",
  "capabilities": {
    "scale_types": [
      "standard"
    ],
    "completion": false,
    "chat_completion": true,
    "embeddings": false,
    "fine_tune": false,
    "inference": false
  }
}

Troubleshooting

The request fails when either of the dial_* variables is not set correctly.

Incorrect DIAL URL leads in ConnectError

Incorrect API key leads to 401 Unauthorized error

Non existing deployment name results in 404 Not Found error

In the last case, you may request the whole listing and pick the correct deployment name for GPT-Image-1 in your DIAL instance:
all_models = http_client.get("/openai/deployments").json()

What is of interest to us is the features supported by this model. The feature flags are stored in the features field of the deployment listing. The flag features.configuration indicates that the model is configurable.

features = deployment_metadata['features']
print("Deployment features:")
jprint(features)

is_configurable = features['configuration']
print("-" * 30)
print(f"Deployment is configurable: {is_configurable}")
assert is_configurable, "Deployment is not configurable"

Deployment features:
{
  "rate": false,
  "tokenize": false,
  "truncate_prompt": false,
  "configuration": true,
  "system_prompt": true,
  "tools": false,
  "seed": false,
  "url_attachments": false,
  "folder_attachments": false,
  "allow_resume": true,
  "accessible_by_per_request_key": true,
  "content_parts": false,
  "temperature": true,
  "cache": false,
  "auto_caching": false,
  "parallel_tool_calls": true,
  "assistant_attachments_in_request": false
}
------------------------------
Deployment is configurable: True

Configuration schema

A deployment is configurable when it exposes the configuration endpoint: v1/models/{model_name}/configuration. This endpoint returns JSON Schema for the configuration object that can be passed to the model in chat completion requests.

configuration_schema_response = http_client.get(f"/v1/deployments/{dial_deployment}/configuration")
configuration_schema_response.raise_for_status()
configuration_schema = configuration_schema_response.json()
jprint(configuration_schema)

{
  "title": "GptImage1Config",
  "type": "object",
  "properties": {
    "background": {
      "title": "Background",
      "description": "Allows to set transparency for the background of the generated image(s).\nMust be one of `transparent`, `opaque` or `auto` (default value).\nWhen `auto` is used, the model will automatically determine the best\nbackground for the image.\n\nIf `transparent`, the output format needs to support transparency, so it should\nbe set to either `png` (default value) or `webp`.",
      "anyOf": [
        {
          "enum": [
            "transparent",
            "opaque",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "string"
        }
      ]
    },
    "moderation": {
      "title": "Moderation",
      "description": "Control the content-moderation level for generated images.\nMust be either `low` for less restrictive filtering or `auto` (default value).",
      "anyOf": [
        {
          "enum": [
            "low",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "string"
        }
      ]
    },
    "output_compression": {
      "title": "Output Compression",
      "description": "The compression level (0-100%) for the generated images. This parameter is only\nsupported with the `webp` or `jpeg` output formats, and defaults to 100.",
      "type": "integer"
    },
    "output_format": {
      "title": "Output Format",
      "description": "The format in which the generated images are returned.\nMust be one of `png`, `jpeg`, or `webp`.",
      "anyOf": [
        {
          "enum": [
            "png",
            "jpeg",
            "webp"
          ],
          "type": "string"
        },
        {
          "type": "string"
        }
      ]
    },
    "quality": {
      "title": "Quality",
      "description": "The quality of the image that will be generated.",
      "anyOf": [
        {
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "type": "string"
        },
        {
          "type": "string"
        }
      ]
    },
    "size": {
      "title": "Size",
      "description": "Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value)",
      "anyOf": [
        {
          "enum": [
            "1024x1024",
            "1536x1024",
            "1024x1536",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "string"
        }
      ]
    }
  }
}

The schema says that the configuration may contain any of the following optional fields: - background - the quality of the generated image (transparent, opaque and other…) - size - the size of the generated image (one of 1024x1024, 1536x1024 and other…) - quality - the style of the generated image (high, natural and other…)

Image generation

The DIAL deployment could be called via OpenAI Python SDK.

openai_client = openai.AzureOpenAI(
    azure_endpoint=dial_url,
    azure_deployment=dial_deployment,
    api_key=dial_api_key,
    api_version=api_version,
)

Let’s call the model with the configuration provided in the custom_fields.configuration field of the chat completion request.

The first user message contains the prompt for the GPT-Image-1 model.

model_config = {
    "background": "transparent",
    "quality": "high",
    "size": "1024x1024",
}
prompt = "Sleeping fat cat."

chat_completion = openai_client.chat.completions.create(
    messages=[{"role": "user", "content": prompt}],
    model=dial_deployment,
    extra_body={"custom_fields": {"configuration": model_config}}
)
print(chat_completion)

ChatCompletion(id='chatcmpl-0d6eae64-bd5f-4875-9eed-2bfafac52dfc', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='', refusal=None, role='assistant', function_call=None, tool_calls=None, custom_content={'attachments': [{'type': 'image/png', 'title': 'Image', 'url': 'files/42sFNoaKe2cF13S6uidEyRcMZGGFpPvdKwd2akTXEAPt/appdata/gpt-image-1/images/8c037e0e3871743191d68f48a72a8ee0daadd2355c2bea9f361d02aa34d1fa55.png'}]}))], created=1774510361, model='gpt-image-1', object='chat.completion', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=1, prompt_tokens=0, total_tokens=1))

Note

The configuration value that doesn’t follow the schema (such as {"quality": 42}) will lead to an invalid request error.

The chat completion response contains custom_content attachments that store the URL of the generated image.

message = chat_completion.choices[0].message
attachments = message.custom_content["attachments"]
jprint(attachments)

[
  {
    "type": "image/png",
    "title": "Image",
    "url": "files/42sFNoaKe2cF13S6uidEyRcMZGGFpPvdKwd2akTXEAPt/appdata/gpt-image-1/images/8c037e0e3871743191d68f48a72a8ee0daadd2355c2bea9f361d02aa34d1fa55.png"
  }
]

Now we can easily download image by URL.

It could be accessed via the DIAL File API:

image_url = attachments[0]["url"]
print(f"Image URL: {image_url}")

Image URL: files/42sFNoaKe2cF13S6uidEyRcMZGGFpPvdKwd2akTXEAPt/appdata/gpt-image-1/images/8c037e0e3871743191d68f48a72a8ee0daadd2355c2bea9f361d02aa34d1fa55.png

# set a directory to save images to
image_dir_name = "images"
image_dir = os.path.join(os.curdir, image_dir_name)
image_filepath = os.path.join(image_dir, "generated_image.png")

os.makedirs(image_dir, exist_ok=True)

file = http_client.get(f"v1/{image_url}")

# save the image to the image directory
with open(image_filepath, "wb") as image_file:
    image_file.write(file.content)
print(f"Image was saved to {image_filepath}")

Image was saved to ./images/generated_image.png

display(Image.open(image_filepath))

Setup​

Listing metadata​

Configuration schema​

Image generation​

Setup

Listing metadata

Configuration schema

Image generation