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

# 语音集成

> 使用 Theo 的语音 API 为你的应用添加实时语音对话功能。

Theo 的语音系统支持具备语音转文字、文字转语音和实时工具调用能力的实时对话式 AI。语音会话与驱动文本补全的角色、技能和工具是共享的，因此单个 API 密钥即可同时驱动两种界面。

## 工作原理

语音会话是你的客户端与 Theo 语音运行时之间的一个流式连接。你的应用需要：

1. 在浏览器（或设备端）中采集麦克风音频。
2. 向 Theo 请求一个短时效的会话令牌。
3. 使用该令牌打开流式语音连接，并在 Theo 的音频响应到达时进行播放。

Theo 会在该令牌背后处理转录、编排（角色、技能、工具、记忆）以及文字转语音。客户端从不直接与任何上游模型通信——每一次调用都由 Theo 语音运行时进行中转。

## 获取语音令牌

在开始语音会话之前，先请求一个会话令牌：

```bash theme={null}
curl -X POST https://api.hitheo.ai/api/v1/voice/token \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

响应内容包括：

```json theme={null}
{
  "token": "theo_voice_...",
  "expiresAt": "2026-04-16T22:00:00Z",
  "systemInstruction": "…Theo voice persona…",
  "tools": [ { "functionDeclarations": [] } ]
}
```

<Note>
  令牌端点会在返回令牌的同时返回 `systemInstruction` 和 `tools`，这是 Theo 平台的约定契约。你的客户端在打开实时语音连接时必须同时附带这两项——否则会话将在没有 Theo 角色、也没有任何工具访问权限的情况下启动。
</Note>

`systemInstruction` 承载了 Theo 语音角色、平台上下文、运行时协议以及工具使用指引（在存在时还包括记忆和技能上下文）。`tools` 数组包含所有已声明的语音工具（`generate_image`、`generate_video`、`deep_research`、`generate_code`、`generate_document`、`save_memory`），以及任何以 `skill_{slug}_{toolName}` 命名空间标识的已安装技能工具。

语音选择是可选项。可用的语音标识符列在仪表盘的 **Settings → Voice**（设置 → 语音）中。

## 转录（STT）

通过 STT 端点发送音频进行转录：

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/audio/stt \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -F "file=@recording.webm" \
  -F "language=en"
```

返回 `{ "text": "transcribed text" }`。

支持的格式：WebM、MP3、WAV、M4A、OGG。文件大小上限：25MB。

## 文字转语音（TTS）

将文本转换为音频：

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/audio/tts \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello!", "voice": "theo-voice-warm" }' \
  --output response.mp3
```

语音选择是可选项。完整的 Theo 语音标识符列表参见 [TTS 参考文档](/api-reference/audio/text-to-speech)。

## 语音中的技能工具

带有工具定义的 E.V.I. 技能会自动在语音会话中可用。技能桥接层会将每个技能的工具以函数声明的形式暴露给语音运行时：

* 工具名称以 `skill_{slug}_{toolName}` 命名空间标识，以避免冲突。
* 技能清单中声明的输入模式会被转发给语音运行时。
* 当语音会话调用某个技能工具时，Theo 会将其路由到你的技能工具执行器，并将结果回传到实时会话中。

## 语音操作

在实时会话期间，工具可能会在对话轮次中途被触发。Theo 会将这些调用路由到：

```
POST /api/v1/voice/action
```

该端点负责执行工具调用（技能工具、网页搜索、记忆查询、代码生成），并将结果返回给实时会话，供 Theo 将其纳入响应中。

## 示例流程

```
User speaks → WebM audio blob
  → POST /api/v1/audio/stt → "What's the status of my latest order?"
  → Theo voice session (with customer-support skill tools)
  → Voice session calls skill_customer-support_lookup_order tool
  → POST /api/v1/voice/action → tool result
  → Voice session generates response with order status
  → POST /api/v1/audio/tts → audio response
  → Play audio to user
```

## API 参考

* [语音转文字](/api-reference/audio/speech-to-text)
* [文字转语音](/api-reference/audio/text-to-speech)


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