Add support for text-to-image (#6648)

* Add ITextToImageClient

* Remove URI based edit since it's not available

* Add filename for edit

* Add OpenAI implmentation of ITextToImageClient

* Fix tests

* Add tests for TextToImage

* Add DeletgatingTextToImageClient and tests

* Add integration test and fix some bugs

* Add remaining support to MEAI for TextToImage

* Make all TextToImageOptions optional

These are all nullable now so that the client can use defaults where
appropriate.

Remove quality default since it's not consistent across models.

Also remove setting ResponseFormat since this is not supported by
gpt-image-1.

* Address feedback

* Document some exceptions

* Address feedback

* Make EditImageAsync plural

OpenAI's image API supports multiple images and this does seem to be
common functionality and a better generalization.  The client library
doesn't expose this yet, but we should account for it.

Image models may be capable of things like
"Combine the subjects of these images into a single image" or
"Create a single image that uses the subject from the first image and
background for the second" etc.

* Address feedback and add/fix tests.

* Fix bad merge

* Address feedback

* Fix test

* Use DataContent.Name for filename.

* Add extensions for EditImageAsync

Extension that accepts a single DataContent and one that accepts a byte[].

I've left out streams and file paths, since these require more opinions
about how to load them.  I filed #6683 to address streams.

* Fix test

* Remove use of `_model` field.

* Rename ImageToText to Image

* Rename TextToImage directories to Image

* Rename files TextToImage -> Image

* Add new request and response type

* Make GenerateImagesAsync accept ImageRequest

* Remove EditImageAsync

* Adding GenerateStreamingImagesAsync

* Update docs

* Rename ImageClient ImageGenerator

* Fix up some text-to-image references

* Rename Image(Options|Request|Response)

* Remove `Images` from `GenerateImagesAsync`

* Remove streaming method

We don't yet have any good public support for streaming to vet this API

We can guess at how it might behave for OpenAI, but that doesn't
really give enough confidence to build the API around it.

* Address feedback

* Provide OpenAI an appropriate filename

* Remove Style from ImageGenerationOptions

Author: ericstj

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/DelegatingImageGenerator.cs

@@ -0,0 +1,69 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Provides an optional base class for an <see cref="IImageGenerator"/> that passes through calls to another instance.
+/// </summary>
+/// <remarks>
+/// This is recommended as a base type when building generators that can be chained in any order around an underlying <see cref="IImageGenerator"/>.
+/// The default implementation simply passes each call to the inner generator instance.
+/// </remarks>
+[Experimental("MEAI001")]
+public class DelegatingImageGenerator : IImageGenerator
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DelegatingImageGenerator"/> class.
+    /// </summary>
+    /// <param name="innerGenerator">The wrapped generator instance.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="innerGenerator"/> is <see langword="null"/>.</exception>
+    protected DelegatingImageGenerator(IImageGenerator innerGenerator)
+    {
+        InnerGenerator = Throw.IfNull(innerGenerator);
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        Dispose(disposing: true);
+        GC.SuppressFinalize(this);
+    }
+
+    /// <summary>Gets the inner <see cref="IImageGenerator" />.</summary>
+    protected IImageGenerator InnerGenerator { get; }
+
+    /// <inheritdoc />
+    public virtual Task<ImageGenerationResponse> GenerateAsync(
+        ImageGenerationRequest request, ImageGenerationOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        return InnerGenerator.GenerateAsync(request, options, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public virtual object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        _ = Throw.IfNull(serviceType);
+
+        // If the key is non-null, we don't know what it means so pass through to the inner service.
+        return
+            serviceKey is null && serviceType.IsInstanceOfType(this) ? this :
+            InnerGenerator.GetService(serviceType, serviceKey);
+    }
+
+    /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
+    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
+    protected virtual void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            InnerGenerator.Dispose();
+        }
+    }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/IImageGenerator.cs

