Add tutorial for text-to-image generation using Microsoft.Extensions.AI

docs/ai/index.yml

@@ -35,8 +35,8 @@ landingContent:
             url: quickstarts/prompt-model.md
           - text: Build an Azure AI chat app
             url: quickstarts/build-chat-app.md
-          - text: Generate images using Azure AI
-            url: quickstarts/generate-images.md
+          - text: Generate images from text
+            url: quickstarts/text-to-image.md
 
   # Card
   - title: Essential concepts

docs/ai/overview.md

@@ -36,10 +36,10 @@ We recommend the following sequence of tutorials and articles for an introductio
 | Scenario                    | Tutorial                                                                |
 |-----------------------------|-------------------------------------------------------------------------|
 | Create a chat application   | [Build an Azure AI chat app with .NET](./quickstarts/build-chat-app.md) |
-| Summarize text              | [Summarize text using Azure AI chat app with .NET](./quickstarts/prompt-model.md) |
-| Chat with your data         | [Get insight about your data from an .NET Azure AI chat app](./quickstarts/build-vector-search-app.md) |
+| Summarize text              | [Summarize text using Azure AI chat app](./quickstarts/prompt-model.md) |
+| Chat with your data         | [Get insight about your data from a .NET Azure AI chat app](./quickstarts/build-vector-search-app.md) |
 | Call .NET functions with AI | [Extend Azure AI using tools and execute a local function with .NET](./quickstarts/use-function-calling.md) |
