> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phonic

> Use Phonic, a speech-to-speech model, in a Zero Runtime pipeline. Setup and usage in Python.

Phonic is a **speech-to-speech** model. It handles transcription, reasoning, and voice synthesis in a single telephony-tuned model that manages turn-taking and interruptions itself. It goes in the pipeline's `llm` slot with no separate STT or TTS, and the `Pipeline` auto-detects [Realtime mode](https://docs.zeroruntime.ai/runtime-sdk/build/configure-a-pipeline/modes.md) when you pass it.

## Setup

Set your Phonic API key in the worker environment. Generate a key from the [Phonic site](https://phonic.ai/):

```bash theme={null}
export PHONIC_API_KEY=<key>
```

## Usage

Pass the realtime model to the pipeline's `llm` slot, no `stt` or `tts` needed.

```python Python theme={null}
from zeroruntime import Pipeline
from zeroruntime.plugins import PhonicRealtimeConfig, PhonicRealtime

llm = PhonicRealtime(
    config=PhonicRealtimeConfig(
        voice="sabrina",
        welcome_message="Hi, how can I help?",
    ),
)

pipeline = Pipeline(llm=llm)
```

> [!NOTE]
>
> `PhonicRealtime` ships in the Python SDK only. The Node JS SDK does not include this plugin yet.

> [!NOTE]
>
> `PhonicRealtime` requires a `zeroruntime` release newer than 0.1.9.

## Parameters

*Constructor parameters for `PhonicRealtime`.*

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str` | `None` | Phonic API key. Falls back to the `PHONIC_API_KEY` environment variable when unset. |
| `model` | `str \| None` | `None` | Phonic model name, e.g. "phonic-1". None uses Phonic's current default model. |
| `config` | `dict \| None` | `None` | Conversation settings such as voice, languages, welcome message and silence timers. |
| `base_url` | `str \| None` | `None` | WebSocket URL of the Phonic conversations endpoint. |

### `config` keys

`config` takes a `PhonicRealtimeConfig` or a plain dict with the same keys.

| Field | Type | Default | Description |
| - | - | - | - |
| `agent` | `str \| None` | `None` | Name of an agent on the Phonic platform. Your instructions and any field set here override that agent's settings. |
| `project` | `str \| None` | `None` | Phonic project name. Phonic uses 'main' when unset. |
| `voice` | `str \| None` | `None` | Phonic voice ID, e.g. 'sabrina' or 'grant'. |
| `welcome_message` | `str \| None` | `None` | Message Phonic speaks when the conversation starts. |
| `generate_welcome_message` | `bool \| None` | `None` | Have Phonic generate the welcome message instead. |
| `is_welcome_message_interruptible` | `bool \| None` | `None` | Whether the caller can cut the welcome message off. |
| `audio_speed` | `float \| None` | `None` | Playback speed, 0.5 to 1.5. |
| `default_language` | `str \| None` | `None` | ISO 639-1 language code to recognize and speak, e.g. 'en'. |
| `additional_languages` | `list[str] \| None` | `None` | Further ISO 639-1 codes the agent can switch to. |
| `multilingual_mode` | `Literal['auto', 'request', 'initial'] \| None` | `None` | How the language is chosen: 'request', 'auto' or 'initial'. The spelling is Phonic's own. |
| `intelligence_level` | `Literal['standard', 'high'] \| None` | `None` | 'standard' for lower latency, 'high' for harder reasoning. |
| `boosted_keywords` | `list[str] \| None` | `None` | Words to boost in speech recognition. |
| `pronunciation_dictionary` | `list[dict[str, str]] \| None` | `None` | List of `{"word": ..., "pronunciation": ...}` entries. |
| `min_words_to_interrupt` | `int \| None` | `None` | User words needed to interrupt the agent, 1 to 10. |
| `vad_min_silence_duration_ms` | `int \| None` | `None` | Milliseconds of silence that end the user's turn, up to 1500. |
| `vad_threshold` | `float \| None` | `None` | Voice activity threshold, 0.2 to 0.8. |
| `no_input_poke_sec` | `int \| None` | `None` | Seconds of silence before the poke message. |
| `no_input_poke_text` | `str \| None` | `None` | Poke message text. |
| `generate_no_input_poke_text` | `bool \| None` | `None` | Have Phonic generate the poke message instead. |
| `no_input_end_conversation_sec` | `int \| None` | `None` | Seconds of silence before Phonic ends the call and the agent hangs up, 30 to 600. Phonic's default is 180. |
| `enable_assistant_backchannel` | `bool \| None` | `None` | Say 'mm-hmm' while the user is speaking. |
| `template_variables` | `dict[str, str] \| None` | `None` | Values for template variables in the prompt. |
| `tools` | `list[str \| dict[str, Any]] \| None` | `None` | Names of pre-defined or built-in Phonic tools, e.g. 'natural\_conversation\_ending', or built-in tool objects. Function tools come from the agent. |
| `tool_call_output_timeout_ms` | `int` | `60000` | How long Phonic waits for a function tool's result, 1000 to 180000. |
| `stream_ahead_of_real_time` | `bool` | `True` | Receive audio as fast as Phonic generates it and pace it locally, which rides out network jitter. |

To pair the realtime model with an external STT or TTS, see [Hybrid mode](https://docs.zeroruntime.ai/runtime-sdk/build/configure-a-pipeline/modes.md#hybrid). For general plugin concepts, see the [plugins overview](https://docs.zeroruntime.ai/runtime-sdk/plugins/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.