@@ -0,0 +1,37 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a generator of images.
+/// </summary>
+[Experimental("MEAI001")]
+public interface IImageGenerator : IDisposable
+{
+    /// <summary>
+    /// Sends an image generation request and returns the generated image as a <see cref="ImageGenerationResponse"/>.
+    /// </summary>
+    /// <param name="request">The image generation request containing the prompt and optional original images for editing.</param>
+    /// <param name="options">The image generation options to configure the request.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="request"/> is <see langword="null"/>.</exception>
+    /// <returns>The images generated by the <see cref="ImageGenerationRequest"/>.</returns>
+    Task<ImageGenerationResponse> GenerateAsync(ImageGenerationRequest request, ImageGenerationOptions? options = null, CancellationToken cancellationToken = default);
+
+    /// <summary>Asks the <see cref="IImageGenerator"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
+    /// <param name="serviceType">The type of object being requested.</param>
+    /// <param name="serviceKey">An optional key that can be used to help identify the target service.</param>
+    /// <returns>The found object, otherwise <see langword="null"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="serviceType"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// The purpose of this method is to allow for the retrieval of strongly typed services that might be provided by the <see cref="IImageGenerator"/>,
+    /// including itself or any services it might be wrapping.
+    /// </remarks>
+    object? GetService(Type serviceType, object? serviceKey = null);
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGenerationOptions.cs

@@ -0,0 +1,103 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Drawing;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Represents the options for an image generation request.</summary>
+[Experimental("MEAI001")]
+public class ImageGenerationOptions
+{
+    /// <summary>
+    /// Gets or sets the number of images to generate.
+    /// </summary>
+    public int? Count { get; set; }
+
+    /// <summary>
+    /// Gets or sets the size of the generated image.
+    /// </summary>
+    /// <remarks>
+    /// If a provider only supports fixed sizes the closest supported size will be used.
+    /// </remarks>
+    public Size? ImageSize { get; set; }
+
+    /// <summary>
+    /// Gets or sets the media type (also known as MIME type) of the generated image.
+    /// </summary>
+    public string? MediaType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the model ID to use for image generation.
+    /// </summary>
+    public string? ModelId { get; set; }
+
+    /// <summary>
+    /// Gets or sets a callback responsible for creating the raw representation of the image generation options from an underlying implementation.
+    /// </summary>
+    /// <remarks>
+    /// The underlying <see cref="IImageGenerator" /> implementation may have its own representation of options.
+    /// When <see cref="IImageGenerator.GenerateAsync" /> is invoked with an <see cref="ImageGenerationOptions" />,
+    /// that implementation may convert the provided options into its own representation in order to use it while performing
+    /// the operation. For situations where a consumer knows  which concrete <see cref="IImageGenerator" /> is being used
+    /// and how it represents options, a new instance of that implementation-specific options type may be returned by this
+    /// callback, for the <see cref="IImageGenerator" />implementation to use instead of creating a new instance.
+    /// Such implementations may mutate the supplied options instance further based on other settings supplied on this
+    /// <see cref="ImageGenerationOptions" /> instance or from other inputs, therefore, it is <b>strongly recommended</b> to not
+    /// return shared instances and instead make the callback return a new instance on each call.
+    /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed
+    /// properties on <see cref="ImageGenerationOptions" />.
+    /// </remarks>
+    [JsonIgnore]
+    public Func<IImageGenerator, object?>? RawRepresentationFactory { get; set; }
+
+    /// <summary>
+    /// Gets or sets the response format of the generated image.
+    /// </summary>
+    public ImageGenerationResponseFormat? ResponseFormat { get; set; }
+
+    /// <summary>Produces a clone of the current <see cref="ImageGenerationOptions"/> instance.</summary>
+    /// <returns>A clone of the current <see cref="ImageGenerationOptions"/> instance.</returns>
+    public virtual ImageGenerationOptions Clone()
+    {
+        ImageGenerationOptions options = new()
+        {
+            Count = Count,
+            MediaType = MediaType,
+            ImageSize = ImageSize,
+            ModelId = ModelId,
+            RawRepresentationFactory = RawRepresentationFactory,
+            ResponseFormat = ResponseFormat
+        };
+
+        return options;
+    }
+}
+
+/// <summary>
+/// Represents the requested response format of the generated image.
+/// </summary>
+/// <remarks>
+/// Not all implementations support all response formats and this value may be ignored by the implementation if not supported.
+/// </remarks>
+[Experimental("MEAI001")]
+public enum ImageGenerationResponseFormat
+{
+    /// <summary>
+    /// The generated image is returned as a URI pointing to the image resource.
+    /// </summary>
+    Uri,
+
+    /// <summary>
+    /// The generated image is returned as in-memory image data.
+    /// </summary>
+    Data,
+
+    /// <summary>
+    /// The generated image is returned as a hosted resource identifier, which can be used to retrieve the image later.
+    /// </summary>
+    Hosted,
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGenerationRequest.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Represents a request for image generation.</summary>
+[Experimental("MEAI001")]
+public class ImageGenerationRequest
+{
+    /// <summary>Initializes a new instance of the <see cref="ImageGenerationRequest"/> class.</summary>
+    public ImageGenerationRequest()
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="ImageGenerationRequest"/> class.</summary>
+    /// <param name="prompt">The prompt to guide the image generation.</param>
+    public ImageGenerationRequest(string prompt)
+    {
+        Prompt = prompt;
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="ImageGenerationRequest"/> class.</summary>
+    /// <param name="prompt">The prompt to guide the image generation.</param>
+    /// <param name="originalImages">The original images to base edits on.</param>
+    public ImageGenerationRequest(string prompt, IEnumerable<AIContent>? originalImages)
+    {
+        Prompt = prompt;
+        OriginalImages = originalImages;
+    }
+
+    /// <summary>Gets or sets the prompt to guide the image generation.</summary>
+    public string? Prompt { get; set; }
+
+    /// <summary>
+    /// Gets or sets the original images to base edits on.
+    /// </summary>
+    /// <remarks>
+    /// If this property is set, the request will behave as an image edit operation.
+    /// If this property is null or empty, the request will behave as a new image generation operation.
+    /// </remarks>
+    public IEnumerable<AIContent>? OriginalImages { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGenerationResponse.cs

@@ -0,0 +1,52 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+#pragma warning disable EA0011 // Consider removing unnecessary conditional access operators
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Represents the result of an image generation request.</summary>
+[Experimental("MEAI001")]
+public class ImageGenerationResponse
+{
+    /// <summary>The content items in the generated text response.</summary>
+    private IList<AIContent>? _contents;
+
+    /// <summary>Initializes a new instance of the <see cref="ImageGenerationResponse"/> class.</summary>
+    [JsonConstructor]
+    public ImageGenerationResponse()
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="ImageGenerationResponse"/> class.</summary>
+    /// <param name="contents">The contents for this response.</param>
+    public ImageGenerationResponse(IList<AIContent>? contents)
+    {
+        _contents = contents;
+    }
+
+    /// <summary>Gets or sets the raw representation of the image generation response from an underlying implementation.</summary>
+    /// <remarks>
+    /// If a <see cref="ImageGenerationResponse"/> is created to represent some underlying object from another object
+    /// model, this property can be used to store that original object. This can be useful for debugging or
+    /// for enabling a consumer to access the underlying object model if needed.
+    /// </remarks>
+    [JsonIgnore]
+    public object? RawRepresentation { get; set; }
+
+    /// <summary>
+    /// Gets or sets the generated content items.  Content will typically be DataContent for
+    /// images streamed from the generator or UriContent for remotely hosted images, but may also
+    /// be provider specific content types that represent the generated images.
+    /// </summary>
+    [AllowNull]
+    public IList<AIContent> Contents
+    {
+        get => _contents ??= [];
+        set => _contents = value;
+    }
+}