SwarmUI.ApiClient 0.13.1-beta

SwarmUI API Client Library

Professional C# client library for SwarmUI API

🚧 v0.13.0-beta 🚧

SwarmUI.ApiClient is a strongly-typed C# wrapper around the SwarmUI API, providing first-class support for text-to-image generation, model management, presets, user data, backends, and admin operations. The core implementation is in place and covered by unit tests; the API surface may still evolve before a 1.0.0 stable release.

Project Structure

Stock SwarmUI and SwarmUI extensions are deliberately kept in separate trees. Anything under Endpoints/ works against a vanilla SwarmUI server; anything under Extensions/ requires a specific extension to be installed on that server.

SwarmUI.ApiClient/
├── SwarmClient.cs                 # Main client class
├── ISwarmClient.cs                # Main client interface
├── SwarmClientOptions.cs          # Configuration options
├── SwarmClientServiceCollectionExtensions.cs   # AddSwarmClient DI registration
│
├── Sessions/                      # Session management
│   ├── ISessionManager.cs
│   └── SessionManager.cs
│
├── Http/                          # HTTP communication
│   ├── ISwarmHttpClient.cs
│   └── SwarmHttpClient.cs
│
├── WebSockets/                    # WebSocket streaming
│   ├── ISwarmWebSocketClient.cs
│   └── SwarmWebSocketClient.cs
│
├── Endpoints/                     # Stock SwarmUI API endpoint groups
│   ├── Generation/                # Text-to-image generation
│   ├── Models/                    # Model management
│   ├── Backends/                  # Backend servers
│   ├── Presets/                   # Parameter presets
│   ├── User/                      # User settings
│   └── Admin/                     # Admin operations
│
├── Contracts/                     # Wire contracts for stock SwarmUI endpoints
│   ├── Requests/                  # Request contracts
│   ├── Responses/                 # Response contracts
│   ├── Common/                    # Shared contracts
│   └── Enums/                     # Contract enums
│
├── Exceptions/                    # Custom exceptions
│   ├── SwarmException.cs
│   ├── SwarmSessionException.cs
│   ├── SwarmAuthenticationException.cs
│   └── SwarmWebSocketException.cs
│
└── Extensions/                    # SwarmUI server extensions, one folder per extension
    ├── README.md                  # Supported extension registry
    ├── ISwarmExtensions.cs        # Exposed as ISwarmClient.Extensions
    ├── ISwarmExtensionEndpoint.cs # Implemented by every extension endpoint group
    ├── SwarmExtensionInfo.cs      # Extension metadata for runtime discovery
    ├── AudioLab/                  # AudioLab extension
    │   ├── IAudioLabEndpoint.cs
    │   ├── AudioLabEndpoint.cs
    │   ├── AudioLabVoiceSessionClient.cs # duplex voice session; build one via IAudioLabEndpoint.CreateVoiceSession
    │   └── Contracts/             # Contracts owned by this extension
    ├── LLMAssistant/              # LLM Assistant extension
    │   ├── ILLMAssistantEndpoint.cs
    │   ├── LLMAssistantEndpoint.cs
    │   └── Contracts/
    └── MagicPrompt/               # MagicPrompt extension
        ├── IMagicPromptEndpoint.cs
        ├── MagicPromptEndpoint.cs
        └── Contracts/

Extension endpoints

Extension-backed endpoints are namespaced and accessed separately from the stock API, so a dependency on a server-side extension is visible in the folder tree, the namespace, and the call site:

// Stock SwarmUI - works against any server
ModelListResponse models = await client.Models.ListModelsAsync("Stable-Diffusion");

// Extension - requires SwarmUI-MagicPromptExtension installed on the server
MagicPromptResponse enhanced = await client.Extensions.MagicPrompt.EnhancePromptAsync(request);

// Extension - requires SwarmUI-AudioLab installed and an enabled Audio Backend
TextToSpeechResponse speech = await client.Extensions.AudioLab.SynthesizeSpeechAsync(ttsRequest);

// Extension - requires SwarmUI-LLMAssistant installed
await foreach (ChatStreamUpdate update in client.Extensions.LLMAssistant.StreamMessageAsync(chatRequest))
{
    Console.Write(update.Raw["token"]);
}

// Which extensions this client supports
foreach (SwarmExtensionInfo info in client.Extensions.All)
{
    Console.WriteLine($"{info.DisplayName} -> {info.RepositoryUrl}");
}

Supported extensions:

• AudioLab -- speech synthesis and transcription, audio engine and model management, format conversion, DAW projects, and a real-time voice agent session. Build one with client.Extensions.AudioLab.CreateVoiceSession(...) -- note it does not inherit the session key of a scoped client (eg one from client.ForSession(...)); pass that explicitly to the returned client's own ConnectAsync. Constructing AudioLabVoiceSessionClient directly still works too, for a caller without a full ISwarmClient to hand. Its generation parameters (music, TTS/STT) live on request.Extensions.AudioLab (AudioLabGenerationParams).
• LLM Assistant -- streaming chat threads, assistants, tools, LLM model management, per-user memory, and a stateless voice-turn endpoint for that same voice agent to answer through. Its prompt-processing generation parameters (<llmprompt> tag handling) live on request.Extensions.LLMAssistant (LLMAssistantGenerationParams).
• API Backends -- reports what a given API-backed model (BFL, OpenAI, Ideogram, Google, Grok, and fal.ai-fronted providers) will actually accept. Its generation parameters live on request.Extensions.APIBackends (APIBackendsGenerationParams).
• HartsyInference Backend -- reports which composition features, samplers, and schedulers an architecture or checkpoint supports. Its generation parameters live on request.Extensions.HartsyInference (HartsyInferenceGenerationParams).
• MagicPrompt -- prompt enhancement. Registers no generation parameters of its own.

