ElBruno.Text2Image.Cpu 1.2.11

ElBruno.Text2Image

HuggingFace ONNX Models:

📦 NuGet Packages

Package	Version	Downloads
ElBruno.Text2Image
ElBruno.Text2Image.Foundry
ElBruno.Text2Image.Cpu
ElBruno.Text2Image.Cuda
ElBruno.Text2Image.DirectML
ElBruno.Text2Image.Cli

📢 Origin Story: This project started with FLUX.2 Flex on Microsoft Foundry — a cloud-first approach to text-to-image generation with best-in-class text rendering. After wrapping that API, we thought: "Why not bring the same developer experience to local models too?" So we did. Now you can generate images from text prompts using cloud APIs or local Stable Diffusion models with ONNX Runtime — all through the same clean .NET interface.

What is This?

Text-to-image for .NET developers: use as library, CLI tool, or AI coding skill. Cloud (FLUX.2, MAI-Image-2, GPT-Image) + local ONNX (Stable Diffusion). No Python required.

Three Ways to Use It

Model Support

☁️ Cloud Models (API-based, no GPU required)

🖥️ Local Models (ONNX Runtime, works offline)

Why This Library?

✅ No Python — Pure .NET, no environment setup headaches
✅ ~30 MB footprint — Lightweight compared to Python stacks
✅ Cross-platform — Windows, Linux, macOS
✅ Auto GPU detection — CUDA → DirectML → CPU fallback
✅ Unified interface — Same API for cloud and local models
✅ Microsoft.Extensions.AI — Implements IImageGenerator standard

What's Your Use Case?

Are you a...

🛠️ Command-Line Tool

Install the cross-platform CLI:

dotnet tool install --global ElBruno.Text2Image.Cli

Update to the latest version:

dotnet tool update --global ElBruno.Text2Image.Cli

Note: All packages are released with matching versions for consistency. Use t2i doctor to verify your CLI version and configuration.

CLI Examples

Local Models (Stable Diffusion):

t2i config                                           # interactive setup
t2i "a robot painting a landscape"                  # generate with default local model
t2i --provider stable-diffusion-15 "sunset over mountains, oil painting style"

Cloud Models (Microsoft Foundry & Azure OpenAI):

# FLUX.2 Pro (photorealistic)
t2i --provider foundry-flux2 "a futuristic cityscape with neon lights"

# FLUX.2 Flex (optimized for text-heavy design)
t2i config set foundry-flux2.model FLUX.2-flex
t2i "a business card design with modern minimalist style"

# MAI-Image-2 (high-quality generation)
t2i --provider foundry-mai2 "a serene mountain landscape at sunrise"

# GPT-Image-1.5 (DALL-E 3 via Azure OpenAI)
t2i --provider azure-openai-gpt-image-15 "an impressionist painting of a garden"

# GPT-Image-2 (next-gen model, may take 3-4 minutes)
t2i --provider gpt-image-2 "a sci-fi space station in orbit" --timeout 300

Model Configuration:

# View current configuration
t2i config show

# Set default provider for cloud generation
t2i config set provider foundry-flux2

# Set model variant
t2i config set foundry-mai2.model MAI-Image-2e
t2i config set foundry-flux2.model FLUX.2-flex

# Provide credentials
t2i config set foundry-flux2.endpoint "https://your-resource.services.ai.azure.com"
t2i config set foundry-flux2.apiKey "your-api-key"

See docs/cli-tool.md for the full guide.

Features

• 🎨 Text-to-Image — Generate images from text prompts using Stable Diffusion, FLUX.2, GPT-Image-1.5, and more
• 🤖 Multiple Models — Stable Diffusion 1.5, LCM Dreamshaper, SDXL Turbo, SD 2.1, FLUX.2, MAI-Image-2, GPT-Image-1.5, GPT-Image-2
• ☁️ Cloud APIs — FLUX.2, MAI-Image-2 (Microsoft Foundry), GPT-Image-1.5, GPT-Image-2 (Azure OpenAI)
• 🔧 ONNX Runtime — Fast, cross-platform inference (CPU, CUDA, DirectML)
• ⚡ Auto GPU Detection — Automatically uses GPU if available (CUDA → DirectML → CPU)
• 📦 NuGet Package — Simple dotnet add package installation
• 🎯 Multi-target — Supports .NET 8.0 and .NET 10.0
• 🔌 Microsoft.Extensions.AI — All generators implement IImageGenerator from Microsoft.Extensions.AI
• 🌱 Reproducible — Seed-based generation for reproducible results

🤖 AI Agent Integration

