Agentic 语音：VoiceStudio 作为 TTS/STT 提供商¶

VoiceStudio 提供了一个本地语音平台——兼容 OpenAI 的批量音频、带版本化的转录 WebSocket，以及 MCP——因此任何能与 OpenAI 音频端点对接的智能体框架，都可以使用你的本地 VoiceStudio 来完成语音——并且使用你克隆的声音，一切都不会离开你的机器。你提供智能体运行时；VoiceStudio 负责语音。

若要直接口述到 Claude Code、Codex、Pi、Antigravity CLI 或其他专注型 prompt，请使用应用的听写快捷键；流式 API 见本地语音平台。

这是“agentic v1”：VoiceStudio 是提供商，而非编排器。你接入自己的智能体（支持热线、桌面助手、Discord 角色），并将其 TTS/STT 指向 VoiceStudio。

范围。 本页介绍 VoiceStudio 作为提供商的用法。外呼电话是一个单独且推迟的里程碑（它们需要付费运营商——不存在完全本地的 PSTN 路径），并且只在明确的同意护栏之后推出。路线图见 docs/competitive-analysis.md（§R1）。接听来电并播放语音问候可作为可选集成：见 Twilio。

端点¶

VoiceStudio 的服务根地址是 http://localhost:3900（或你的远程后端 URL）。兼容 OpenAI 的客户端使用 http://localhost:3900/v1 作为其基础 URL，而发现端点仍位于服务根地址：http://localhost:3900/.well-known/voicestudio-speech。

语音 response_format 会精确返回所请求的格式：

mp3、opus 和 aac 使用 ffmpeg（随 VoiceStudio 捆绑）编码。如果找不到 ffmpeg，请求会在生成任何音频之前以 400 失败，并指明修复方法；wav、flac 和 pcm 不需要编码器。

这些路由上的错误使用 OpenAI 的错误结构——{"error": {"message", "type", "param", "code"}}——因此 SDK 会抛出带可读消息的类型化异常。与 OpenAI 一样，无效请求返回 400。响应体还会保留现有 VoiceStudio 客户端读取的 detail 字段。

契约测试在 CI 中锁定这一接口：tests/test_agentic_provider_contract.py（pipecat/LiveKit 请求形态）和 tests/test_openai_sdk_contract.py（通过官方 openai SDK 驱动每个路由）。

pipecat（推荐）¶

pipecat（BSD-2）作为 Python 库运行在你自己的进程中——无需额外服务器。将其 OpenAI TTS/STT 服务指向 VoiceStudio：

from pipecat.services.openai.tts import OpenAITTSService
from pipecat.services.openai.stt import OpenAISTTService

tts = OpenAITTSService(
    base_url="http://localhost:3900/v1",
    api_key="not-needed-locally",        # any string; VoiceStudio ignores it unless OMNIVOICE_API_KEY is set
    voice="<your-voice-profile-id>",     # or its name; see GET /v1/audio/voices, or "default"
    model="omnivoice",                   # or any installed engine id
    sample_rate=24000,                   # matches VoiceStudio's default output
)

stt = OpenAISTTService(
    base_url="http://localhost:3900/v1",
    api_key="not-needed-locally",
)

将这两个服务放入任何 pipecat 流水线（VAD、轮流发言和 LLM 也都保持在本地）。可运行的最小示例见 examples/agentic/pipecat_minimal.py。

LiveKit Agents¶

LiveKit Agents（Apache-2.0）还需要一个 LiveKit 媒体服务器与它配套，但其 OpenAI 插件接受同样的 base_url：

from livekit.plugins import openai

tts = openai.TTS(base_url="http://localhost:3900/v1", api_key="x", voice="<profile-id>")
stt = openai.STT(base_url="http://localhost:3900/v1", api_key="x")

只有在需要 WebRTC/SIP 这种规模能力时，才选择 LiveKit 而不是 pipecat；对于 单个本地智能体，pipecat 更轻量。

