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 URLApiKey
must not be emptyDeploymentName
must not be emptyHttpTimeout
must be between 1 second and 30 minutesMaxRetryAttempts
must be between 0 and 10RetryDelay
must be between 100ms and 1 minute
PromptEnhancerOptions Validation
Endpoint
must be a valid HTTPS URLApiKey
must not be emptyDeploymentName
must not be emptyApiVersion
must not be emptyHttpTimeout
must be positiveMaxRetryAttempts
must be between 0 and 10RetryDelay
must be positiveDefaultTemperature
must be between 0.0 and 2.0DefaultTopP
must be between 0.0 and 1.0MaxTokensPerRequest
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