BlockadeLabs-SDK-DotNet 2.0.0

BlockadeLabs-SDK-DotNet

A simple C# .NET client library for BlockadeLabs to use through their RESTful API. An BlockadeLabs API account subscription is required.

Requirements

• This library targets .NET 8.0 and above.
• It should work across console apps, winforms, wpf, asp.net, etc.
• It should also work across Windows, Linux, and Mac.

Getting started

Install from NuGet

Install package BlockadeLabs-SDK-DotNet from Nuget. Here's how via command line:

Install-Package BlockadeLabs-SDK-DotNet

Documentation

Docs website: https://rageagainstthepixel.github.io/BlockadeLabs-SDK-DotNet

Table of Contents

• Authentication
• BlockadeLabs API Proxy
• Skyboxes
  • Get Skybox Styles
  • Get Skybox Style Families
  • Get Skybox Export Options
  • Generate Skybox
  • Get Skybox by Id
  • Request Skybox Export
  • Delete Skybox by Id
  • Get Skybox History
  • Cancel Skybox Generation
  • Cancel All Pending Skybox Generations

Authentication

There are 3 ways to provide your API keys, in order of precedence:

[!WARNING] We recommended using the environment variables to load the API key instead of having it hard coded in your source. It is not recommended use this method in production, but only for accepting user credentials, local testing and quick start scenarios.

1. Pass keys directly with constructor ⚠️
2. Load key from configuration file
3. Use System Environment Variables

Pass keys directly with constructor

[!WARNING] We recommended using the environment variables to load the API key instead of having it hard coded in your source. It is not recommended use this method in production, but only for accepting user credentials, local testing and quick start scenarios.

using var api = new BlockadeLabsClient("api-key");

Or create a BlockadeLabsAuthentication object manually

using var api = new BlockadeLabsClient(new BlockadeLabsAuthentication("api-key"));

Load key from configuration file

Attempts to load api keys from a configuration file, by default .blockadelabs in the current directory, optionally traversing up the directory tree or in the user's home directory.

To create a configuration file, create a new text file named .blockadelabs and containing the line:

Json format

{
    "apiKey": "your-api-key"
}

You can also load the configuration file directly with known path by calling static methods in BlockadeLabsAuthentication:

• Loads the default .blockadelabs config in the specified directory:

using var api = new BlockadeLabsClient(BlockadeLabsAuthentication.LoadFromDirectory("path/to/your/directory"));

• Loads the configuration file from a specific path. File does not need to be named .blockadelabs as long as it conforms to the json format:

using var api = new BlockadeLabsClient(BlockadeLabsAuthentication.LoadFromPath("path/to/your/file.json"));

Use System Environment Variables

Use your system's environment variables specify an api key and organization to use.

• Use BLOCKADELABS_API_KEY for your api key.

using var api = new BlockadeLabsClient(BlockadeLabsAuthentication.LoadFromEnvironment());

BlockadeLabs API Proxy

Using either the BlockadeLabs-SDK-DotNet or com.blockadelabs.sdk packages directly in your front-end app may expose your API keys and other sensitive information. To mitigate this risk, it is recommended to set up an intermediate API that makes requests to BlockadeLabs on behalf of your front-end app. This library can be utilized for both front-end and intermediary host configurations, ensuring secure communication with the BlockadeLabs API.

Front End Example

In the front end example, you will need to securely authenticate your users using your preferred OAuth provider. Once the user is authenticated, exchange your custom auth token with your API key on the backend.

Follow these steps:

1. Setup a new project using either the BlockadeLabs-SDK-DotNet or com.blockadelabs.sdk packages.
2. Authenticate users with your OAuth provider.
3. After successful authentication, create a new BlockadeLabsAuthentication object and pass in the custom token as your apiKey.
4. Create a new BlockadeLabsClientSettings object and specify the domain where your intermediate API is located.
5. Pass your new auth and settings objects to the BlockadeLabsClient constructor when you create the client instance.

Here's an example of how to set up the front end:

var authToken = await LoginAsync();
var auth = new BlockadeLabsAuthentication(authToken);
var settings = new BlockadeLabsClientSettings(domain: "api.your-custom-domain.com");
using var api = new BlockadeLabsClient(auth, settings);

This setup allows your front end application to securely communicate with your backend that will be using the BlockadeLabs-SDK-DotNet-Proxy, which then forwards requests to the BlockadeLabs API. This ensures that your BlockadeLabs API keys and other sensitive information remain secure throughout the process.

Back End Example

In this example, we demonstrate how to set up and use BlockadeLabsProxy in a new ASP.NET Core web app. The proxy server will handle authentication and forward requests to the BlockadeLabs API, ensuring that your API keys and other sensitive information remain secure.

1. Create a new ASP.NET Core minimal web API project.
2. Add the BlockadeLabs-SDK-DotNet nuget package to your project.
   • Powershell install: Install-Package BlockadeLabs-SDK-DotNet-Proxy
   • Manually editing .csproj: <PackageReference Include="BlockadeLabs-SDK-DotNet-Proxy" />
3. Create a new class that inherits from AbstractAuthenticationFilter and override the ValidateAuthentication method. This will implement the IAuthenticationFilter that you will use to check user session token against your internal server.
4. In Program.cs, create a new proxy web application by calling BlockadeLabsProxy.CreateWebApplication method, passing your custom AuthenticationFilter as a type argument.
5. Create BlockadeLabsAuthentication as you would normally and load your API key from environment variable.