OpenAI Agents SDK¶

OpenAI Agents SDK 的语音管道需要一个 OpenAI 客户端，因此请为它提供一个指向 VoiceStudio 的客户端。 其默认模型（gpt-4o-transcribe、gpt-4o-mini-tts）、默认声音以及 24 kHz PCM 输出都可以原样使用。Integrations 下的 OpenAI Agents 页面 会显示这个代码片段，并已为你填入后端地址：

import os

from agents import Agent, OpenAIChatCompletionsModel, set_tracing_disabled
from agents.voice import (
    OpenAIVoiceModelProvider, SingleAgentVoiceWorkflow, STTModelSettings,
    TTSModelSettings, VoicePipeline, VoicePipelineConfig,
)
from openai import AsyncOpenAI

set_tracing_disabled(True)  # the SDK uploads traces to OpenAI by default

voicestudio = AsyncOpenAI(
    base_url="http://localhost:3900/v1",
    api_key=os.environ.get("OMNIVOICE_API_KEY", "not-needed-locally"),
)
# The agent's language model: a local OpenAI-compatible server you choose.
llm = AsyncOpenAI(
    base_url=os.environ["AGENT_LLM_BASE_URL"],  # e.g. Ollama: http://localhost:11434/v1
    api_key=os.environ.get("AGENT_LLM_API_KEY", "not-needed-locally"),
)
agent = Agent(
    name="Assistant",
    instructions="Be brief.",
    model=OpenAIChatCompletionsModel(model=os.environ["AGENT_LLM_MODEL"], openai_client=llm),
)

pipeline = VoicePipeline(
    workflow=SingleAgentVoiceWorkflow(agent),
    stt_model="gpt-4o-transcribe",   # VoiceStudio's active speech-recognition engine
    tts_model="gpt-4o-mini-tts",     # VoiceStudio's active voice engine
    config=VoicePipelineConfig(
        model_provider=OpenAIVoiceModelProvider(openai_client=voicestudio),
        stt_settings=STTModelSettings(language="en"),
        tts_settings=TTSModelSettings(voice="alloy"),  # or a voice-profile id or name
    ),
)

SDK 会为 TTSModelSettings.instructions 发送一段默认的自然语言文本；支持 自由文本指令的引擎会遵循它，而 OmniVoice 会忽略它。设置 instructions="female, whisper" 这类标签即可引导 OmniVoice。

智能体的语言模型是显式指定的：将 AGENT_LLM_BASE_URL 和 AGENT_LLM_MODEL 设置为本地 OpenAI 兼容服务器（Ollama、LM Studio、 llama.cpp、vLLM）。如果未设置这些变量，代码片段会快速失败，而不会回退到 OpenAI 的托管模型。输入模式同样由你决定——使用 AudioInput（ 录制的语音回合）。StreamedAudioInput 需要 OpenAI 的 Realtime 转录 WebSocket，而 VoiceStudio 没有实现它。

远程后端¶

在远程 GPU 机器上运行 VoiceStudio？请将 /v1 附加到该 后端服务根 URL 的末尾，作为 OpenAI 客户端的 base_url，并把它的 OMNIVOICE_API_KEY 作为 api_key 传入——这也是应用其余部分所使用的同一个 Bearer 令牌。 只应通过 https（例如 Tailscale Serve）发送该密钥；通过普通 http 发送时， 它会以明文在网络中传输。 保留未修改的服务根 URL，以用于 /.well-known/voicestudio-speech 发现，并让后端保持在你的 tailnet 内，而不要暴露到公网。

负责任地使用你的声音¶

当智能体用克隆声音说话时，请优先选择你已标记为 verified own voice （设置 → 声音档案 → Voice ownership）的档案。那道同意锁是在更重量级的 智能体功能陆续落地时用于控制访问的机制，也是“有一个 AI 正在以我的身份说话”时 诚实合理的默认要求。