Configuration - DrHazemAli/AzureSoraSDK GitHub Wiki

Configuration

This page provides detailed information about configuring the AzureSoraSDK.

Configuration Classes

SoraClientOptions

The main configuration class for video generation with all available options:

Property	Type	Default	Description
`Endpoint`	string	Required	Azure OpenAI endpoint URL for video generation
`ApiKey`	string	Required	API key for video generation authentication
`DeploymentName`	string	Required	Name of your Sora deployment
`ApiVersion`	string	"preview"	Azure OpenAI API version for video generation
`HttpTimeout`	TimeSpan	5 minutes	HTTP request timeout
`MaxRetryAttempts`	int	3	Maximum retry attempts for failed requests
`RetryDelay`	TimeSpan	2 seconds	Base delay between retries (exponential backoff)
`DefaultPollingInterval`	TimeSpan	5 seconds	Default interval for job status polling
`MaxWaitTime`	TimeSpan	1 hour	Maximum time to wait for job completion

PromptEnhancerOptions

The configuration class for prompt enhancement with chat completion models:

Property	Type	Default	Description
`Endpoint`	string	Required	Azure OpenAI endpoint URL for chat completions
`ApiKey`	string	Required	API key for chat completions authentication
`DeploymentName`	string	Required	Name of your chat completion deployment (e.g., gpt-4)
`ApiVersion`	string	"2024-02-15-preview"	Azure OpenAI API version for chat completions
`HttpTimeout`	TimeSpan	2 minutes	HTTP request timeout
`MaxRetryAttempts`	int	3	Maximum retry attempts for failed requests
`RetryDelay`	TimeSpan	1 second	Base delay between retries (exponential backoff)
`DefaultTemperature`	double	0.7	Temperature for prompt enhancement completions
`DefaultTopP`	double	0.9	Top-p value for prompt enhancement completions
`MaxTokensPerRequest`	int	1000	Maximum tokens per prompt enhancement request

Configuration Methods

1. Separate Configuration (Recommended)

Configure video generation and prompt enhancement with different endpoints and settings:

Using appsettings.json

{
  "AzureSora": {
    "Endpoint": "https://your-sora-endpoint.openai.azure.com",
    "ApiKey": "your-sora-api-key",
    "DeploymentName": "sora",
    "ApiVersion": "preview",
    "HttpTimeout": "00:05:00",
    "MaxRetryAttempts": 3,
    "RetryDelay": "00:00:02",
    "DefaultPollingInterval": "00:00:05",
    "MaxWaitTime": "01:00:00"
  },
  "PromptEnhancer": {
    "Endpoint": "https://your-chat-endpoint.openai.azure.com",
    "ApiKey": "your-chat-api-key",
    "DeploymentName": "gpt-4",
    "ApiVersion": "2024-02-15-preview",
    "HttpTimeout": "00:02:00",
    "MaxRetryAttempts": 3,
    "RetryDelay": "00:00:01",
    "DefaultTemperature": 0.7,
    "DefaultTopP": 0.9,
    "MaxTokensPerRequest": 1500
  }
}

Load in Program.cs:

builder.Services.AddAzureSoraSDK(
    builder.Configuration.GetSection("AzureSora"));

Using Code Configuration

builder.Services.AddAzureSoraSDK(
    configureSoraOptions: options =>
    {
        options.Endpoint = "https://your-sora-endpoint.openai.azure.com";
        options.ApiKey = "your-sora-api-key";
        options.DeploymentName = "sora";
        options.ApiVersion = "preview";
        options.HttpTimeout = TimeSpan.FromMinutes(10);
        options.MaxRetryAttempts = 5;
        options.RetryDelay = TimeSpan.FromSeconds(3);
        options.DefaultPollingInterval = TimeSpan.FromSeconds(10);
        options.MaxWaitTime = TimeSpan.FromMinutes(30);
    },
    configurePromptEnhancerOptions: options =>
    {
        options.Endpoint = "https://your-chat-endpoint.openai.azure.com";
        options.ApiKey = "your-chat-api-key";
        options.DeploymentName = "gpt-4";
        options.ApiVersion = "2024-02-15-preview";
        options.HttpTimeout = TimeSpan.FromMinutes(3);
        options.MaxRetryAttempts = 3;
        options.RetryDelay = TimeSpan.FromSeconds(1);
        options.DefaultTemperature = 0.5;
        options.DefaultTopP = 0.8;
        options.MaxTokensPerRequest = 2000;
    });

