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