Generating Images

What it is

An image generation model creates a picture from a written description, called the prompt. Many can also edit an existing image by following an instruction, for example to replace a background or change a region. In Foundry you deploy an image model, test it in the Images playground, then call it from code.

How it works

Image models

Foundry offers the gpt-image family of image models, for example gpt-image-1 and newer versions in the same family, which differ in quality, speed, supported sizes and access. An earlier model, DALL-E 3, has been retired, so new work uses the gpt-image family. Check the model catalog for the models available to your subscription.

Making a request

The request names the deployment and carries the prompt and a few options.

result = openai.images.generate(
    model="your-image-deployment",
    prompt="A watercolour of a lighthouse at sunrise, soft colours",
    size="1024x1024",
    quality="medium",
    n=1,
)

import base64
image_bytes = base64.b64decode(result.data[0].b64_json)
with open("lighthouse.png", "wb") as f:
    f.write(image_bytes)

Images from gpt-image-1 models always come back as base64 encoded data in the b64_json field, not as a web address. The app decodes the data and saves or displays it. A parameter such as response_format is not used for gpt-image-1, and style is not a gpt-image parameter. Some newer models in the family can also return other formats, so check the documentation for the model you deploy.

Editing an image

The edit operation takes one or more input images, a prompt, and optionally a mask. The transparent area of the mask marks the part to change. Edits are useful for removing objects, changing a background or adding an element. The result is a modified picture, not a description.

Writing good image prompts

• Name the subject, the setting and the style, for example "a watercolour of a lighthouse at sunrise".
• Add details such as colours, lighting, camera angle or mood.
• Say what to avoid or what must not change when editing.
• Create a few variations with n, then refine the wording of the best one.

The Images playground

The Images playground in Foundry lets you type a prompt and see the picture from an image generation deployment without writing code. You can change the size and quality and then view the sample code for the same settings, which you can copy into an app.

Safety, provenance and limits

• Content filters screen the prompt and the generated image, and block harmful requests.
• Provenance information, also called content credentials, is added to images from Azure image models, so that they can be identified as AI generated.
• Rate limits restrict how many images you can create per minute for each deployment, so an app should handle a 429 error by waiting and retrying.
• Generated images can contain mistakes, such as distorted hands or garbled text, so review them before use.

Image generation compared with image understanding

A worked scenario

A marketing team needs hero images for a campaign. A developer deploys an image model and tries prompts in the Images playground until a watercolour style looks right, then copies the sample code. The app sends the prompt with a size of 1024x1024 and quality set to medium, decodes the b64_json result and saves a PNG. For one image the team wants a plain white background replaced with a beach, so it uses the edit operation with a mask over the background. Because the app generates many images during a campaign, it retries after HTTP 429 responses.