Get started

Build a real-time Ojin avatar in minutes, the same flow drives both Human Portrait and Human Presence. 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.

2. Create a custom persona or use a Persona Template.

3. A config_id, the Model Config ID shown on your configuration in the dashboard.

4. Python 3.10 or newer (3.11 or newer for the Pipecat integration).

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

Python SDK

Python SDK

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

pip install "ojin-client[stv]"

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

Full walkthrough → Build with the Python SDK.

Pipecat

Pipecat

Drop an Ojin face into a Pipecat voice agent with the 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:

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.

pip install pipecat-ojin

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.

A complete, runnable voice + avatar agent (browser WebRTC or Daily) lives in pipecat-ojin/examples/ojin-bot. You bring the STT / LLM / TTS services for the pipeline.

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) →.

Next Steps

• Build with the Python SDK →: install, auth, events, and the full quickstart

• API Reference (advanced) →: the raw WebSocket protocol for custom integrations