{"id":16683480,"url":"https://github.com/marcominerva/dallenet","last_synced_at":"2025-04-09T23:24:40.121Z","repository":{"id":173058535,"uuid":"650045322","full_name":"marcominerva/DallENet","owner":"marcominerva","description":"A DALL·E integration library for .NET","archived":false,"fork":false,"pushed_at":"2024-11-05T10:23:00.000Z","size":125,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T01:13:32.499Z","etag":null,"topics":["azure","azure-openai","azure-openai-api","csharp","dall-e","dotnet","hacktoberfest","net","openai","openai-api"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcominerva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-06T08:07:48.000Z","updated_at":"2024-11-05T10:22:32.000Z","dependencies_parsed_at":"2023-12-07T09:26:49.293Z","dependency_job_id":"f25ee8a2-e816-4e44-83ab-f44aa8032e2d","html_url":"https://github.com/marcominerva/DallENet","commit_stats":null,"previous_names":["marcominerva/dallenet"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcominerva%2FDallENet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcominerva%2FDallENet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcominerva%2FDallENet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcominerva%2FDallENet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcominerva","download_url":"https://codeload.github.com/marcominerva/DallENet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247981174,"owners_count":21027877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure","azure-openai","azure-openai-api","csharp","dall-e","dotnet","hacktoberfest","net","openai","openai-api"],"created_at":"2024-10-12T14:24:54.402Z","updated_at":"2025-04-09T23:24:40.087Z","avatar_url":"https://github.com/marcominerva.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DallENet\n\n[![Lint Code Base](https://github.com/marcominerva/DallENet/actions/workflows/linter.yml/badge.svg)](https://github.com/marcominerva/DallENet/actions/workflows/linter.yml)\n[![CodeQL](https://github.com/marcominerva/DallENet/actions/workflows/codeql.yml/badge.svg)](https://github.com/marcominerva/DallENet/actions/workflows/codeql.yml)\n[![NuGet](https://img.shields.io/nuget/v/DallENet.svg?style=flat-square)](https://www.nuget.org/packages/DallENet)\n[![Nuget](https://img.shields.io/nuget/dt/DallENet)](https://www.nuget.org/packages/DallENet)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/marcominerva/DallENet/blob/master/LICENSE)\n\nA DALL·E integration library for .NET\n\n\u003e **Note**\nThe current version of the library requires a DALL·E 3 resource. If you want to use DALL·E 2, plese refer to [this version](https://github.com/marcominerva/DallENet/tree/v1.0.13).\n\n## Installation\n\nThe library is available on [NuGet](https://www.nuget.org/packages/DallENet). Just search for *DallENet* in the **Package Manager GUI** or run the following command in the **.NET CLI**:\n\n```shell\ndotnet add package DallENet\n```\n\n## Configuration\n\nRegister DALL·E service at application startup:\n\n```csharp\nbuilder.Services.AddDallE(options =\u003e\n{\n    // Azure OpenAI Service.\n    options.UseAzure(resourceName: \"\", apiKey: \"\", authenticationType: AzureAuthenticationType.ApiKey);\n\n    options.DefaultSize = DallEImageSizes._1792x1024;              // Default: 1024x1024\n    options.DefaultQuality = DallEImageQualities.HD;               // Default: Standard\n    options.DefaultStyle = DallEImageStyles.Natural;               // Default: Vivid\n    options.DefaultResponseFormat = DallEImageResponseFormats.Url; // Default: Url\n});\n```\n\nCurrently, **DallENet** supports Azure OpenAI Service only. Support for OpenAI will be added in a future version. The required configuration parameters are the following:\n\n- _ResourceName_: the name of your Azure OpenAI Resource (required).\n- _ApiKey_: Azure OpenAI provides two methods for authentication. You can use either API Keys or Azure Active Directory (required).\n- _ApiVersion_: the version of the API to use (optional). Allowed values:\n  - 2023-12-01-preview (default)\n- _AuthenticationType_: it specifies if the key is an actual API Key or an [Azure Active Directory token](https://learn.microsoft.com/azure/cognitive-services/openai/how-to/managed-identity) (optional, default: \"ApiKey\").\n\n#### Default Image Size\n\nDALL·E 3 is able to generate images at different resolutions:\n\n- 1024x1024\n- 1792x1024\n- 1024x1792\n\nUsing the *DefaultSize* property, it is possible to specify the default image size, unless you pass an explicit value in the **GenerateImageAsync** or **GetImageStreamAsync** methods. The default resolution is 1024x1024.\n\n#### Default Quality\n\nDALL·E 3 is able to generate images in standard or HD quality, that is, with finer details and greater consistency across the image. Using the *DefaultQuality* property, it is possible to specify the default quality, unless you pass an explicit value in the **GenerateImageAsync** or **GetImageStreamAsync** methods. The default quality is _Standard_.\n\n#### Default Style\n\nDALL·E 3 is able to generate images usinga vivid of natural style:\n\n- Vivid generates hyper-real and dramatic images.\n- Natural produces more natural, less hyper-real looking images.\n\nUsing the *DefaultStyle* property, it is possible to specify the default style, unless you pass an explicit value in the **GenerateImageAsync** or **GetImageStreamAsync** methods. The default style is _Vivid_.\n\n#### Default Response format\n\nDALL·E 3 is able to return the URL of the generated image of its Base64 encoding. Using the *DefaultResponseFormat* property, it is possible to specify the default quality, unless you pass an explicit value in the **GenerateImageAsync** or **GetImageStreamAsync** methods. The default quality is _Url_.\n\n### Configuration using an external source\n\nThe configuration can be automatically read from [IConfiguration](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.configuration.iconfiguration), using for example a _DallE_ section in the _appsettings.json_ file:\n\n```csharp\n\"DallE\": {\n    \"Provider\": \"Azure\",                // Optional. Currently only Azure is supported\n    \"ApiKey\": \"\",                       // Required\n    \"ResourceName\": \"\",                 // Required \n    \"ApiVersion\": \"2023-12-01-preview\", // Optional, used only by Azure OpenAI Service. Allowed values: 2023-12-01-preview (default)\n    \"AuthenticationType\": \"ApiKey\",     // Optional, Allowed values: ApiKey (default) or ActiveDirectory\n\n    \"DefaultModel\": \"dall-e-3\",         // Required\n    \"DefaultSize\": \"1792x1024\",         // Optional, Allowed values: 1024x1024 (default), 1792x1024 or 1024x1792\n    \"DefaultQuality\": \"standard\",       // Optional, Allowed values: standard (default) or hd\n    \"DefaultResponseFormat\": \"url\",     // Optional, Allowed values: url (default) or b64_json\n    \"DefaultStyle\": \"vivid\",            // Optional, Allowed values: natural (default), or vivid\n    \"ThrowExceptionOnError\": true\n    //\"User\": \"UserName\"                // Optional\n}\n```\n\nAnd then use the corresponding overload of che **AddDallE** method:\n\n```csharp\n// Adds DALL·E service using settings from IConfiguration.\nbuilder.Services.AddDallE(builder.Configuration);\n```\n\n### Configuring DallENet dinamically\n\nThe **AddDallE** method has also an overload that accepts an [IServiceProvider](https://learn.microsoft.com/dotnet/api/system.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:\n\n```csharp\nbuilder.Services.AddDallE((services, options) =\u003e\n{\n    var accountService = services.GetRequiredService\u003cIAccountService\u003e();\n\n    // Dynamically gets the Resource name and the API Key from the service.\n    var resourceName = \"...\";\n    var apiKey = \"...\"\n\n    options.UseAzure(resourceName, apiKey);\n});\n```\n\n### Configuring DallENet using both IConfiguration and code\n\nIn more complex scenarios, it is possible to configure **DallENet** using both code and [IConfiguration](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.configuration.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:\n\n```csharp\nbuilder.Services.AddDallE((services, options) =\u003e\n{\n    // Configure common properties (default size, default style, ecc.) using IConfiguration.\n    options.UseConfiguration(builder.Configuration);\n\n    var accountService = services.GetRequiredService\u003cIAccountService\u003e();\n\n    // Dynamically gets the Resource name and the API Key from the service.\n    var resourceName = \"...\";\n    var apiKey = \"...\"\n\n    options.UseAzure(resourceName, apiKey);\n});\n```\n\n## Usage\n\nThe 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:\n\n```csharp\napp.MapPost(\"/api/image\", async (Request request, IDallEClient dallEClient) =\u003e\n{\n    var response = await dallEClient.GenerateImagesAsync(request.Prompt);\n    return TypedResults.Ok(response);\n})\n.WithOpenApi();\n\npublic record class Request(string Prompt);\n```\n\nIn particular, the response contains the URL of the generated image. If we just want to retrieve the URL of the first generated image, we can call the **GetImageUrl** method:\n\n```csharp\nvar imageUrl = response.GetImageUrl();\n```\n\n\u003e **Note**\nGenerated images are automatically deleted after 24 hours.\n\nCheck the [Samples folder](https://github.com/marcominerva/DallENet/tree/master/samples) for more information about the different implementations.\n\n## Documentation\n\nThe full technical documentation is available [here](https://github.com/marcominerva/DallENet/tree/master/docs).\n\n## Contribute\n\nThe 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. \n\n\u003e **Warning**\nRemember to work on the **develop** branch, don't use the **master** branch directly. Create Pull Requests targeting **develop**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcominerva%2Fdallenet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcominerva%2Fdallenet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcominerva%2Fdallenet/lists"}