2. Shared Configuration (Backward Compatible)

Use the same endpoint and configuration for both services:

Using appsettings.json

{
  "AzureSora": {
    "Endpoint": "https://your-resource.openai.azure.com",
    "ApiKey": "your-api-key",
    "DeploymentName": "sora",
    "ApiVersion": "preview",
    "HttpTimeout": "00:10:00",
    "MaxRetryAttempts": 5,
    "RetryDelay": "00:00:03",
    "DefaultPollingInterval": "00:00:10",
    "MaxWaitTime": "00:30:00"
  }
}

Load in Program.cs:

builder.Services.AddAzureSoraSDK(
    builder.Configuration.GetSection("AzureSora"));

Using Code Configuration

builder.Services.AddAzureSoraSDK(options =>
{
    options.Endpoint = "https://your-resource.openai.azure.com";
    options.ApiKey = "your-api-key";
    options.DeploymentName = "sora";
    options.ApiVersion = "preview";
    options.HttpTimeout = TimeSpan.FromMinutes(10);
    options.MaxRetryAttempts = 5;
    options.RetryDelay = TimeSpan.FromSeconds(3);
    options.DefaultPollingInterval = TimeSpan.FromSeconds(10);
    options.MaxWaitTime = TimeSpan.FromMinutes(30);
});

3. Direct Constructor Usage

Create clients directly with specific options:

using AzureSoraSDK.Configuration;

// Create SoraClient with video generation options
var soraOptions = new SoraClientOptions
{
    Endpoint = "https://your-sora-endpoint.openai.azure.com",
    ApiKey = "your-sora-api-key",
    DeploymentName = "sora",
    ApiVersion = "preview"
};

var soraClient = new SoraClient(httpClient, soraOptions, logger);

// Create PromptEnhancer with separate options
var promptEnhancerOptions = new PromptEnhancerOptions
{
    Endpoint = "https://your-chat-endpoint.openai.azure.com",
    ApiKey = "your-chat-api-key",
    DeploymentName = "gpt-4",
    ApiVersion = "2024-02-15-preview",
    DefaultTemperature = 0.6,
    MaxTokensPerRequest = 1500
};

var promptEnhancer = new PromptEnhancer(httpClient, promptEnhancerOptions, logger);

4. Using Environment Variables

Set environment variables for separate services:

# Linux/macOS - Video Generation
export AZURE_OPENAI_SORA_ENDPOINT="https://your-sora-endpoint.openai.azure.com"
export AZURE_OPENAI_SORA_KEY="your-sora-api-key"
export AZURE_OPENAI_SORA_DEPLOYMENT="sora"

# Linux/macOS - Prompt Enhancement
export AZURE_OPENAI_CHAT_ENDPOINT="https://your-chat-endpoint.openai.azure.com"
export AZURE_OPENAI_CHAT_KEY="your-chat-api-key"
export AZURE_OPENAI_CHAT_DEPLOYMENT="gpt-4"

# Windows PowerShell - Video Generation
$env:AZURE_OPENAI_SORA_ENDPOINT="https://your-sora-endpoint.openai.azure.com"
$env:AZURE_OPENAI_SORA_KEY="your-sora-api-key"
$env:AZURE_OPENAI_SORA_DEPLOYMENT="sora"

# Windows PowerShell - Prompt Enhancement
$env:AZURE_OPENAI_CHAT_ENDPOINT="https://your-chat-endpoint.openai.azure.com"
$env:AZURE_OPENAI_CHAT_KEY="your-chat-api-key"
$env:AZURE_OPENAI_CHAT_DEPLOYMENT="gpt-4"