-| Generate images             | [Generate images using Azure AI with .NET](./quickstarts/generate-images.md) |
+| Generate images             | [Generate images from text](./quickstarts/text-to-image.md) |
 | Train your own model        | [ML.NET tutorial](https://dotnet.microsoft.com/learn/ml-dotnet/get-started-tutorial/intro) |
 
 Browse the table of contents to learn more about the core concepts, starting with [How generative AI and LLMs work](./conceptual/how-genai-and-llms-work.md).

docs/ai/quickstarts/build-chat-app.md

@@ -145,4 +145,4 @@ If you no longer need them, delete the Azure OpenAI resource and GPT-4 model dep
 ## Next steps
 
 - [Quickstart - Chat with a local AI model](chat-local-model.md)
-- [Generate images using AI with .NET](generate-images.md)
+- [Generate images from text using AI](text-to-image.md)

docs/ai/quickstarts/build-vector-search-app.md

@@ -199,4 +199,4 @@ If you no longer need them, delete the Azure OpenAI resource and model deploymen
 ## Next steps
 
 - [Quickstart - Chat with a local AI model](chat-local-model.md)
-- [Generate images using AI with .NET](generate-images.md)
+- [Generate images from text using AI](text-to-image.md)

docs/ai/quickstarts/generate-images.md

@@ -1,15 +1,14 @@
 ---
-title: Quickstart - Generate images using AI with .NET
-description: Create a simple app using to generate images using .NET and the OpenAI or Azure OpenAI models.
+title: Quickstart - Generate images using OpenAI.Images.ImageClient
+description: Create a simple app using to generate images using OpenAI.Images.ImageClient in .NET.
 ms.date: 04/09/2025
 ms.topic: quickstart
 zone_pivot_groups: openai-library
-# CustomerIntent: As a .NET developer new to OpenAI, I want deploy and use sample code to interact to learn from the sample code to generate images.
 ---
 
-# Generate images using AI with .NET
+# Generate images using OpenAI.Images.ImageClient
 
-In this quickstart, you learn how to create a .NET console app to generate images using an OpenAI or Azure OpenAI DALLe AI model, which are specifically designed to generate images based on text prompts.
+In this quickstart, you create a .NET console app that uses `OpenAI.Images.ImageClient` to generate images using an OpenAI or Azure OpenAI DALL-E AI model. These models generate images from text prompts.
 
 :::zone target="docs" pivot="openai"
 
@@ -101,7 +100,7 @@ Complete the following steps to create a .NET console app to connect to an AI mo
     :::code language="csharp" source="snippets/image-generation/azure-openai/program.cs" :::
 
     > [!NOTE]
-    > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. If you aren't using the `azd` template to provision the Azure OpenAI resource, you'll need to assign the `Azure AI Developer` role to the account you used to sign-in to Visual Studio or the Azure CLI. For more information, see [Authenticate to Azure AI services with .NET](../azure-ai-services-authentication.md).
+    > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. If you aren't using the `azd` template to provision the Azure OpenAI resource, you'll need to assign the `Azure AI Developer` role to the account you used to sign in to Visual Studio or the Azure CLI. For more information, see [Authenticate to Azure AI services with .NET](../azure-ai-services-authentication.md).
 
     :::zone-end
 

docs/ai/quickstarts/snippets/text-to-image/azure-openai/Program.cs

@@ -0,0 +1,46 @@
+// <SnippetConfigClient>
+using Azure;
+using Azure.AI.OpenAI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+
+IConfigurationRoot config = new ConfigurationBuilder()
+    .AddUserSecrets<Program>()
+    .Build();
+
+string endpoint = config["AZURE_OPENAI_ENDPOINT"];
+string apiKey = config["AZURE_OPENAI_API_KEY"];
+string model = config["AZURE_OPENAI_GPT_NAME"];
+
+// Create the Azure OpenAI client and convert to IImageGenerator.
+AzureOpenAIClient azureClient = new(
+    new Uri(endpoint),
+    new AzureKeyCredential(apiKey));
+
+var imageClient = azureClient.GetImageClient(model);
+#pragma warning disable MEAI001 // Type is for evaluation purposes only.
+IImageGenerator generator = imageClient.AsIImageGenerator();
+// </SnippetConfigClient>
+
+// <SnippetGenerateImage>
+// Generate an image from a text prompt
+var options = new ImageGenerationOptions
+{
+    MediaType = "image/png"
+};
+string prompt = "A tennis court in a jungle";
+var response = await generator.GenerateImagesAsync(prompt, options);
+
+// Save the image to a file.
+var dataContent = response.Contents.OfType<DataContent>().First();
+string fileName = SaveImage(dataContent, "jungle-tennis.png");
+Console.WriteLine($"Image saved to file: {fileName}");
+
+static string SaveImage(DataContent content, string fileName)
+{
+    string userDirectory = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+    var path = Path.Combine(userDirectory, fileName);
+    File.WriteAllBytes(path, content.Data.ToArray());
+    return Path.GetFullPath(path);
+}
+// </SnippetGenerateImage>

docs/ai/quickstarts/snippets/text-to-image/azure-openai/TextToImageAzureOpenAI.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.1-preview.1.25521.4" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.10" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.10" />
+  </ItemGroup>
+
+</Project>

docs/ai/quickstarts/text-to-image.md

@@ -0,0 +1,132 @@
+---
+title: Quickstart - Generate images from text using AI
+description: Learn how to use Microsoft.Extensions.AI to generate images from text prompts using AI models in a .NET application.
+ms.date: 10/21/2025
+ms.topic: quickstart
+ai-usage: ai-assisted
+---
+
+# Generate images from text using AI
+
+In this quickstart, you use the <xref:Microsoft.Extensions.AI> (MEAI) library to generate images from text prompts using an AI model. The MEAI text-to-image capabilities let you generate images from natural language prompts or existing images using a consistent and extensible API surface.
+
+The <xref:Microsoft.Extensions.AI.IImageGenerator> interface provides a unified, extensible API for working with various image generation services, making it easy to integrate text-to-image capabilities into your .NET apps. The interface supports:
+
+- Text-to-image generation.
+- Pipeline composition with middleware (logging, telemetry, caching).
+- Flexible configuration options.
+- Support for multiple AI providers.
+
+> [!NOTE]
+> The `IImageGenerator` interface is currently marked as experimental with the `MEAI001` diagnostic ID. You might need to suppress this warning in your project file or code.
+
+<!--Prereqs-->
+[!INCLUDE [azure-openai-prereqs](../quickstarts/includes/prerequisites-azure-openai.md)]
+
+## Configure the AI service
+
+To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article. In the "Deploy a model" step, select the `gpt-image-1` model.
+
+> [!NOTE]
+> `gpt-image-1` is a newer model that offers several improvements over DALL-E 3. It's available from OpenAI on a limited basis; apply for access with [this form](https://aka.ms/oai/gptimage1access).
+
+## Create the application
+
+Complete the following steps to create a .NET console application that generates images from text prompts.
+
+1. Create a new console application:
+
+    ```dotnetcli
+    dotnet new console -o TextToImageAI
+    ```
+
+1. Navigate to the `TextToImageAI` directory, and add the necessary packages to your app:
+
+    ```dotnetcli
+    dotnet add package Azure.AI.OpenAI
+    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
+    dotnet add package Microsoft.Extensions.Configuration
+    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
+    ```
+
+1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint, model name, and API key:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
+    dotnet user-secrets set AZURE_OPENAI_GPT_NAME gpt-image-1
+    dotnet user-secrets set AZURE_OPENAI_API_KEY <your-azure-openai-api-key>
+    ```
+
+1. Open the new app in your editor of choice (for example, Visual Studio).
+
+## Implement basic image generation
+
+1. Update the `Program.cs` file with the following code to get the configuration data and create the <xref:Azure.AI.OpenAI.AzureOpenAIClient>:
+
+   :::code language="csharp" source="snippets/text-to-image/azure-openai/Program.cs" id="ConfigClient":::
+
+   The preceding code:
+
+   - Loads configuration from user secrets.
+   - Creates an `ImageClient` from the OpenAI SDK.
+   - Converts the `ImageClient` to an `IImageGenerator` using the <xref:Microsoft.Extensions.AI.OpenAIClientExtensions.AsIImageGenerator(OpenAI.Images.ImageClient)> extension method.
+
+1. Add the following code to implement basic text-to-image generation:
+
+   :::code language="csharp" source="snippets/text-to-image/azure-openai/Program.cs" id="GenerateImage":::
+
+   The preceding code:
+
+   - Sets the requested image file type by setting <xref:Microsoft.Extensions.AI.ImageGenerationOptions.MediaType?displayProperty=nameWithType>.
+   - Generates an image using the <xref:Microsoft.Extensions.AI.ImageGeneratorExtensions.GenerateImagesAsync(Microsoft.Extensions.AI.IImageGenerator,System.String,Microsoft.Extensions.AI.ImageGenerationOptions,System.Threading.CancellationToken)> method with a text prompt.
+   - Saves the generated image to a file in the local user directory.
+
+1. Run the application, either through the IDE or using `dotnet run`.
+
+   The application generates an image and outputs the file path to the image. Open the file to view the generated image. The following image shows one example of a generated image.
+
+   :::image type="content" source="media/text-to-image/jungle-tennis.png" alt-text="AI-generated image of a tennis court in a jungle.":::
+
+## Configure image generation options
+
+You can customize image generation by providing other options such as size, response format, and number of images to generate. The <xref:Microsoft.Extensions.AI.ImageGenerationOptions> class allows you to specify:
+
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.AdditionalProperties>: Provider-specific options.
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.Count>: The number of images to generate.
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ImageSize>: The dimensions of the generated image as a <xref:System.Drawing.Size?displayProperty=fullName>. For supported sizes, see the [OpenAI API reference](https://platform.openai.com/docs/api-reference/images/create).
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.MediaType>: The media type (MIME type) of the generated image.
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ModelId>: The model ID.
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.RawRepresentationFactory>: The callback that creates the raw representation of the image generation options from an underlying implementation.
+- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ResponseFormat>: Options are <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Uri>, <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Data>, and <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Hosted>.
+
+## Best practices
+
+When implementing text-to-image generation in your applications, consider these best practices:
+
+- **Prompt engineering**: Write clear, detailed prompts that describe the desired image. Include specific details about style, composition, colors, and elements.
+- **Cost management**: Image generation can be expensive. Cache results when possible and implement rate limiting to control costs.
+- **Content safety**: Always review generated images for appropriate content, especially in production applications. Consider implementing content filtering and moderation.
+- **User experience**: Image generation can take several seconds. Provide progress indicators and handle timeouts gracefully.
+- **Legal considerations**: Be aware of licensing and usage rights for generated images. Review the terms of service for your AI provider.
+
+## Clean up resources
+
+When you no longer need the Azure OpenAI resource, delete it to avoid incurring charges:
+
+1. In the [Azure Portal](https://portal.azure.com), navigate to your Azure OpenAI resource.
+1. Select the resource and then select **Delete**.
+
+## Next steps
+
+You've successfully generated some different images using the <xref:Microsoft.Extensions.AI.IImageGenerator> interface in <xref:Microsoft.Extensions.AI>. Next, you can explore some of the additional functionality, including:
+
+- Refining the generated image iteratively.
+- Editing an existing image.
+- Personalizing an image, diagram, or theme.
+
+## See also
+
+- [Explore text-to-image capabilities in .NET (blog post)](https://devblogs.microsoft.com/dotnet/explore-text-to-image-dotnet/)
+- [Microsoft.Extensions.AI library overview](../microsoft-extensions-ai.md)
+- [Quickstart: Build an AI chat app with .NET](../quickstarts/build-chat-app.md)

docs/ai/toc.yml

@@ -3,20 +3,21 @@ items:
   href: index.yml
 - name: Overview
   href: overview.md
-- name: "Quickstart: Connect to and prompt an AI model"
-  href: quickstarts/prompt-model.md
 - name: AI tools and SDKs
   items:
   - name: Overview
     href: dotnet-ai-ecosystem.md
   - name: Microsoft.Extensions.AI
-    href: microsoft-extensions-ai.md    
+    href: microsoft-extensions-ai.md
   - name: Microsoft Agent Framework
     href: /agent-framework/overview/agent-framework-overview?toc=/dotnet/ai/toc.json&bc=/dotnet/ai/toc.json
   - name: C# SDK for MCP
     href: get-started-mcp.md
 - name: Quickstarts
+  expanded: true
   items:
+  - name: Connect to and prompt an AI model
+    href: quickstarts/prompt-model.md
   - name: Build a chat app
     href: quickstarts/build-chat-app.md
   - name: Request structured output
@@ -25,18 +26,12 @@ items:
     href: quickstarts/build-vector-search-app.md
   - name: Execute a local .NET function
     href: quickstarts/use-function-calling.md
-  - name: Generate images
-    href: quickstarts/generate-images.md
   - name: Chat with a local AI model
     href: quickstarts/chat-local-model.md
   - name: Build a minimal AI assistant
     href: quickstarts/create-assistant.md
   - name: Get started using the AI app templates
     href: quickstarts/ai-templates.md
-  - name: Build a minimal MCP server and publish to NuGet
-    href: quickstarts/build-mcp-server.md
-  - name: Build a minimal MCP client
-    href: quickstarts/build-mcp-client.md
 - name: Concepts
   items:
   - name: How generative AI and LLMs work
@@ -67,6 +62,18 @@ items:
       href: tutorials/tutorial-ai-vector-search.md
     - name: Scale Azure OpenAI with Azure Container Apps
       href: get-started-app-chat-scaling-with-azure-container-apps.md
+- name: MCP client/server
+  items:
+    - name: Build a minimal MCP server and publish to NuGet
+      href: quickstarts/build-mcp-server.md
+    - name: Build a minimal MCP client
+      href: quickstarts/build-mcp-client.md
+- name: Text to image
+  items:
+    - name: Generate images using MEAI
+      href: quickstarts/text-to-image.md
+    - name: Generate images using OpenAI.Images.ImageClient
+      href: quickstarts/generate-images.md
 - name: Security and content safety
   items:
   - name: Authentication for Azure-hosted apps and services

docs/azure/index.yml

@@ -103,7 +103,7 @@ conceptualContent:
           text: Build a chat app
         - itemType: quickstart
           text: Generate images
-          url: ../ai/quickstarts/generate-images.md
+          url: ../ai/quickstarts/text-to-image.md
         - itemType: concept
           text: Understand prompt engineering
           url: ../ai/conceptual/prompt-engineering-dotnet.md