Upgrading from before 0.13.0-beta: extension-registered parameters moved off GenerationRequest itself onto these per-extension groups (a breaking change) -- see the "Breaking changes" section for 0.13.0-beta in Docs/CHANGELOG.md for the full before/after mapping.

See Extensions/README.md for the supported extension registry and the steps for adding a new one.

Changelog

This README gives a high level snapshot. For detailed release notes, see:

• Docs/CHANGELOG.md

Highlights for the current beta:

• 0.13.0-beta, breaking: extension-registered GenerationRequest parameters (AudioLab, API Backends, HartsyInference, LLM Assistant) moved off the core type onto per-extension groups under request.Extensions.<Extension> -- see the "Breaking changes" section for 0.13.0-beta in Docs/CHANGELOG.md for the full migration map.
• 0.13.0-beta: client.Extensions.AudioLab.CreateVoiceSession(...) reaches AudioLab's real-time voice agent session without hand-threading SwarmClientOptions/ISessionManager yourself.
• Core infrastructure implemented: SwarmClientOptions, SessionManager, SwarmHttpClient, SwarmWebSocketClient, and the SwarmClient facade.
• Endpoint coverage for generation, models, backends, presets, user, and admin operations, plus the server extensions listed above.
• Unit tests in the SwarmTests project cover HTTP behavior, sessions, streaming generation, model management, presets, and client wiring.

Upcoming Features

Planned improvements for future releases include:

• Retry and resilience policies using Polly (configurable via SwarmClientOptions).
• Integration tests against a real SwarmUI instance.
• Optional examples project / samples that mirror the docs.
• CI/CD pipeline for automated build, test, pack, and publish to NuGet.
• Potential multi targeting support for additional .NET versions.

Usage

Standalone Usage

SwarmClientOptions options = new SwarmClientOptions
{
    BaseUrl = "https://hartsy.ai",
    Authorization = "your-api-key"
};
await using SwarmClient client = new SwarmClient(options);
GenerationRequest request = new GenerationRequest
{
    Prompt = "A beautiful sunset over mountains",
    Model = "flux-dev",
    Width = 1024,
    Height = 768
};
await foreach (GenerationUpdate update in client.Generation.StreamGenerationAsync(request))
{
    if (update.Type == "progress")
        Console.WriteLine($"Progress: {update.Progress.CurrentPercent}%");
    else if (update.Type == "image")
        SaveImage(update.Image.Image);   // relative server path OR data: URL — check update.Image.IsDataUrl
    else if (update.Type == "complete")
        Console.WriteLine($"Done. Succeeded: {update.Completion.Succeeded}, images: {update.Completion.ImagesReceived}");
}

Multi-user hosts: per-user sessions

SwarmUI scopes generation queues, status counters, and InterruptAll to a session. If your app serves many users through one ISwarmClient, route each user through their own session key so one user's cancel can never kill another user's generation:

ISwarmClient userView = swarm.ForSession(appUserId);
await foreach (GenerationUpdate update in userView.Generation.StreamGenerationAsync(request, ct)) { /* ... */ }
// Cancels ONLY this user's generations:
await userView.Generation.InterruptAllAsync();

Sessions are pooled, created on demand, and transparently re-acquired if the SwarmUI server restarts or rejects one — a Swarm restart never requires restarting your app.

Dependency Injection Usage

// Program.cs - AddSwarmClient lives in the Microsoft.Extensions.DependencyInjection
// namespace, so no extra using directive is needed in a typical host.
builder.Services.AddSwarmClient(options =>
{
    options.BaseUrl = "https://hartsy.ai";
    options.Authorization = builder.Configuration["SwarmAuth"];
});

// YourService.cs
public class ImageService(ISwarmClient swarm)
{
    public async Task GenerateAsync()
    {
        // Use swarm...
    }
}

Contributing

This library follows strict coding guidelines:

• No var keyword - always use explicit types
• All public members must have XML documentation
• Follow .NET naming conventions
• Use ConfigureAwait(false) in library code

See detailed guidelines in Docs/CodingGuidelines.md.

Real-World Usage Examples

The HartsyWeb application uses SwarmUI.ApiClient in production for both internal and external APIs. For example, an ASP.NET Core controller can stream generation updates to the client using Server-Sent Events (SSE):

[ApiController]
[Route("api/swarm")]
public class GenerateController(ISwarmClient swarmClient) : ControllerBase
{
    [HttpPost("generate")]
    public async Task Generate([FromBody] GenerationRequest request, CancellationToken cancellationToken)
    {
        Response.Headers.Append("Content-Type", "text/event-stream");

        await foreach (GenerationUpdate update in swarmClient.Generation.StreamGenerationAsync(request, cancellationToken))
        {
            // Write SSE event data and flush the response stream here.
        }
    }
}

See the HartsyWeb repository for full controller implementations and additional end-to-end examples.

License

MIT License. See the LICENSE file in this folder.

Links

• SwarmUI: https://github.com/mcmonkeyprojects/SwarmUI
• SwarmUI API Docs: https://github.com/mcmonkeyprojects/SwarmUI/blob/master/docs/API.md