Use in code:

var soraEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_SORA_ENDPOINT");
var soraApiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_SORA_KEY");
var soraDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_SORA_DEPLOYMENT");

var chatEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_CHAT_ENDPOINT");
var chatApiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_CHAT_KEY");
var chatDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_CHAT_DEPLOYMENT");

builder.Services.AddAzureSoraSDK(
    configureSoraOptions: options =>
    {
        options.Endpoint = soraEndpoint;
        options.ApiKey = soraApiKey;
        options.DeploymentName = soraDeployment;
    },
    configurePromptEnhancerOptions: options =>
    {
        options.Endpoint = chatEndpoint;
        options.ApiKey = chatApiKey;
        options.DeploymentName = chatDeployment;
    });

5. Using Azure Key Vault

// Add Azure Key Vault
builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{keyVaultName}.vault.azure.net/"),
    new DefaultAzureCredential());

// Configure SDK with separate secrets
builder.Services.AddAzureSoraSDK(
    configureSoraOptions: options =>
    {
        options.Endpoint = builder.Configuration["AzureOpenAI-Sora-Endpoint"];
        options.ApiKey = builder.Configuration["AzureOpenAI-Sora-ApiKey"];
        options.DeploymentName = builder.Configuration["AzureOpenAI-Sora-DeploymentName"];
    },
    configurePromptEnhancerOptions: options =>
    {
        options.Endpoint = builder.Configuration["AzureOpenAI-Chat-Endpoint"];
        options.ApiKey = builder.Configuration["AzureOpenAI-Chat-ApiKey"];
        options.DeploymentName = builder.Configuration["AzureOpenAI-Chat-DeploymentName"];
    });

Advanced Configuration

Custom HttpClient Configuration

Configure separate HttpClients for each service:

// Configure SoraClient HttpClient
builder.Services.AddHttpClient<ISoraClient, SoraClient>(client =>
{
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp-SoraClient/1.0");
    client.DefaultRequestHeaders.Add("X-Video-Service", "sora");
})
.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
    AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
    MaxConnectionsPerServer = 5
});

// Configure PromptEnhancer HttpClient
builder.Services.AddHttpClient<IPromptEnhancer, PromptEnhancer>(client =>
{
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp-PromptEnhancer/1.0");
    client.DefaultRequestHeaders.Add("X-Chat-Service", "completion");
})
.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
    AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
    MaxConnectionsPerServer = 10
});

Logging Configuration

builder.Services.AddLogging(logging =>
{
    logging.AddConsole();
    logging.AddDebug();
    logging.SetMinimumLevel(LogLevel.Information);
    
    // Set specific levels for different services
    logging.AddFilter("AzureSoraSDK.SoraClient", LogLevel.Debug);
    logging.AddFilter("AzureSoraSDK.PromptEnhancer", LogLevel.Information);
});

Polly Retry Policies

The SDK uses separate Polly policies for each service. You can customize them:

// Custom retry policy for SoraClient (longer delays for video generation)
builder.Services.AddHttpClient<ISoraClient, SoraClient>()
    .AddPolicyHandler(HttpPolicyExtensions
        .HandleTransientHttpError()
        .OrResult(msg => msg.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(
            5,
            retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
            onRetry: (outcome, timespan, retry, context) =>
            {
                var logger = context.Values["logger"] as ILogger;
                logger?.LogWarning($"SoraClient retry {retry} after {timespan}");
            }));

// Custom retry policy for PromptEnhancer (faster retries for chat completions)
builder.Services.AddHttpClient<IPromptEnhancer, PromptEnhancer>()
    .AddPolicyHandler(HttpPolicyExtensions
        .HandleTransientHttpError()
        .OrResult(msg => msg.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(
            3,
            retryAttempt => TimeSpan.FromSeconds(Math.Pow(1.5, retryAttempt)),
            onRetry: (outcome, timespan, retry, context) =>
            {
                var logger = context.Values["logger"] as ILogger;
                logger?.LogWarning($"PromptEnhancer retry {retry} after {timespan}");
            }));

Configuration Validation

The SDK validates both configuration classes on startup. Common validation rules:

SoraClientOptions Validation

Endpoint must be a valid HTTPS URL
ApiKey must not be empty
DeploymentName must not be empty
HttpTimeout must be between 1 second and 30 minutes
MaxRetryAttempts must be between 0 and 10
RetryDelay must be between 100ms and 1 minute

PromptEnhancerOptions Validation

Endpoint must be a valid HTTPS URL
ApiKey must not be empty
DeploymentName must not be empty
ApiVersion must not be empty
HttpTimeout must be positive
MaxRetryAttempts must be between 0 and 10
RetryDelay must be positive
DefaultTemperature must be between 0.0 and 2.0
DefaultTopP must be between 0.0 and 1.0
MaxTokensPerRequest must be between 1 and 4096

Example Validation Error

try
{
    builder.Services.AddAzureSoraSDK(
        configureSoraOptions: options =>
        {
            options.Endpoint = ""; // Invalid
            options.ApiKey = "key";
            options.DeploymentName = "sora";
        },
        configurePromptEnhancerOptions: options =>
        {
            options.Endpoint = "https://valid.endpoint.com";
            options.ApiKey = "key";
            options.DeploymentName = "gpt-4";
            options.DefaultTemperature = 3.0; // Invalid - must be <= 2.0
        });
}
catch (ValidationException ex)
{
    Console.WriteLine($"Configuration error: {ex.Message}");
    // Output: Multiple validation errors
}

Best Practices

Use separate endpoints: Configure different endpoints for video generation and chat completions for optimal performance
Store secrets securely: Use Azure Key Vault or environment variables for sensitive data
Use appropriate timeouts: Video generation typically needs longer timeouts than chat completions
Configure retry logic: Set different retry strategies for different services
Monitor configuration: Log configuration values (except secrets) on startup
Use dependency injection: Prefer DI over manual instantiation for better testability
API versions: Use the latest stable API versions for each service

Configuration for Different Environments

Development

Optimized for faster feedback and debugging:

{
  "AzureSora": {
    "HttpTimeout": "00:15:00",
    "MaxRetryAttempts": 5,
    "DefaultPollingInterval": "00:00:02"
  },
  "PromptEnhancer": {
    "HttpTimeout": "00:03:00",
    "MaxRetryAttempts": 5,
    "RetryDelay": "00:00:01",
    "DefaultTemperature": 0.8
  }
}

Production

Optimized for reliability and cost:

{
  "AzureSora": {
    "HttpTimeout": "00:05:00",
    "MaxRetryAttempts": 3,
    "DefaultPollingInterval": "00:00:05"
  },
  "PromptEnhancer": {
    "HttpTimeout": "00:02:00",
    "MaxRetryAttempts": 3,
    "RetryDelay": "00:00:01",
    "DefaultTemperature": 0.7
  }
}

Migration Guide

From Single Configuration to Separate Configuration

If you're upgrading from a previous version, your existing configuration will continue to work:

// Old way (still works)
builder.Services.AddAzureSoraSDK(options =>
{
    options.Endpoint = "https://your-endpoint.openai.azure.com";
    options.ApiKey = "your-api-key";
    options.DeploymentName = "sora";
});

// New way (recommended)
builder.Services.AddAzureSoraSDK(
    configureSoraOptions: options =>
    {
        options.Endpoint = "https://your-sora-endpoint.openai.azure.com";
        options.ApiKey = "your-sora-api-key";
        options.DeploymentName = "sora";
    },
    configurePromptEnhancerOptions: options =>
    {
        options.Endpoint = "https://your-chat-endpoint.openai.azure.com";
        options.ApiKey = "your-chat-api-key";
        options.DeploymentName = "gpt-4";
    });

Next Steps

API Reference - Detailed API documentation
Error Handling - Configure error handling
Examples - See configuration examples in action