---
title: "Capability API"
manual: "Ai3 Core"
version: "main"
permalink: "https://docs.typo3.org/permalink/wegewerk/ai3_core:developer-capability-api@main"
source: "Developer/CapabilityApi.rst"
rendered: "2026-10-23T16:30:49+00:00"
---

# Capability API {#developer-capability-api}

A *capability* is a named AI endpoint that a third-party Ai3 extension
provides. Ai3 Core exposes a **tagged DI compiler pass** so that
capabilities register without code changes in `ai3_core`.

## ZakAiEndpointInterface {#developer-capability-api-interface}

Every capability must implement
`\Wegewerk\Ai3Core\Api\ZakAiEndpointInterface`:

**Classes/Api/ZakAiEndpointInterface.php**

```php
interface ZakAiEndpointInterface
{
    public function generate(array $options = []): string;
}
```

The `generate()` method receives an associative array of options (such
as `text`, `image`, `language`, etc.) and returns the generated
string.

## AbstractZakAiEndpoint {#developer-capability-api-abstract-endpoint}

For most capabilities, extending
`\Wegewerk\Ai3Core\Api\AbstractZakAiEndpoint` is the recommended way
to implement endpoints. It handles required parameter validation,
building the API request payload, sending the POST request via
`ZakAiClient`, and extracting the response key.

Subclasses declare their configuration via protected properties:

| Property | Description |
| --- | --- |
| `string $endpoint` | The API path for the POST request (e.g. `bulletpoints`, `faq`, `alttexts`). |
| `string $responseKey` | The JSON key to extract from the API response. |
| `array $requiredOptions` | List of required option keys (e.g. `['text']` or `['image']`). |
| `array $optionalOptions` | List of optional option keys passed through to the payload if present. |

Payload construction and hooks:

-   **Validation:** `validateRequiredOptions(array $options)` verifies that
    all keys in `$requiredOptions` are present and non-empty.
-   **Payload building:** `buildPayload(array $options)` populates the
    payload directly with all required and present optional option keys.
-   **Preparation hook:** `preparePayload(array $payload, array $options): array`
    allows custom manipulation before sending (e.g. image resizing and base64 encoding).
-   **Result extraction:** `extractResult(array $response): string` extracts
    the `$responseKey` value (converting arrays to JSON if needed).

## Registering a capability {#developer-capability-api-register}

Tag your endpoint service with `ai3.capability` in your extension's
[`Configuration/Services.yaml`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.html#file-extension-configuration-services-yaml). The compiler pass picks up the
`$key`, `$title`, and `$endpoint` constructor arguments
automatically:

**Configuration/Services.yaml (your extension)**

```yaml
MyVendor\MyAiExt\Endpoint\SummaryEndpoint:
    tags:
        - name: ai3.capability
    arguments:
        $key: 'my_ext_summary'
        $title: 'Automatic summary'
        $endpoint: '@MyVendor\MyAiExt\Endpoint\SummaryEndpoint'
```

**Classes/Endpoint/SummaryEndpoint.php**

```php
use Wegewerk\Ai3Core\Api\AbstractZakAiEndpoint;

final class SummaryEndpoint extends AbstractZakAiEndpoint
{
    protected string $endpoint = 'bulletpoints';
    protected string $responseKey = 'bulletpoints';
    protected array $requiredOptions = ['text'];
    protected array $optionalOptions = ['language'];
}
```

## CapabilityRegistry {#developer-capability-registry}

At runtime, all registered capabilities are available via
`\Wegewerk\Ai3Core\Service\CapabilityRegistry`. It is a
`SingletonInterface` and can be injected via constructor:

**Injecting the registry**

```php
use Wegewerk\Ai3Core\Service\CapabilityRegistry;

final class MyService
{
    public function __construct(
        private readonly CapabilityRegistry $capabilityRegistry,
    ) {}

    public function run(string $capabilityKey): string
    {
        $capability = $this->capabilityRegistry
            ->getCapability($capabilityKey);
        if ($capability === null) {
            throw new \RuntimeException(
                'Unknown capability: ' . $capabilityKey,
            );
        }
        return $capability->endpoint->generate([
            'text' => 'Hello',
            'language' => 'en',
        ]);
    }
}
```

## TCA integration {#developer-capability-formengine}

The CapabilityRegistry is used in the `itemsProcFunc` of `capability` in tx_ai3_domain_model_generation_task
:

**TCA column configuration**

```php
'capability' => [
    'label' => 'AI capability',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'itemsProcFunc' =>
            \Wegewerk\Ai3Core\FormEngine\CapabilityItemsProcFunc::class
            . '->itemsProcFunc',
    ],
],
```