The t2i CLI is now discoverable by GitHub Copilot and Claude Code as a native skill, enabling AI agents to generate images directly within your development workflow. Run t2i init to configure skill integration, which adds the necessary metadata to .github/skills/t2i/ or .claude/skills/t2i/ directories in your workspace. Once integrated, AI agents can autonomously invoke t2i for image generation tasks without manual configuration.

See docs/skill-integration.md for the complete setup guide.

Quick Start

Install

Choose the package matching your hardware:

# CPU (default — works everywhere)
dotnet add package ElBruno.Text2Image.Cpu

# NVIDIA GPU (CUDA — 4x faster)
dotnet add package ElBruno.Text2Image.Cuda

# DirectML (AMD/Intel/NVIDIA on Windows)
dotnet add package ElBruno.Text2Image.DirectML

# FLUX.2 cloud via Microsoft Foundry (no GPU needed)
dotnet add package ElBruno.Text2Image.Foundry

Note: These are mutually exclusive — install only ONE, following the same pattern as Microsoft.ML.OnnxRuntime vs Microsoft.ML.OnnxRuntime.Gpu.

Basic Usage — Local (Stable Diffusion 1.5)

using ElBruno.Text2Image;
using ElBruno.Text2Image.Models;

// Create a Stable Diffusion 1.5 generator (model downloads automatically on first use)
using var generator = new StableDiffusion15();

// Generate an image from a text prompt
var result = await generator.GenerateAsync("a beautiful sunset over a mountain lake, digital art");

// Save the generated image
await result.SaveAsync("output.png");
Console.WriteLine($"Generated in {result.InferenceTimeMs}ms (seed: {result.Seed})");

Basic Usage — Cloud (FLUX.2 via Microsoft Foundry)

using ElBruno.Text2Image;
using ElBruno.Text2Image.Foundry;

// Create a FLUX.2 generator using Microsoft Foundry
// Default model is FLUX.2-pro (photorealistic image generation)
using var generator = new Flux2Generator(
    endpoint: "https://your-resource.services.ai.azure.com",
    apiKey: "your-api-key",
    modelName: "FLUX.2 Pro",       // display name
    modelId: "FLUX.2-pro");        // deployment/model name

// Generate an image — same interface as local models
var result = await generator.GenerateAsync("a futuristic cityscape with neon lights, cyberpunk style");
await result.SaveAsync("flux2-output.png");

// Or use FLUX.2 Flex for text-heavy design:
using var flexGenerator = new Flux2Generator(endpoint, apiKey,
    modelName: "FLUX.2 Flex", modelId: "FLUX.2-flex");

Basic Usage — Cloud (MAI-Image-2)

using ElBruno.Text2Image;
using ElBruno.Text2Image.Foundry;

// Create an MAI-Image-2 generator using Microsoft Foundry
// Default model is MAI-Image-2
using var generator = new MaiImage2Generator(
    endpoint: "https://your-resource.services.ai.azure.com",
    apiKey: "your-api-key",
    modelName: "MAI-Image-2",
    modelId: "MAI-Image-2");

var result = await generator.GenerateAsync("a futuristic cityscape with neon lights, cyberpunk style");
await result.SaveAsync("mai-image2-output.png");

// Or use MAI-Image-2e for alternative model:
using var maiE = new MaiImage2Generator(endpoint, apiKey,
    modelName: "MAI-Image-2e", modelId: "MAI-Image-2e");

Basic Usage — Cloud (GPT-Image-1.5 via Azure OpenAI)

using ElBruno.Text2Image;
using ElBruno.Text2Image.Foundry;

// Create a GPT-Image-1.5 (DALL-E 3) generator using Azure OpenAI
using var generator = new GptImage1p5Generator(
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: "your-api-key",
    deploymentName: "gpt-image-15");

// Generate an image — same interface as other providers
var result = await generator.GenerateAsync("a serene mountain landscape at sunset, oil painting style");
await result.SaveAsync("gpt-image-1p5-output.png");

// Request specific size (1024×1024, 1792×1024, or 1024×1792)
var landscape = await generator.GenerateAsync(
    "a panoramic view of a futuristic cityscape",
    new ImageGenerationOptions { Width = 1792, Height = 1024 });

With Custom Options

using var generator = new StableDiffusion15();

var result = await generator.GenerateAsync("a futuristic cityscape at night, neon lights",
    new ImageGenerationOptions
    {
        NumInferenceSteps = 20,  // More steps = better quality
        GuidanceScale = 7.5,     // Higher = follows prompt more closely
        Width = 512,
        Height = 512,
        Seed = 42,               // For reproducible results
        ExecutionProvider = ExecutionProvider.Cpu
    });

await result.SaveAsync("cityscape.png");

Microsoft.Extensions.AI Interface

All generators implement Microsoft.Extensions.AI.IImageGenerator, enabling a standard API:

