Important

The DALL-E image generation model dall-e-3 was retired on March 4, 2026, and is no longer available for new deployments. Existing deployments are non-functional. Use gpt-image-1 or gpt-image-1.5 for image generation instead. See the image generation how-to guide for updated instructions.

Use this guide to get started calling the Azure OpenAI in Microsoft Foundry Models image generation REST APIs by using Python.

Prerequisites

• An Azure subscription. Create one for free.
• Python 3.8 or later version.
• The following Python libraries installed: os, requests, json.
• An Azure OpenAI resource created in a supported region. See Region availability.
• Then, you need to deploy a gpt-image-1-series model with your Azure resource. For more information, see Create a resource and deploy a model with Azure OpenAI.

Setup

Retrieve key and endpoint

To successfully call the Azure OpenAI APIs, you need the following information about your Azure OpenAI resource:

Go to your resource in the Azure portal. On the navigation pane, select Keys and Endpoint under Resource Management. Copy the Endpoint value and an access key value. You can use either the KEY 1 or KEY 2 value. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption.

Environment variables

Create and assign persistent environment variables for your key and endpoint.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE"

Create a new Python application

Create a new Python file named quickstart.py. Open the new file in your preferred editor or IDE.

1. Replace the contents of quickstart.py with the following code. Change the value of prompt to your preferred text. Also set deployment to the deployment name you chose when you deployed the GPT-image-1 series model.

   import os
   import requests
   import base64
   from PIL import Image
   from io import BytesIO
   
   # set environment variables
   endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
   subscription_key = os.getenv("AZURE_OPENAI_API_KEY")
   
   deployment = "gpt-image-1.5" # the name of your GPT-image-1 series deployment
   api_version = "2025-04-01-preview" # or later version
   
   def decode_and_save_image(b64_data, output_filename):
     image = Image.open(BytesIO(base64.b64decode(b64_data)))
     image.show()
     image.save(output_filename)
   
   def save_all_images_from_response(response_data, filename_prefix):
     for idx, item in enumerate(response_data['data']):
       b64_img = item['b64_json']
       filename = f"{filename_prefix}_{idx+1}.png"
       decode_and_save_image(b64_img, filename)
       print(f"Image saved to: '{filename}'")
   
   base_path = f'openai/deployments/{deployment}/images'
   params = f'?api-version={api_version}'
   
   generation_url = f"{endpoint}{base_path}/generations{params}"
   generation_body = {
     "prompt": "girl falling asleep",
     "n": 1,
     "size": "1024x1024",
     "quality": "medium",
     "output_format": "png"
   }
   generation_response = requests.post(
     generation_url,
     headers={
       'Api-Key': subscription_key,
       'Content-Type': 'application/json',
     },
     json=generation_body
   ).json()
   save_all_images_from_response(generation_response, "generated_image")
   
   # In addition to generating images, you can edit them.
   edit_url = f"{endpoint}{base_path}/edits{params}"
   edit_body = {
     "prompt": "girl falling asleep",
     "n": 1,
     "size": "1024x1024",
     "quality": "medium"
   }
   files = {
     "image": ("generated_image_1.png", open("generated_image_1.png", "rb"), "image/png"),
     # You can use a mask to specify which parts of the image you want to edit.
     # The mask must be the same size as the input image.
     # "mask": ("mask.png", open("mask.png", "rb"), "image/png"),
   }
   edit_response = requests.post(
     edit_url,
     headers={'Api-Key': subscription_key},
     data=edit_body,
     files=files
   ).json()
   save_all_images_from_response(edit_response, "edited_image")
   

   The script makes a synchronous image generation API call.

   Important

   Remember to remove the key from your code when you're done, and never post your key publicly. For production, use a secure way of storing and accessing your credentials. For more information, see Azure Key Vault.

2. Run the application with the python command:

   python quickstart.py
   

   Wait a few moments to get the response.

Output

The output from a successful image generation API call looks like the following example. The b64_json field contains the base64-encoded output image data.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
} 

A successful response includes:

• A created timestamp (Unix epoch time)
• A data array with at least one image object- Either a b64_json (base64-encoded image data) value for each generated image

Common errors

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. For examples of error responses, see the Image generation how-to guide.

