> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/concepts/capabilities.md).

# Capabilities

Capabilities represent the types of AI operations that providers can support.

A capability represents a type of AI operation. Providers implement capabilities to expose their features, and profiles are configured for a specific capability. Capabilities build on Microsoft.Extensions.AI (M.E.AI) interfaces.

## Available Capabilities

| Capability           | Description                                               | M.E.AI Interface                                |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------- |
| **Chat**             | Conversational AI, text generation, completions           | `IChatClient`                                   |
| **Embedding**        | Vector embeddings for semantic search                     | `IEmbeddingGenerator<string, Embedding<float>>` |
| **Speech-to-Text**   | Audio transcription and voice input                       | `ISpeechToTextClient`                           |
| **Image Generation** | Text-to-image generation and image editing (experimental) | `IImageGenerator`                               |
| **Decision**         | Typed yes/no, pick-one, and score answers (experimental)  | None. Uses the Umbraco AI `IAIDecisionClient`   |

## Chat Capability

The Chat capability provides conversational AI features:

* Text completion and generation
* Multi-turn conversations
* System prompts and instructions
* Streaming responses
* Tool/function calling

{% code title="Example.cs" %}

```csharp
var messages = new List<ChatMessage>
{
    new(ChatRole.System, "You are a helpful assistant."),
    new(ChatRole.User, "What is Umbraco?")
};

var response = await _chatService.GetChatResponseAsync(
    chat => chat.WithAlias("content-chat"),
    messages);
```

{% endcode %}

## Embedding Capability

The Embedding capability generates vector representations of text:

* Semantic search indexing
* Document similarity
* Clustering and classification
* Retrieval-augmented generation (RAG)

{% code title="Example.cs" %}

```csharp
var embedding = await _embeddingService.GenerateEmbeddingAsync(
    emb => emb.WithAlias("content-embedding"),
    "Umbraco is a content management system");

// embedding.Vector contains the float array
```

{% endcode %}

## Speech-to-Text Capability

The Speech-to-Text capability transcribes audio into text:

* Audio file transcription
* Real-time streaming transcription
* Language detection and hints
* Voice input for Contextual Copilot and Copilot Workspace

{% code title="Example.cs" %}

```csharp
var response = await _sttService.TranscribeAsync(
    stt => stt.WithAlias("voice-notes"),
    audioStream);

// response.Text contains the transcribed text
```

{% endcode %}

## Image Generation Capability

{% hint style="warning" %}
Image Generation is **experimental**. It is hidden unless the `Umbraco:AI:Experimental:ImageGeneration` feature flag is enabled, and the C# API surface carries the `UMBRACOAI_IMAGEGEN` diagnostic, which consumers must suppress. See [Using the Image Generation API](/ai-in-umbraco/using-the-api/image-generation.md) for how to enable it.
{% endhint %}

The Image Generation capability produces images from text prompts:

* Text-to-image generation
* Maskless image editing (transform supplied images)
* Provider-native masked outpainting via an escape hatch
* Per-model size and capability constraints

{% code title="Example.cs" %}

```csharp
#pragma warning disable UMBRACOAI_IMAGEGEN

var response = await _imageGenerationService.GenerateImagesAsync(
    img => img.WithAlias("hero-banner"),
    "A serene mountain landscape at dawn");

// response.Contents contains the generated image content
```

{% endcode %}

## Decision Capability

{% hint style="warning" %}
Decision is **experimental**. It is hidden unless the `Umbraco:AI:Experimental:Decision` feature flag is enabled. The C# API surface carries the `UMBRACOAI_DECISION` diagnostic, which consumers must suppress. See [Decision](/ai-in-umbraco/using-the-api/decision.md) for how to enable it.
{% endhint %}

The Decision capability answers a typed question instead of returning free text:

* Yes/no questions, answered with a probability
* Pick-one questions, answered with the key of one of 2 to 255 options
* Score questions, answered against 2 to 10 labelled levels

Microsoft.Extensions.AI has no abstraction for this kind of model. Decision uses the Umbraco AI `IAIDecisionClient` interface instead.

{% code title="Example.cs" %}

```csharp
#pragma warning disable UMBRACOAI_DECISION

var response = await _decisionService.AskAsync(
    new AIBinaryDecisionQuestion { Instructions = "Is this comment spam?" },
    commentText);

// response.Answer.TrueProbability is the chance of "yes"; IsTrue() applies a 0.5 threshold
bool isSpam = response.Answer.IsTrue();
```

