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

docs/ai/quickstarts/generate-images.md

@@ -1,13 +1,13 @@
 ---
-title: Quickstart - Generate images using AI with .NET
+title: Quickstart - Generate images using DALLe
 description: Create a simple app using to generate images using .NET and the OpenAI or Azure OpenAI models.
 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 DALLe
 
 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.
 

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

@@ -0,0 +1,83 @@
+// <SnippetConfigClient>
+using Azure;
+using Azure.AI.OpenAI;
+using Microsoft.Extensions.AI;
+
+using Microsoft.Extensions.Configuration;
+using System.Drawing;
+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 prompt = "A tennis court in a jungle";
+var response = await generator.GenerateImagesAsync(prompt);
+
+// Save the image to a file.
+var dataContent = response.Contents.OfType<DataContent>().First();
+string fileName = SaveImage(dataContent, "jungle-tennis");
+Console.WriteLine($"Image saved to file: {fileName}");
+
+static string SaveImage(DataContent content, string name)
+{
+    string userDirectory = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+    var extension = content.MediaType.Split(@"/")[1];
+    var path = Path.Combine(userDirectory, $"{name}.{extension}");
+    File.WriteAllBytes(path, content.Data.ToArray());
+    return Path.GetFullPath(path);
+}
+// </SnippetGenerateImage>
+
+// <SnippetWithOptions>
+var options = new ImageGenerationOptions
+{
+    ImageSize = new Size(1024, 1536),
+    Count = 2
+};
+
+var promptWithOptions = "A futuristic cityscape with flying cars and neon lights";
+response = await generator.GenerateImagesAsync(promptWithOptions, options);
+Console.WriteLine($"Successfully generated {response.Contents.Count} image(s)");
+// </SnippetWithOptions>
+
+// <SnippetWithErrorHandling>
+try
+{
+    response = await generator.GenerateImagesAsync(
+        "An abstract representation of technology and nature in harmony",
+        new ImageGenerationOptions { ImageSize = new Size(512, 512) });
+
+    if (response.Contents.Count == 0)
+    {
+        Console.WriteLine("No images were generated");
+    }
+    else
+    {
+        Console.WriteLine($"Generated an image with no errors.");
+    }
+}
+catch (System.ClientModel.ClientResultException ex)
+{
+    Console.WriteLine(ex.Message);
+
+    /* HTTP 400 (invalid_request_error: invalid_value)
+       Parameter: size
+       Invalid value: '512x512'.Supported values are: '1024x1024', '1024x1536', '1536x1024', and 'auto'.
+    */
+}
+// </SnippetWithErrorHandling>

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

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn);MEAI001</NoWarn>
+    <UserSecretsId>text-to-image-azure-openai</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
+    <PackageReference Include="Azure.Identity" Version="1.13.1" />
+    <PackageReference Include="Microsoft.Extensions.AI" Version="9.10.0" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.0-preview.1.25513.3" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.0" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,140 @@
+---
+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 learn how to use the <xref:Microsoft.Extensions.AI> (MEAI) library to generate images from text prompts using AI models. The MEAI text-to-image capabilities are designed to empower you to 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.
+
+## 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:
+
+   - 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 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>. Supported sizes are 1024 x 1024, 1024 x 1536, and 1536 x 1024.
+- <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>.
+
+Update your code to include configuration options:
+
+:::code language="csharp" source="snippets/text-to-image/azure-openai/Program.cs" id="WithOptions":::
+
+## Handle errors and edge cases
+
+It's important to handle potential errors such as content filtering, rate limiting, or invalid sizes when you generate images. Add error handling to your application:
+
+:::code language="csharp" source="snippets/text-to-image/azure-openai/Program.cs" id="WithErrorHandling":::
+
+## 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.
+- Merging multiple images into one, such as putting a character into a scene.
+
+## See also
+
+- [Quickstart: Generate images using AI with .NET](../quickstarts/generate-images.md)
+- [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 DALLe
+      href: quickstarts/generate-images.md
 - name: Security and content safety
   items:
   - name: Authentication for Azure-hosted apps and services