The system returns an operation status of Failed and 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."
    }
}

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for Python.

Library source code | Package | Samples

Prerequisites

• An Azure subscription. Create one for free.
• Python 3.8 or later version.
• An Azure OpenAI resource created in a compatible region. See Region availability.
  • Access the Azure OpenAI resource endpoint and keys in the Azure portal.
• A deployed image generation model:
  • GPT-image-1 series: Deploy a gpt-image-1-series model. Available in limited access.
  • GPT-image-1 series: Deploy a gpt-image-1 model. Requires limited access registration.

For more information, see Create a resource and deploy a model with Azure OpenAI.

Setup

Retrieve key and endpoint

To successfully call the Azure OpenAI APIs, you need the following information about your Azure OpenAI resource:

Go to your resource in the Azure portal. On the navigation pane, select Keys and Endpoint under Resource Management. Copy the Endpoint value and an access key value. You can use either the KEY 1 or KEY 2 value. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption.

Environment variables

Create and assign persistent environment variables for your key and endpoint.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE"

Install the Python SDK

Open a command prompt and browse to your project folder. Install the OpenAI Python SDK by using the following command:

pip install openai

Install the following libraries as well:

pip install requests
pip install pillow 

Generate images

Create a new python file, quickstart.py. Open it in your preferred editor or IDE.

Replace the contents of quickstart.py with the following code.

from openai import AzureOpenAI
import os
import requests
from PIL import Image
import json

client = AzureOpenAI(
    api_version="2025-04-01-preview",  
    api_key=os.environ["AZURE_OPENAI_API_KEY"],  
    azure_endpoint=os.environ['AZURE_OPENAI_ENDPOINT']
)

result = client.images.generate(
    model="gpt-image-1", # the name of your GPT-image-1 series deployment
    prompt="a close-up of a bear walking through the forest",
    n=1
)

json_response = json.loads(result.model_dump_json())

# Set the directory for the stored image
image_dir = os.path.join(os.curdir, 'images')

# If the directory doesn't exist, create it
if not os.path.isdir(image_dir):
    os.mkdir(image_dir)

# Initialize the image path (note the filetype should be png)
image_path = os.path.join(image_dir, 'generated_image.png')

# Retrieve the generated image
image_url = json_response["data"][0]["url"]  # extract image URL from response
generated_image = requests.get(image_url).content  # download the image
with open(image_path, "wb") as image_file:
    image_file.write(generated_image)

# Display the image in the default image viewer
image = Image.open(image_path)
image.show()

1. Make sure the AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY environment variables are set.
2. Change the value of prompt to your preferred text.
3. Change the value of model to the name of your deployed GPT-image-1 series model.

Run the application with the python command:

python quickstart.py

Wait a few moments to get the response.

Output

Azure OpenAI stores the output image in the generated_image.png file in your specified directory. The script also displays the image in your default image viewer.

A successful response includes:

• A created timestamp
• A data array with at least one image object
• Either a url (temporary link valid for 24 hours) or b64_json (base64-encoded image data)

Common errors

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.

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for C#.

Library source code | Package (NuGet) | Samples

Prerequisites

• An Azure subscription - Create one for free
• The .NET 7 SDK
• An Azure OpenAI resource created in a supported region (see Region availability). For more information, see Create a resource and deploy a model with Azure OpenAI.

Microsoft Entra ID prerequisites

For the recommended keyless authentication with Microsoft Entra ID, you need to:

• Install the Azure CLI used for keyless authentication with Microsoft Entra ID.
• Assign the Cognitive Services User role to your user account. You can assign roles in the Azure portal under Access control (IAM) > Add role assignment.

Set up

1. Create a new folder image-quickstart and go to the quickstart folder with the following command:

   mkdir image-quickstart && cd image-quickstart
   

2. Create a new console application with the following command:

   dotnet new console
   

3. Install the OpenAI .NET client library with the dotnet add package command:

   dotnet add package Azure.AI.OpenAI --version 1.0.0-beta.6
   

4. For the recommended keyless authentication with Microsoft Entra ID, install the Azure.Identity package with:

   dotnet add package Azure.Identity
   

