microsoft/semantic-kernel · error · NotSupportedException

The provided quality

Error message

The provided quality '{quality}' is not supported.

What it means

The image quality string is matched case-insensitively against STANDARD, HIGH, HD, MEDIUM, LOW, AUTO. Null is allowed (returns null, omitting the parameter). Any other value throws NotSupportedException before the request is sent.

Solutions

1. Use one of: standard, high, hd, medium, low, auto (case-insensitive).
2. Leave Quality unset/null if you don't need to override the default.
3. Upgrade the connector package if a newer quality level is available upstream.

Example fix

// before
var settings = new OpenAITextToImageExecutionSettings { Quality = "ultra" };

// after
var settings = new OpenAITextToImageExecutionSettings { Quality = "hd" };

static readonly HashSet<string> SupportedQualities = new(StringComparer.OrdinalIgnoreCase)
{
    "standard", "high", "hd", "medium", "low", "auto"
};

void ValidateQuality(string? quality)
{
    if (quality is not null && !SupportedQualities.Contains(quality.Trim()))
        throw new ArgumentOutOfRangeException(nameof(quality),
            $"Quality must be one of: {string.Join(", ", SupportedQualities)} (or null)");
}

try { await imageService.GetTextToImageAsync(prompt, settings); }
catch (NotSupportedException ex) when (ex.Message.Contains("quality"))
{
    settings.Quality = null;
    await imageService.GetTextToImageAsync(prompt, settings);
}

When it happens

Trigger: Passing an OpenAITextToImageExecutionSettings.Quality value not in the allowed set, e.g. 'ultra', 'best', or a numeric like '1'.

Common situations: Using a quality token from newer OpenAI API docs not yet mapped by the installed connector version. Passing a quality name that only applies to a different model (e.g. DALL-E 2 values used with DALL-E 3).

Related errors

• The provided response format
• The provided style ' ' is not supported.
• Invalid image size: x .
• Prompt is required.
• Provide either 'image_paths' or 'image_files', and only one.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/389d9a6086d19d0c. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToImage.cs:128

        => size is null
            ? null
            : new GeneratedImageSize(size.Value.Width, size.Value.Height);

    private static GeneratedImageQuality? GetGeneratedImageQuality(string? quality)
    {
        if (quality is null)
        {
            return null;
        }

        return quality.ToUpperInvariant() switch
        {
            "STANDARD" => GeneratedImageQuality.Standard,
            "HIGH" or "HD" => GeneratedImageQuality.High,
            "MEDIUM" => GeneratedImageQuality.MediumQuality,
            "LOW" => GeneratedImageQuality.LowQuality,
            "AUTO" => GeneratedImageQuality.Auto,
            _ => throw new NotSupportedException($"The provided quality '{quality}' is not supported.")
        };
    }

    private static GeneratedImageStyle? GetGeneratedImageStyle(string? style)
    {
        if (style is null)
        {
            return null;
        }

        return style.ToUpperInvariant() switch
        {
            "VIVID" => GeneratedImageStyle.Vivid,
            "NATURAL" => GeneratedImageStyle.Natural,
            _ => throw new NotSupportedException($"The provided style '{style}' is not supported.")
        };
    }

View on GitHub (pinned to c028a0c7dc)