This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
Access to this page requires authorization. You can trysigning in orchanging directories.
Access to this page requires authorization. You can trychanging directories.
OpenAI's image generation models create images from user-provided text prompts and optional images. This article explains how to use these models, configure options, and benefit from advanced image generation capabilities in Azure.
dall-e-3 orgpt-image-1-series model with your Azure OpenAI resource. For more information on deployments, seeCreate a resource and deploy a model with Azure OpenAI.| Aspect | GPT-Image-1 | GPT-Image-1-Mini | DALL·E 3 |
|---|---|---|---|
| Input / Output Modalities & Format | Acceptstext + image inputs; outputs images only inbase64 (no URL option). | Acceptstext + image inputs; outputs images only inbase64 (no URL option). | Acceptstext (primary) input; limited image editing inputs (with mask). Outputs asURL or base64. |
| Image Sizes / Resolutions | 1024×1024, 1024×1536, 1536×1024 | 1024×1024, 1024×1536, 1536×1024 | 1024×1024, 1024×1792, 1792×1024 |
| Quality Options | low,medium,high (default = high) | low,medium,high (default = medium) | standard,hd; style options:natural,vivid |
| Number of Images per Request | 1–10 images per request (n parameter) | 1–10 images per request (n parameter) | Only1 image per request (n must be 1) |
| Editing (inpainting / variations) | Yes — supports inpainting and variations with mask + prompt | Yes — supports inpainting and variations with mask + prompt | Yes — supports inpainting and variations |
| Face Preservation | ✅ Advancedface preservation for realistic, consistent results | ❌ No dedicated face preservation; better fornon-portrait/general creative imagery | ❌ No dedicated face preservation |
| Performance & Cost | High-fidelity,realism-optimized model; higher latency and cost | Cost-efficient andfaster for large-scale or iterative generation | Balanced performance; higher latency on complex prompts |
| Strengths | Best forrealism,instruction following, andmultimodal context | Best forfast prototyping,bulk generation, orcost-sensitive use cases | Strongprompt adherence,natural text rendering, andstylistic diversity |
Azure OpenAI's image generation models include built-in Responsible AI (RAI) protections to help ensure safe and compliant use.
In addition, Azure provides input and output moderation across all image generation models, along with Azure-specific safeguards such as content filtering and abuse monitoring. These systems help detect and prevent the generation or misuse of harmful, unsafe, or policy-violating content.
Customers can learn more about these safeguards and how to customize them here:
Photorealistic images of minors are blocked by default. Customers canrequest access to this model capability. Enterprise-tier customers are automatically approved.
The following command shows the most basic way to use an image model with code. If this is your first time using these models programmatically, start with thequickstart.
Send a POST request to:
https://<your_resource_name>.openai.azure.com/openai/deployments/<your_deployment_name>/images/generations?api-version=<api_version>URL:
Replace the following values:
<your_resource_name> is the name of your Azure OpenAI resource.<your_deployment_name> is the name of your DALL-E 3 or GPT-image-1 model deployment.<api_version> is the version of the API you want to use. For example,2025-04-01-preview.Required headers:
Content-Type:application/jsonapi-key:<your_API_key>Body:
The following is a sample request body. You specify a number of options, defined in later sections.
{ "prompt": "A multi-colored umbrella on the beach, disposable camera", "model": "gpt-image-1", "size": "1024x1024", "n": 1, "quality": "high"}Tip
For image generation token costs, seeImage tokens.
The response from a successful image generation API call looks like the following example. Theb64_json field contains the output image data.
{ "created": 1698116662, "data": [ { "b64_json": "<base64 image data>" } ]}Note
Theresponse_format parameter isn't supported for GPT-image-1, which always returns base64-encoded images.
You can stream image generation requests togpt-image-1 by setting thestream parameter totrue, and setting thepartial_images parameter to a value between 0 and 3.
import base64from openai import OpenAIfrom azure.identity import DefaultAzureCredential, get_bearer_token_providertoken_provider = get_bearer_token_provider( DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")client = OpenAI( base_url = "https://RESOURCE-NAME-HERE/openai/v1/", api_key=token_provider, default_headers={"api_version":"preview"})stream = client.images.generate( model="gpt-image-1", prompt="A cute baby sea otter", n=1, size="1024x1024", stream=True, partial_images = 2)for event in stream: if event.type == "image_generation.partial_image": idx = event.partial_image_index image_base64 = event.b64_json image_bytes = base64.b64decode(image_base64) with open(f"river{idx}.png", "wb") as f: f.write(image_bytes)Prompts and images are filtered based on our content policy. The API returns an error when a prompt or image is flagged.
If your prompt is flagged, theerror.code value in the message is set tocontentFilter. Here's an example:
{ "created": 1698435368, "error": { "code": "contentFilter", "message": "Your task failed as a result of our safety system." }}It's also possible that the generated image itself is filtered. In this case, the error message is set toGenerated image was filtered as a result of our safety system. Here's an example:
{ "created": 1698435368, "error": { "code": "contentFilter", "message": "Generated image was filtered as a result of our safety system." }}Your prompts should describe the content you want to see in the image and the visual style of the image.
When you write prompts, consider that the Image APIs come with a content moderation filter. If the service recognizes your prompt as harmful content, it doesn't generate an image. For more information, seeContent filtering.
Tip
For a thorough look at how you can tweak your text prompts to generate different kinds of images, see theImage prompt engineering guide.
The following API body parameters are available for image generation models.
Specify the size of the generated images. Must be one of1024x1024,1024x1536, or1536x1024 for GPT-image-1 models. Square images are faster to generate.
There are three options for image quality:low,medium, andhigh. Lower quality images can be generated faster.
The default value ishigh.
You can generate between one and 10 images in a single API call. The default value is1.
Use theuser parameter to specify a unique identifier for the user making the request. This identifier is useful for tracking and monitoring usage patterns. The value can be any string, such as a user ID or email address.
Use theoutput_format parameter to specify the format of the generated image. Supported formats arePNG andJPEG. The default isPNG.
Note
WEBP images aren't supported in the Azure OpenAI in Microsoft Foundry Models.
Use theoutput_compression parameter to specify the compression level for the generated image. Input an integer between0 and100, where0 is no compression and100 is maximum compression. The default is100.
Use thestream parameter to enable streaming responses. When set totrue, the API returns partial images as they're generated. This feature provides faster visual feedback for users and improves perceived latency. Set thepartial_images parameter to control how many partial images are generated (1-3).
Set thebackground parameter totransparent andoutput_format toPNG on an image generate request to get an image with a transparent background.
The Image Edit API enables you to modify existing images based on text prompts you provide. The API call is similar to the image generation API call, but you also need to provide an input image.
Important
The input image must be less than 50 MB in size and must be a PNG or JPG file.
Send a POST request to:
https://<your_resource_name>.openai.azure.com/openai/deployments/<your_deployment_name>/images/edits?api-version=<api_version>URL:
Replace the following values:
<your_resource_name> is the name of your Azure OpenAI resource.<your_deployment_name> is the name of your DALL-E 3 or GPT-image-1 model deployment.<api_version> is the version of the API you want to use. For example,2025-04-01-preview.Required headers:
Content-Type:multipart/form-dataapi-key:<your_API_key>Body:
The following is a sample request body. You specify a number of options, defined in later sections.
Important
The Image Edit API takes multipart/form data, not JSON data. The example below shows sample form data that would be attached to a cURL request.
-F "image[]=@beach.png" \-F 'prompt=Add a beach ball in the center' \-F "model=gpt-image-1" \-F "size=1024x1024" \-F "n=1" \-F "quality=high"The response from a successful image editing API call looks like the following example. Theb64_json field contains the output image data.
{ "created": 1698116662, "data": [ { "b64_json": "<base64 image data>" } ]}The following API body parameters are available for image editing models, in addition to the ones available for image generation models.
Theimage value indicates the image file you want to edit.
Theinput_fidelity parameter controls how much effort the model puts into matching the style and features, especially facial features, of input images.
This parameter lets you make subtle edits to an image without changing unrelated areas. When you use high input fidelity, faces are preserved more accurately than in standard mode.
Important
Input fidelity is not supported by thegpt-image-1-mini model.
Themask parameter uses the same type as the mainimage input parameter. It defines the area of the image that you want the model to edit, using fully transparent pixels (alpha of zero) in those areas. The mask must be a PNG file and have the same dimensions as the input image.
Use thestream parameter to enable streaming responses. When set totrue, the API returns partial images as they're generated. This feature provides faster visual feedback for users and improves perceived latency. Set thepartial_images parameter to control how many partial images are generated (1-3).
Set thebackground parameter totransparent andoutput_format toPNG on an image generate request to get an image with a transparent background.
Was this page helpful?
Need help with this topic?
Want to try using Ask Learn to clarify or guide you through this topic?
Was this page helpful?
Want to try using Ask Learn to clarify or guide you through this topic?