DallENet 1.0.13

DallENet

A DALL·E integration library for .NET

Installation

The library is available on NuGet. Just search for DallENet in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package DallENet

Configuration

Register DALL·E service at application startup:

builder.Services.AddDallE(options =>
{
    // Azure OpenAI Service.
    //options.UseAzure(resourceName: "", apiKey: "", authenticationType: AzureAuthenticationType.ApiKey);

    options.DefaultResolution = DallEImageResolutions.Medium;     // Default: Large (1024x1024)
    options.DefaultImageCount = 2;  // Default: 1
});

Currently, DallENet supports Azure OpenAI Service only. Support for OpenAI will be added in a future version. The required configuration parameters are the following:

• ResourceName: the name of your Azure OpenAI Resource (required).
• ApiKey: Azure OpenAI provides two methods for authentication. You can use either API Keys or Azure Active Directory (required).
• ApiVersion: the version of the API to use (optional). Allowed values:
  • 2023-06-01-preview (default)
• AuthenticationType: it specifies if the key is an actual API Key or an Azure Active Directory token (optional, default: "ApiKey").

Default Image Resolution

DALL·E is able to generate images at different resolutions:

• Small (256x256)
• Medium (512x512)
• Large (1024x1024)

Using the DefaultResolution property, it is possible to specify the default image resolution, unless you pass an explicit value in the GenerateImageAsync method. The default resolution is Large (1024x1024).

Default Image Count

DALL·E is able to generate up to 5 images for a single request. Using the DefaultImage property, it is possible to specify the default number of images to generate, unless you pass an explicit value in the GenerateImageAsync method. The default image count is 1.

Configuration using an external source

The configuration can be automatically read from IConfiguration, using for example a DallE section in the appsettings.json file:

"DallE": {
    "Provider": "Azure",                // Optional. Currently only Azure is supported
    "ApiKey": "",                       // Required
    "ResourceName": "",                 // Required 
    "ApiVersion": "2023-06-01-preview", // Optional, used only by Azure OpenAI Service. Allowed values: 2023-06-01-preview (default)
    "AuthenticationType": "ApiKey",     // Optional, Allowed values: ApiKey (default) or ActiveDirectory

    "DefaultResolution": "1024x1024",   // Optional, Allowed values: 256x256, 512x512, 1024x1024 (default)
    "DefaultImageCount": 1,             // Optional, Allowed values: 1 (default) to 5
    "ThrowExceptionOnError": true
}

And then use the corresponding overload of che AddDallE method:

// Adds DALL·E service using settings from IConfiguration.
builder.Services.AddDallE(builder.Configuration);

Configuring DallENet dinamically

The AddDallE method has also an overload that accepts an IServiceProvider as argument. It can be used, for example, if we're in a Web API and we need to support scenarios in which every user has a different API Key that can be retrieved accessing a database via Dependency Injection:

builder.Services.AddDallE((services, options) =>
{
    var accountService = services.GetRequiredService<IAccountService>();

    // Dynamically gets the Resource name and the API Key from the service.
    var resourceName = "...";
    var apiKey = "..."

    options.UseAzure(resourceName, apiKey);
});

Configuring DallENet using both IConfiguration and code

In more complex scenarios, it is possible to configure DallENet using both code and IConfiguration. This can be useful if we want to set a bunch of common properties, but at the same time we need some configuration logic. For example:

builder.Services.AddDallE((services, options) =>
{
    // Configure common properties (default resolution, default image count, ecc.) using IConfiguration.
    options.UseConfiguration(builder.Configuration);

    var accountService = services.GetRequiredService<IAccountService>();

    // Dynamically gets the Resource name and the API Key from the service.
    var resourceName = "...";
    var apiKey = "..."

    options.UseAzure(resourceName, apiKey);
});

Usage

The library can be used in any .NET application built with .NET 6.0 or later. For example, we can create a Minimal API in this way:

app.MapPost("/api/image", async (Request request, IDallEClient dallEClient) =>
{
    var response = await dallEClient.GenerateImagesAsync(request.Prompt);
    return TypedResults.Ok(response);
})
.WithOpenApi();

public record class Request(string Prompt);

In particular, the response contains the URL (or the list of URLs) of generated images. If we just want to retrieve the URL of the first generated image, we can call the GetImageUrl method:

var imageUrl = response.GetImageUrl();

Note Generated images are automatically deleted after 24 hours.

Check the Samples folder for more information about the different implementations.

Deleting generated images

Generated images are automatically deleted after 24 hours. If necessary, it is possible to explicitly trigger the deletion earlier using the DeleteImagesAsync method:

await dallECliente.DeleteImagesAsync(response.Id);

The operationId argument is a GUID that identifies the original image generation request and is returned when calling the GenerateImagesAsync method.

Note This method deletes all the images that have been generated in the request associated with the given OperationId.

Documentation

The full technical documentation is available here.

Contribute

The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repo and we'll address them as we can.

Warning Remember to work on the develop branch, don't use the master branch directly. Create Pull Requests targeting develop.