dotnet · jeffhandley · Aug 12, 2025 · Aug 12, 2025
@@ -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();
+        }
+    }
+}
@@ -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);
+}
@@ -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,
+}
@@ -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; }
+}
@@ -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;
+    }
+}