> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-improve-self-hosting-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hakim

> Text-to-speech service implementation using Hakim's Arabic-first realtime synthesis API

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="tryHakimAI" maintainerUrl="https://github.com/tryHakimAI" repo="https://github.com/tryHakimAI/hakim-pipecat" />

## Overview

`HakimTTSService` synthesizes speech from text using [Hakim](https://tryhakim.ai)'s
Arabic-first realtime text-to-speech API. It subclasses `InterruptibleTTSService`
(Hakim's realtime TTS has no mid-utterance cancel message and no word-level
timestamps, so interruption is handled by reconnecting rather than sending a cancel
frame) and opens one persistent connection to `WSS /v1/audio/speech/stream` -- each
sentence Pipecat sends to `run_tts` becomes one `speech.create` request on the same
socket, with no new TCP/TLS handshake per utterance.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/tryHakimAI/hakim-pipecat">
    Source code, examples, and issues for the Hakim integration
  </Card>

  <Card title="Hakim Docs" icon="book" href="https://tryhakim.ai/docs">
    Learn more about Hakim's speech services
  </Card>

  <Card title="API Keys" icon="key" href="https://tryhakim.ai">
    Create and manage your Hakim API keys from the dashboard (Settings -> API keys)
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`,
built and maintained by the Hakim team. It is not yet published to PyPI, so install
it directly from GitHub:

```bash theme={null}
uv pip install git+https://github.com/tryHakimAI/hakim-pipecat.git
```

## Prerequisites

### Hakim Account Setup

Before using the Hakim TTS service, you need:

1. **Hakim Account**: Sign up at [tryhakim.ai](https://tryhakim.ai)
2. **API Key**: Generate a key (format: `hk_live_...`) from the dashboard
   (Settings -> API keys), with the `tts:write` scope
3. **A voice**: pick a voice id or slug from the dashboard's Voices page

### Required Environment Variables

* `HAKIM_API_KEY`: Your Hakim API key. Falls back to this environment variable if
  `api_key` is not passed to the constructor.

## Configuration

<ParamField path="voice" type="str" required>
  Hakim voice id or slug. Required -- there is no bundled default voice.
</ParamField>

<ParamField path="api_key" type="str" default="None">
  Hakim API key. Falls back to the `HAKIM_API_KEY` environment variable if not
  provided.
</ParamField>

<ParamField path="model" type="str" default="hakim-fast-v1">
  One of `"hakim-fast-v1"` (sub-120ms TTFB), `"hakim-v2"` (higher quality +
  non-verbal tags), or `"hakim-v3"` (adds free-form `voice_prompt` control).
</ParamField>

<ParamField path="cfg" type="float" default="3.0">
  Classifier-free-guidance weight, `0.0`-`10.0`.
</ParamField>

<ParamField path="voice_prompt" type="str" default="None">
  Free-form voice-character description. Only honoured on `model="hakim-v3"` --
  dropped elsewhere.
</ParamField>

<ParamField path="region" type="str" default="auto">
  Pins the session to a specific regional endpoint. One of `"auto"`, `"de"`,
  `"uae"`, or `"ksa"`.
</ParamField>

<ParamField path="base_url" type="str" default="None">
  Overrides the region table entirely (staging / self-hosted). Takes precedence
  over `region`.
</ParamField>

<ParamField path="settings" type="HakimTTSService.Settings" default="None">
  Runtime-updatable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-updatable configuration passed via the `settings` constructor argument
using `HakimTTSService.Settings(...)`.

| Parameter      | Type    | Default | Description                                                                 |
| -------------- | ------- | ------- | --------------------------------------------------------------------------- |
| `cfg`          | `float` | `3.0`   | Classifier-free-guidance weight, `0.0`-`10.0`.                              |
| `voice_prompt` | `str`   | `None`  | Free-form voice-character description. Only honoured on `model="hakim-v3"`. |

<Note>
  See the [source
  repository](https://github.com/tryHakimAI/hakim-pipecat) for the
  authoritative, up-to-date configuration options.
</Note>

## Usage

```python theme={null}
import os
from pipecat.pipeline.pipeline import Pipeline
from hakim_pipecat import HakimTTSService

tts = HakimTTSService(
    api_key=os.getenv("HAKIM_API_KEY"),
    voice="your-voice-id",
)

pipeline = Pipeline([
    transport.input(),               # audio/user input
    stt,                              # speech to text
    context_aggregator.user(),        # add user text to context
    llm,                              # LLM generates response
    tts,                               # Hakim TTS synthesis
    transport.output(),               # stream audio back to user
    context_aggregator.assistant(),   # store assistant response
])
```

## Compatibility

Tested with Pipecat v1.5.0. Check the [source
repository](https://github.com/tryHakimAI/hakim-pipecat) for the latest tested
version and changelog.