> For the complete documentation index, see [llms.txt](https://docs.ojin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ojin.ai/models/introduction/integrations.md).

# Get started

Build a real-time **Ojin** avatar in minutes, the same flow drives both [Human Portrait](/models/human-portrait.md) and [Human Presence](/models/human-presence.md). Pick the integration that fits your stack. We recommend the **Python SDK** or **Pipecat**. The raw WebSocket API is there when you need low-level control.

## Prerequisites

1. An Ojin account with an active API key, if you don't have one, [get your API key](/getting-started/authentication.md).
2. [Create a custom persona](/models/introduction/creating-persona.md) or use a [Persona Template](/models/introduction/using-persona-template.md).
3. A `config_id`, the **Model Config ID** shown on your configuration in the [dashboard](https://ojin.ai/dashboard).
4. Python 3.10 or newer (3.11 or newer for the Pipecat integration).

{% hint style="info" %}
**Production deployments:** the realtime transport is a WebSocket for **server-to-server** use over a stable connection. Drive it from a backend server (ideally in **US East**, near Ojin's inference) to keep your API key secure and latency low, then deliver the final media to end users over a transport built for real-time video (typically WebRTC). If your viewers are in a LiveKit or Daily room, [direct WebRTC](/models/build-with-python-sdk/python-sdk-webrtc.md) has Ojin publish the avatar straight into that room, so you don't relay media at all. The Python SDK and Pipecat integration are designed to run server-side.
{% endhint %}

{% tabs %}
{% tab title="Python SDK" %}

### Python SDK

The [`ojin-client`](https://pypi.org/project/ojin-client/) SDK is the fastest way to drive Ojin from your own code. It streams a synchronized talking-avatar video from the TTS audio you feed it.

```bash
pip install "ojin-client[stv]"
```

```python
import os
from ojin.stv import OjinSTVClient

client = OjinSTVClient(
    api_key=os.environ["OJIN_API_KEY"],
    config_id=os.environ["OJIN_CONFIG_ID"],  # your Human Portrait or Human Presence config
)
# await client.start()  # opens the session; constructing the client does not connect
# Feed TTS audio with client.say(...), or start_turn() + send_tts_audio() to stream,
# and consume the synced 25 fps audio + video from client.output_stream().
```

**Viewers in a LiveKit or Daily room?** Pass `webrtc=WebRTCSettings(...)` and Ojin publishes the avatar straight into the room. See [Direct WebRTC (LiveKit & Daily)](/models/build-with-python-sdk/python-sdk-webrtc.md).

**Full walkthrough →** [**Build with the Python SDK**](/models/build-with-python-sdk.md)**.**
{% endtab %}

{% tab title="Pipecat" %}

### Pipecat

Drop an Ojin face into a [Pipecat](https://github.com/pipecat-ai/pipecat) voice agent with the [`pipecat-ojin`](https://pypi.org/project/pipecat-ojin/) package. `OjinVideoService` is the one stage that turns a voice agent into a video-call avatar. It sits right after your TTS and lip-syncs to it:

```mermaid
flowchart LR
    A["transport.input()"] --> B[STT] --> C[LLM] --> D[TTS]
    D --> E["OjinVideoService"]
    E --> F["transport.output()"]

    style E fill:#6366f1,stroke:#4338ca,color:#ffffff
```

`OjinVideoService` is the only stage you add. Everything upstream of it is your existing voice pipeline, unchanged.

Requires **Python 3.11+** (`pipecat-ai`'s floor); the SDK on its own needs only 3.10.

```bash
pip install pipecat-ojin
```

```python
import os

from pipecat_ojin import OjinVideoService, OjinVideoSettings

avatar = OjinVideoService(
    OjinVideoSettings(
        api_key=os.environ["OJIN_API_KEY"],
        config_id=os.environ["OJIN_CONFIG_ID"],   # your Human Portrait or Human Presence config
    )
)
```

The avatar's frame size comes from your model (`config_id`) — set the transport's `video_out_width` / `video_out_height` to match it.

#### How it works

1. The microphone captures speech input
2. Voice Activity Detection identifies speech segments
3. Your **STT** service transcribes user audio to text
4. Your **LLM** generates the assistant's reply
5. Your **TTS** service synthesizes the reply to audio
6. `OjinVideoService` animates your persona from that TTS audio
7. Synchronized video and audio frames stream back to the client in real time

**Using a LiveKit or Daily transport?** Set `webrtc=WebRTCSettings(...)` on `OjinVideoSettings` and Ojin publishes the avatar straight into the room; turn off the transport's `audio_out_enabled` and `video_out_enabled`. See [Direct WebRTC → Pipecat](/models/build-with-python-sdk/python-sdk-webrtc.md#pipecat).

A complete, runnable voice + avatar agent (browser WebRTC or Daily) lives in [`pipecat-ojin/examples/ojin-bot`](https://github.com/ojinai/pipecat-ojin/tree/main/examples/ojin-bot). You bring the STT / LLM / TTS services for the pipeline.
{% endtab %}

{% tab title="WebSocket (advanced)" %}

### WebSocket (advanced)

For low-level control, connect directly to the real-time WebSocket API and implement the binary protocol yourself. See the [API Reference (advanced) →](/models/introduction/api.md).
{% endtab %}
{% endtabs %}

## Next Steps

* [**Build with the Python SDK →**](/models/build-with-python-sdk.md): install, auth, events, and the full quickstart
* [**API Reference (advanced) →**](/models/introduction/api.md): the raw WebSocket protocol for custom integrations
* [**Search your knowledge →**](/apps/overview/knowledge.md#searching-from-your-own-llm): answer from your organization's documents in your own LLM


---

# 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.ojin.ai/models/introduction/integrations.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.