5. For the recommended keyless authentication with Microsoft Entra ID, sign in to Azure with the following command:

   az login
   

Retrieve resource information

You need to retrieve the following information to authenticate your application with your Azure OpenAI resource:

Run the quickstart

The sample code in this quickstart uses Microsoft Entra ID for the recommended keyless authentication. If you prefer to use an API key, you can replace the DefaultAzureCredential object with an AzureKeyCredential object.

AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 

AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

To run the quickstart, follow these steps:

1. Replace the contents of Program.cs with the following code and update the placeholder values with your own.

   using Azure;
   using Azure.AI.OpenAI;
   using OpenAI.Images;
   using static System.Environment;
   
   string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? "https://<your-resource-name>.openai.azure.com/";
   string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? "<your-key>";
   
   // Use the recommended keyless credential instead of the AzureKeyCredential credential.
   AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 
   //AzureOpenAIClient openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));
   
   // This must match the custom deployment name you chose for your model
   ImageClient chatClient = openAIClient.GetImageClient("gpt-image-1");
   
   var imageGeneration = await chatClient.GenerateImageAsync(
           "a happy monkey sitting in a tree, in watercolor",
           new ImageGenerationOptions()
           {
               Size = GeneratedImageSize.W1024xH1024
           }
       );
   
   Console.WriteLine(imageGeneration.Value.ImageUri);
   

2. Run the application using the dotnet run command or the run button at the top of Visual Studio:

   dotnet run
   

Output

The URL of the generated image is printed to the console.

<SAS URL>

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for Java.

Library source code | Artifact (Maven) | Samples

Prerequisites

• An Azure subscription - Create one for free
• The current version of the Java Development Kit (JDK)
• Install Apache Maven.
• An Azure OpenAI resource created in a supported region (see Region availability). For more information, see Create a resource and deploy a model with Azure OpenAI.

Microsoft Entra ID prerequisites

For the recommended keyless authentication with Microsoft Entra ID, you need to:

• Install the Azure CLI used for keyless authentication with Microsoft Entra ID.
• Assign the Cognitive Services User role to your user account. You can assign roles in the Azure portal under Access control (IAM) > Add role assignment.

Set up

1. Create a new folder image-quickstart and go to the quickstart folder with the following command:

   mkdir image-quickstart && cd image-quickstart
   

2. Install Apache Maven. Then run mvn -v to confirm successful installation.

3. Create a new pom.xml file in the root of your project, and copy the following code into it:

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <groupId>com.azure.samples</groupId>
        <artifactId>quickstart-image-generation</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <build>
            <sourceDirectory>src</sourceDirectory>
            <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.7.0</version>
                <configuration>
                <source>1.8</source>
                <target>1.8</target>
                </configuration>
            </plugin>
            </plugins>
        </build>
        <dependencies>    
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-ai-openai</artifactId>
                <version>1.0.0-beta.3</version>
            </dependency>
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-core</artifactId>
                <version>1.53.0</version>
            </dependency>
            <dependency>
                <groupId>com.azure</groupId>
                <artifactId>azure-identity</artifactId>
                <version>1.15.1</version>
            </dependency>
            <dependency>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-simple</artifactId>
                <version>1.7.9</version>
            </dependency>
        </dependencies>
    </project>
   

4. Install the Azure OpenAI SDK and dependencies.

   mvn clean dependency:copy-dependencies
   

5. For the recommended keyless authentication with Microsoft Entra ID, sign in to Azure with the following command:

   az login
   

Retrieve resource information

You need to retrieve the following information to authenticate your application with your Azure OpenAI resource:

Run the app

The sample code in this quickstart uses Microsoft Entra ID for the recommended keyless authentication. If you prefer to use an API key, you can replace the DefaultAzureCredential object with an AzureKeyCredential object.

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(key))
    .buildAsyncClient();

Output

The URL of the generated image is printed to the console.

Image location URL that provides temporary access to download the generated image is <SAS URL>.
Completed getImages.

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for JavaScript.

Reference documentation | Source code | Package (npm) | Samples

Prerequisites

