Hakim

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

Overview

HakimTTSService synthesizes speech from text using Hakim’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.

Source Repository

Source code, examples, and issues for the Hakim integration

Hakim Docs

Learn more about Hakim’s speech services

API Keys

Create and manage your Hakim API keys from the dashboard (Settings -> API keys)

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:

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
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

voice · str · required

Hakim voice id or slug. Required — there is no bundled default voice.

api_key · str · default: "None"

Hakim API key. Falls back to the HAKIM_API_KEY environment variable if not provided.

model · 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).

cfg · float · default: "3.0"

Classifier-free-guidance weight, 0.0-10.0.

voice_prompt · str · default: "None"

Free-form voice-character description. Only honoured on model="hakim-v3" — dropped elsewhere.

region · str · default: "auto"

Pins the session to a specific regional endpoint. One of "auto", "de", "uae", or "ksa".

base_url · str · default: "None"

Overrides the region table entirely (staging / self-hosted). Takes precedence over region.

settings · HakimTTSService.Settings · default: "None"

Runtime-updatable settings. See Settings below.

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".

See the source repository for the authoritative, up-to-date configuration options.

Usage

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 for the latest tested version and changelog.