{% endcode %}

## Capability and Profile Relationship

Each profile is configured for exactly one capability. This ensures type safety and appropriate settings:

```
Chat Profile
    ├── Capability: Chat
    ├── Connection: OpenAI Prod
    ├── Model: gpt-4o
    └── Settings: AIChatProfileSettings
            ├── Temperature: 0.7
            ├── MaxTokens: 2000
            └── SystemPrompt: "..."

Embedding Profile
    ├── Capability: Embedding
    ├── Connection: OpenAI Prod
    ├── Model: text-embedding-3-small
    └── Settings: AIEmbeddingProfileSettings

Speech-to-Text Profile
    ├── Capability: Speech-to-Text
    ├── Connection: OpenAI Prod
    ├── Model: whisper-1
    └── Settings: AISpeechToTextProfileSettings

Image Generation Profile
    ├── Capability: ImageGeneration
    ├── Connection: OpenAI Prod
    ├── Model: gpt-image-1
    └── Settings: AIImageGenerationProfileSettings

Decision Profile
    ├── Capability: Decision
    ├── Connection: TypeSafe AI
    ├── Model: jev-latest
    └── Settings: AIDecisionProfileSettings (no settings today)
```

## Checking Provider Capabilities

Not all providers support all capabilities. You can check what a provider supports:

{% code title="Example.cs" %}

```csharp
var provider = _registry.GetProvider("openai");

if (provider.HasCapability<IAIChatCapability>())
{
    // Provider supports chat
}

if (provider.HasCapability<IAIEmbeddingCapability>())
{
    // Provider supports embeddings
}

if (provider.HasCapability<IAISpeechToTextCapability>())
{
    // Provider supports speech-to-text
}

if (provider.HasCapability<IAIImageGeneratorCapability>())
{
    // Provider supports image generation
}

if (provider.HasCapability<IAIDecisionCapability>())
{
    // Provider supports decisions (experimental, needs UMBRACOAI_DECISION suppressed)
}
```

{% endcode %}

Experimental capabilities can be switched off for a whole install. To find the capabilities enabled on the current install, call the `GET /umbraco/ai/management/api/v1/capabilities/enabled` endpoint. See [List Capabilities](/ai-in-umbraco/management-api/connections/capabilities.md#list-enabled-capabilities).

## Capability Interfaces

Capabilities are defined by interfaces in `Umbraco.AI.Core`:

{% code title="IAIChatCapability.cs" %}

```csharp
public interface IAIChatCapability : IAICapability
{
    Task<IChatClient> CreateClientAsync(
        object? settings = null,
        string? modelId = null,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

{% code title="IAIEmbeddingCapability.cs" %}

```csharp
public interface IAIEmbeddingCapability : IAICapability
{
    Task<IEmbeddingGenerator<string, Embedding<float>>> CreateGeneratorAsync(
        object? settings,
        string? modelId = null,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

{% code title="IAISpeechToTextCapability.cs" %}

```csharp
public interface IAISpeechToTextCapability : IAICapability
{
    Task<ISpeechToTextClient> CreateClientAsync(
        object? settings = null,
        string? modelId = null,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

{% code title="IAIDecisionCapability.cs" %}

```csharp
[Experimental("UMBRACOAI_DECISION")]
public interface IAIDecisionCapability : IAICapability
{
    Task<IAIDecisionClient> CreateClientAsync(
        object? settings = null,
        string? modelId = null,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

## Related

* [Providers](/ai-in-umbraco/concepts/providers.md) - Implement capabilities
* [Profiles](/ai-in-umbraco/concepts/profiles.md) - Configure capability-specific settings
* [Chat API](/ai-in-umbraco/using-the-api/chat.md) - Use the Chat capability
* [Embeddings API](/ai-in-umbraco/using-the-api/embeddings.md) - Use the Embedding capability
* [Speech-to-Text API](/ai-in-umbraco/using-the-api/speech-to-text.md) - Use the Speech-to-Text capability
* [Image Generation API](/ai-in-umbraco/using-the-api/image-generation.md) - Use the Image Generation capability
* [Decision API](/ai-in-umbraco/using-the-api/decision.md) - Use the Decision capability (experimental)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/concepts/capabilities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.