• An Azure subscription - Create one for free
• LTS versions of Node.js
• Azure CLI used for passwordless authentication in a local development environment, create the necessary context by signing in with the Azure CLI.
• An Azure OpenAI resource created in a supported region (see Region availability). For more information, see Create a resource and deploy a model with Azure OpenAI.

Microsoft Entra ID prerequisites

For the recommended keyless authentication with Microsoft Entra ID, you need to:

• Install the Azure CLI used for keyless authentication with Microsoft Entra ID.
• Assign the Cognitive Services User role to your user account. You can assign roles in the Azure portal under Access control (IAM) > Add role assignment.

Setup

1. Create a new folder image-quickstart and go to the quickstart folder with the following command:

   mkdir image-quickstart && cd image-quickstart
   

2. Create the package.json with the following command:

   npm init -y
   

3. Install the OpenAI client library for JavaScript with:

   npm install openai
   

4. For the recommended passwordless authentication:

   npm install @azure/identity
   

Retrieve resource information

You need to retrieve the following information to authenticate your application with your Azure OpenAI resource:

Generate images

Output

The URL of the generated image is printed to the console.

== Batch Image Generation ==
Image generation result URL: <SAS URL>
Image generation result URL: <SAS URL>

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for JavaScript.

Reference documentation | Source code | Package (npm) | Samples

Prerequisites

• An Azure subscription - Create one for free
• LTS versions of Node.js
• TypeScript
• Azure CLI used for passwordless authentication in a local development environment, create the necessary context by signing in with the Azure CLI.
• An Azure OpenAI resource created in a supported region (see Region availability). For more information, see Create a resource and deploy a model with Azure OpenAI.

Microsoft Entra ID prerequisites

For the recommended keyless authentication with Microsoft Entra ID, you need to:

• Install the Azure CLI used for keyless authentication with Microsoft Entra ID.
• Assign the Cognitive Services User role to your user account. You can assign roles in the Azure portal under Access control (IAM) > Add role assignment.

Setup

1. Create a new folder image-quickstart and go to the quickstart folder with the following command:

   mkdir image-quickstart && cd image-quickstart
   

2. Create the package.json with the following command:

   npm init -y
   

3. Update the package.json to ECMAScript with the following command:

   npm pkg set type=module
   

4. Install the OpenAI client library for JavaScript with:

   npm install openai
   

5. For the recommended passwordless authentication:

   npm install @azure/identity
   

Retrieve resource information

You need to retrieve the following information to authenticate your application with your Azure OpenAI resource:

Generate images

Output

The URL of the generated image is printed to the console.

== Batch Image Generation ==
Image generation result URL: <SAS URL>
Image generation result URL: <SAS URL>

Clean up resources

If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

• Azure portal
• Azure CLI

Use this guide to get started generating images with the Azure OpenAI SDK for Go.

Library source code | Package | Samples

Prerequisites

• An Azure subscription - Create one for free
• Go 1.8+
• An Azure OpenAI resource created in a supported region (see Region availability). For more information, see Create a resource and deploy a model with Azure OpenAI.

Microsoft Entra ID prerequisites

For the recommended keyless authentication with Microsoft Entra ID, you need to:

• Install the Azure CLI used for keyless authentication with Microsoft Entra ID.
• Assign the Cognitive Services User role to your user account. You can assign roles in the Azure portal under Access control (IAM) > Add role assignment.

Setup

1. Create a new folder dall-e-quickstart and go to the quickstart folder with the following command:

   mkdir dall-e-quickstart && cd dall-e-quickstart
   

2. For the recommended keyless authentication with Microsoft Entra ID, sign in to Azure with the following command:

   az login
   

Retrieve resource information

You need to retrieve the following information to authenticate your application with your Azure OpenAI resource:

Run the quickstart

The sample code in this quickstart uses Microsoft Entra ID for the recommended keyless authentication. If you prefer to use an API key, you can replace the NewDefaultAzureCredential implementation with NewKeyCredential.

azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
credential, err := azidentity.NewDefaultAzureCredential(nil)
client, err := azopenai.NewClient(azureOpenAIEndpoint, credential, nil)

azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
azureOpenAIKey := os.Getenv("AZURE_OPENAI_API_KEY")
credential := azcore.NewKeyCredential(azureOpenAIKey)
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, credential, nil)