Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing 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.
Prerequisites
- An Azure subscription. You can create one for free.
- An Azure OpenAI resource created in a supported region. See Region availability.
- Deploy a
dall-e-3orgpt-image-1series model with your Azure OpenAI resource. For more information on deployments, see Create a resource and deploy a model with Azure OpenAI.- GPT-image-1 models are newer and feature a number of improvements over DALL-E 3. They are available in limited access: apply for access with this form.
Overview
- Use image generation via image generation API or responses API
- Experiment with image generation in the image playground
- Learn about image generation tokens
| Aspect | GPT-Image-1 | GPT-Image-1-Mini | DALL·E 3 |
|---|---|---|---|
| Input / Output Modalities & Format | Accepts text + image inputs; outputs images only in base64 (no URL option). | Accepts text + image inputs; outputs images only in base64 (no URL option). | Accepts text (primary) input; limited image editing inputs (with mask). Outputs as URL 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) |
Only 1 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 | ✅ Advanced face preservation for realistic, consistent results | ❌ No dedicated face preservation; better for non-portrait/general creative imagery | ❌ No dedicated face preservation |
| Performance & Cost | High-fidelity, realism-optimized model; higher latency and cost | Cost-efficient and faster for large-scale or iterative generation | Balanced performance; higher latency on complex prompts |
| Strengths | Best for realism, instruction following, and multimodal context | Best for fast prototyping, bulk generation, or cost-sensitive use cases | Strong prompt adherence, natural text rendering, and stylistic diversity |
Responsible AI and Image Generation
Azure OpenAI image generation models include built-in Responsible AI (RAI) protections to help ensure safe and compliant use. We provide 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:
- Learn more: Explorecontent filtering
- Request customization: Apply to opt out of content filtering
Certain Enterprise Agreement (EA) customers, those with significant usage volume, or customers with approved use cases may also be eligible to enable photo transformations (i.e. applying image edits) to images containing minors. If you're approved, such images will not be automatically blocked by the system.
Call the image generation API
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 the quickstart.
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, see Image tokens.
Output
The response from a successful image generation API call looks like the following example. The b64_json field contains the output image data.
{
"created": 1698116662,
"data": [
{
"b64_json": "<base64 image data>"
}
]
}
Note
The response_format parameter isn't supported for GPT-image-1, which always returns base64-encoded images.
Streaming
You can stream image generation requests to gpt-image-1 by setting the stream parameter to true, and setting the partial_images parameter to a value between 0 and 3.
import base64
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_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)
API call rejection
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, the error.code value in the message is set to contentFilter. 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 to Generated 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."
}
}
Write effective text-to-image prompts
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, see Content filtering.
Tip
For a thorough look at how you can tweak your text prompts to generate different kinds of images, see the Image prompt engineering guide.
Specify API options
The following API body parameters are available for image generation models.
Size
Specify the size of the generated images. Must be one of 1024x1024, 1024x1536, or 1536x1024 for GPT-image-1 models. Square images are faster to generate.
Quality
There are three options for image quality: low, medium, and high. Lower quality images can be generated faster.
The default value is high.
Number
You can generate between one and 10 images in a single API call. The default value is 1.
User ID
Use the user 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.
Output format
Use the output_format parameter to specify the format of the generated image. Supported formats are PNG and JPEG. The default is PNG.
Note
WEBP images aren't supported in the Azure OpenAI in Azure AI Foundry Models.
Compression
Use the output_compression parameter to specify the compression level for the generated image. Input an integer between 0 and 100, where 0 is no compression and 100 is maximum compression. The default is 100.
Streaming
Use the stream parameter to enable streaming responses. When set to true, the API returns partial images as they're generated. This feature provides faster visual feedback for users and improves perceived latency. Set the partial_images parameter to control how many partial images are generated (1-3).
Call the image edit API
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"
API response output
The response from a successful image editing API call looks like the following example. The b64_json field contains the output image data.
{
"created": 1698116662,
"data": [
{
"b64_json": "<base64 image data>"
}
]
}
Specify image edit API options
The following API body parameters are available for image editing models, in addition to the ones available for image generation models.
Image
The image value indicates the image file you want to edit.
Input fidelity
The input_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 the gpt-image-1-mini model.
Mask
The mask parameter uses the same type as the main image 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.
Streaming
Use the stream parameter to enable streaming responses. When set to true, the API returns partial images as they're generated. This feature provides faster visual feedback for users and improves perceived latency. Set the partial_images parameter to control how many partial images are generated (1-3).