第9章 Python SDK——实时说话头像开发指南
完整文档索引请参阅 llms.txt。此页同样提供 Markdown 版本。
Python SDK
直接从 Python 调用 Ojin 的人脸模型（Human Presence 与 Human Portrait）。输入 TTS 音频，即可获取同步、唇形匹配的说话头像流。
ojin-client SDK 是为 Python 应用或语音智能体实时添加说话头像的最快方式。你只需提供文本（任何 TTS 生成的音频），SDK 会回传一个口型完美同步的说话人脸，并自动处理缓冲、播放时钟、重采样以及抢话（barge-in）。
如果想要一个完整的智能体？如果不希望自行搭建流水线，Human Agent 可以通过单行嵌入代码提供一个完整的语音输入、语音输出的头像。已经在用 Pipecat？直接跳转到 Pipecat 集成部分。
环境要求
- Python 3.10+
- Ojin API 密钥（获取链接在此）
- 人脸模型配置 ID，即来自仪表盘的 Presence 或 Portrait 配置
新账户将获得 10 美元免费额度。
安装
使用 uv（推荐）：
uv add "ojin-client[stv]"
或者使用 pip：
pip install "ojin-client[stv]"
附加项 [stv] 会引入语音转视频辅助依赖（numpy, opencv-python-headless, soxr），自动处理重采样、解码及同步计算。
身份验证
客户端需要 API 密钥和配置 ID。请避免在源码中硬编码，建议从环境变量读取：
或者让 SDK 自动加载并校验。resolve_credentials() 会读取可选的 .env 文件，如果缺失任一值将抛出明确错误：
默认情况下，客户端连接至 wss://models.ojin.ai/realtime。
切勿在源码中硬编码 API 密钥或将其提交到版本控制系统。
选择模型
SDK 对两种人脸模型均使用相同的接口；传入的 config_id 决定了实际运行的模型。
| config_id 来源... | 你获得... | 适用场景 |
|---|---|---|
| Human Presence 配置 | 旗舰级、高表现力的生成式 Presence，具备丰富的表情和自然的动作 | 质量与表现力最重要 |
| Human Portrait 配置 | 高性价比、实时唇形匹配的说话脸 | 以最优价格获得出色的说话脸效果 |
在仪表盘创建配置。无论选择哪种，下方的代码相同，仅 config_id 不同。
两种客户端，同一软件包
| OjinSTVClient (高级) | OjinClient (低级) |
|---|---|
导入：from ojin.stv import OjinSTVClient |
导入：from ojin.ojin_client import OjinClient |
| 输入：任意采样率的 TTS 音频 | 输入：16 kHz 单声道 int16 PCM |
| 输出：基于 25 fps 时钟的同步 STVAudioFrame + STVVideoFrame | 输出：原始协议消息（JPEG + PCM） |
| 处理：缓冲、播放时钟、重采样、抢话重同步 | 处理：仅 WebSocket + 线协议 |
大多数应用应使用 OjinSTVClient。仅在编写自己的播放/同步层时，才使用 OjinClient。
选择头像到达观众的方式。默认 OjinSTVClient 通过 WebSocket 将帧回传至你的进程。如果观众位于 LiveKit 或 Daily 房间，请传入 webrtc=WebRTCSettings(...)，Ojin 将直接把头像发布到该房间。参见“直接 WebRTC (LiveKit & Daily)”。
快速入门
给头像输入一段 TTS 音频，然后消费其回传的同步流。
say() 是 start_turn() + send_tts_audio() 的一次性辅助函数。对于实时智能体，每句语音调用一次 start_turn()，并在 TTS 生成片段时通过 send_tts_audio() 流式发送。用户听到的是你发送的确切音频，且与头像唇形同步。
SDK 会自动调整输入格式。可以按照 TTS 生成的节奏输入音频，即使是很小的 40 ms 片段也可以。OjinSTVClient 会自动批处理音频；无需收集几秒后再发送。TTS 或网络的暂停仍可能中断播放。它还会将 output_stream() 控制在实时 25 fps，且音视频已同步。你无需管理输入缓冲、播放时钟或丢帧。关于推荐的初始音频量及调优方法，参见“优化性能”。
常用事件
使用 @client.on(STVEvent.X) 或 client.add_listener(STVEvent.X, cb) 注册处理器。处理器可以是同步或异步的；处理器失败不会破坏播放循环。
| 事件 | 触发时机 |
|---|---|
| SESSION_READY | 会话已就绪，可接受音频 |
| FIRST_FRAME | 第一个头像帧发出 (frame_type) |
| WEBRTC_CONNECTED | 仅限直接 WebRTC：头像已加入你的房间 (participant_id) |
| BOT_STARTED_SPEAKING | 一轮对话的第一个语音帧被播放 |
| BOT_STOPPED_SPEAKING | 一轮对话播放结束 |
| INTERRUPTED | interrupt() 生效（检查其返回值以确定是否实际发送了服务端取消） |
| ERROR | 发生传输或服务端错误 |
| CLOSED | 会话已关闭 |
下一步
可运行示例：
实时流媒体及渲染为 MP4，可直接克隆。
构建语音智能体：
将头像放入 Pipecat 流水线。
直接 WebRTC：
将头像直接发布到 LiveKit 或 Daily 房间。
最佳实践：适用于浏览器输出、WebRTC 后端和直接 WebRTC 的流水线模式
选择人脸模型：Human Presence（旗舰版）或 Human Portrait（高性价比）
调优延迟与稳定性：参考“优化性能”及故障排除指南
完整 API 表面：完整的客户端参考位于 ojin-client README 及 PyPI
入门示例：02-realtime-speech-to-video（实时流）和 01-speech-to-video-mp4-generator（渲染至文件）
上一篇 最佳实践
下一篇 最佳实践
最后更新于 12 天前
有帮助吗？