public partial class Program
{
    private class AuthenticationFilter : AbstractAuthenticationFilter
    {
        public override void ValidateAuthentication(IHeaderDictionary request)
        {
            // You will need to implement your own class to properly test
            // custom issued tokens you've setup for your end users.
            if (!request["x-api-key"].ToString().Contains(TestUserToken))
            {
                throw new AuthenticationException("User is not authorized");
            }
        }

        public override async Task ValidateAuthenticationAsync(IHeaderDictionary request)
        {
            await Task.CompletedTask; // remote resource call

            // You will need to implement your own class to properly test
            // custom issued tokens you've setup for your end users.
            if (!request["x-api-key"].ToString().Contains(TestUserToken))
            {
                throw new AuthenticationException("User is not authorized");
            }
        }
    }

    public static void Main(string[] args)
    {
        var auth = BlockadeLabsAuthentication.LoadFromEnvironment();
        using var blockadeLabsClient = new BlockadeLabsClient(auth);
        BlockadeLabsProxy.CreateWebApplication<AuthenticationFilter>(args, blockadeLabsClient).Run();
    }
}

Once you have set up your proxy server, your end users can now make authenticated requests to your proxy api instead of directly to the BlockadeLabs API. The proxy server will handle authentication and forward requests to the BlockadeLabs API, ensuring that your API keys and other sensitive information remain secure.

Skyboxes

Get Skybox Styles

Returns the list of predefined styles that can influence the overall aesthetic of your skybox generation.

using var api = new BlockadeLabsClient();
var skyboxStyles = await api.SkyboxEndpoint.GetSkyboxStylesAsync(SkyboxModel.Model3);

foreach (var skyboxStyle in skyboxStyles)
{
    Console.WriteLine($"{skyboxStyle.Name}");
}

Get Skybox Style Families

Returns the list of predefined styles that can influence the overall aesthetic of your skybox generation, sorted by style family. This route can be used in order to build a menu of styles sorted by family.

using var api = new BlockadeLabsClient();
var skyboxFamilyStyles = await BlockadeLabsClient.SkyboxEndpoint.GetSkyboxStyleFamiliesAsync(SkyboxModel.Model3);

foreach (var skyboxStyle in skyboxFamilyStyles)
{
    Console.WriteLine($"{skyboxStyle.Name}");
}

Get Skybox Export Options

Returns the list of all available export types.

using var api = new BlockadeLabsClient();
var exportOptions = await api.SkyboxEndpoint.GetAllSkyboxExportOptionsAsync();

foreach (var exportOption in exportOptions)
{
    Console.WriteLine($"{exportOption.Id}: {exportOption.Name} | {exportOption.Key}");
}

var request = new SkyboxRequest("mars", enhancePrompt: true);
// Generates ALL export options for the skybox
var skyboxInfo = await api.SkyboxEndpoint.GenerateSkyboxAsync(request, exportOptions);
Console.WriteLine($"Successfully created skybox: {skyboxInfo.Id}");

Generate Skybox

Generate a skybox.

using var api = new BlockadeLabsClient();
var skyboxStyles = await BlockadeLabsClient.SkyboxEndpoint.GetSkyboxStylesAsync(SkyboxModel.Model3);
var request = new SkyboxRequest(skyboxStyles.First(), "mars", enhancePrompt: true);

// You can also get progress callbacks when the generation progress has changed/updated
var progress = new Progress<SkyboxInfo>(async progress =>
{
    Console.WriteLine(progress);
});

var skyboxInfo = await api.SkyboxEndpoint.GenerateSkyboxAsync(request, progressCallback: progress);
Console.WriteLine($"Successfully created skybox: {skyboxInfo.Id}");

Get Skybox

Returns the skybox metadata for the given skybox id.

var skyboxId = 42;
using var api = new BlockadeLabsClient();
var skyboxInfo = await api.SkyboxEndpoint.GetSkyboxInfoAsync(skyboxId);
Console.WriteLine($"Skybox: {result.Id}");

Request Skybox Export

Exports the skybox with the requested export type.

[!NOTE] You can also specify the export types when initially generating a skybox.

var skyboxId = 42;
using var api = new BlockadeLabsClient();
var skyboxInfo = await api.SkyboxEndpoint.GetSkyboxInfoAsync(skyboxId);
skyboxInfo = await api.SkyboxEndpoint.ExportSkyboxAsync(skyboxInfo, DefaultExportOptions.DepthMap_PNG);

foreach (var exportInfo in skyboxInfo.Exports)
{
    Console.WriteLine($"{exportInfo.Key} -> {exportInfo.Value}");
}

Delete Skybox

Deletes a skybox by id.

var skyboxId = 42;
var result = await api.SkyboxEndpoint.DeleteSkyboxAsync(skybox);
// result == true

Get Skybox History

Gets the previously generated skyboxes.

var history = await api.SkyboxEndpoint.GetSkyboxHistoryAsync();
Console.WriteLine($"Found {history.TotalCount} skyboxes");

foreach (var skybox in history.Skyboxes)
{
    Console.WriteLine($"{skybox.Id} {skybox.Title} status: {skybox.Status}");
}

Cancel Skybox Generation

Cancels a pending skybox generation request by id.

var skyboxId = 42;
var result = await CancelSkyboxGenerationAsync(skyboxId);
// result == true

[!NOTE] This is automatically done when cancelling a skybox generation using cancellation token.

Cancel All Pending Skybox Generations

Cancels ALL pending skybox generation requests.

var result = await api.SkyboxEndpoint.CancelAllPendingSkyboxGenerationsAsync();
Console.WriteLine(result ? "All pending generations successfully cancelled" : "No pending generations");