using Microsoft.Extensions.AI;
using ElBruno.Text2Image.Models;

// Any generator can be used via the M.E.AI interface
using var sd15 = new StableDiffusion15();
IImageGenerator generator = sd15;

var request = new ImageGenerationRequest("a whimsical treehouse in a fantasy forest");
var options = new ImageGenerationOptions
{
    ImageSize = new System.Drawing.Size(512, 512),
    AdditionalProperties = new AdditionalPropertiesDictionary
    {
        ["num_inference_steps"] = 15,
        ["guidance_scale"] = 7.5,
        ["seed"] = 42
    }
};

var response = await generator.GenerateAsync(request, options);
var imageBytes = response.Contents.OfType<DataContent>().First().Data.ToArray();
await File.WriteAllBytesAsync("output.png", imageBytes);

Custom Model Directory

// Download and use models from a specific directory
using var generator = new StableDiffusion15(new ImageGenerationOptions
{
    ModelDirectory = @"D:\MyModels",
    NumInferenceSteps = 15
});

await generator.EnsureModelAvailableAsync();
var result = await generator.GenerateAsync("a serene lake");
await result.SaveAsync("output.png");

Dependency Injection

// Local model
services.AddStableDiffusion15(options =>
{
    options.NumInferenceSteps = 20;
    options.ModelDirectory = "/path/to/models";
});

// Cloud model (requires ElBruno.Text2Image.Foundry package)
services.AddFlux2Generator(
    endpoint: "https://your-resource.openai.azure.com",
    apiKey: "your-api-key",
    modelId: "FLUX.2-pro");

// MAI-Image-2 cloud model (requires ElBruno.Text2Image.Foundry package)
services.AddMaiImage2Generator(
    endpoint: "https://your-resource.services.ai.azure.com",
    apiKey: "your-api-key",
    modelId: "MAI-Image-2");

// Inject IImageGenerator anywhere
public class MyService(IImageGenerator generator)
{
    public async Task<byte[]> GenerateImage(string prompt)
    {
        var result = await generator.GenerateAsync(prompt);
        return result.ImageBytes;
    }
}

Supported Models

Local Models (ONNX Runtime)

Cloud Models (REST API)

| Model | Class | Provider | Quality | Status | |-------|-------|----------|---------|--------| | FLUX.2 Pro | Flux2Generator | Microsoft Foundry | Excellent | ✅ Default | | FLUX.2 Flex | Flux2Generator | Microsoft Foundry | Excellent | ✅ Available | | MAI-Image-2 | MaiImage2Generator | Microsoft Foundry | Excellent | ✅ Available | | GPT-Image-1.5 | GptImage1p5Generator | Azure OpenAI (DALL-E 3) | Excellent | ✅ Available | See docs/model-support.md for detailed model comparison.

Samples

Run a Sample

cd src/samples/scenario-01-simple
dotnet run

Documentation

• docs/architecture.md — Package structure and pipeline diagrams
• docs/gpu-acceleration.md — GPU setup (CUDA, DirectML, auto-detection)
• docs/flux2-setup-guide.md — Microsoft Foundry FLUX.2 setup
• docs/mai-image-2-setup-guide.md — Microsoft Foundry MAI-Image-2 setup
• docs/gpt-image-1p5-setup-guide.md — Azure OpenAI GPT-Image-1.5 (DALL-E 3) setup
• docs/model-support.md — Detailed model comparison
• docs/onnx-conversion-guide.md — Step-by-step ONNX conversion guide
• docs/publishing.md — NuGet publishing guide (Trusted Publishing / OIDC)
• docs/version-management.md — Version bumping and unified versioning workflow
• docs/security.md — Security considerations and hardening
• scripts/ — Python conversion and upload scripts

👋 About the Author

Hi! I'm ElBruno 🧡, a passionate developer and content creator exploring AI, .NET, and modern development practices.

Made with ❤️ by ElBruno

If you like this project, consider following my work across platforms:

• 📻 Podcast: No Tienen Nombre — Spanish-language episodes on AI, development, and tech culture
• 💻 Blog: ElBruno.com — Deep dives on embeddings, RAG, .NET, and local AI
• 📺 YouTube: youtube.com/elbruno — Demos, tutorials, and live coding
• 🔗 LinkedIn: @elbruno — Professional updates and insights
• 𝕏 Twitter: @elbruno — Quick tips, releases, and tech news

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• ElBruno.HuggingFace.Downloader
• ElBruno.LocalEmbeddings
• ElBruno.VibeVoiceTTS
• ElBruno.QwenTTS
• ElBruno.PersonaPlex — NVIDIA PersonaPlex-7B-v1 speech-to-speech model wrapper for C#