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

# Speech

## 语音模型

语音模型连接了音频和文本两种输入输出形态，既支持**自动语音识别（ASR）**，也支持**文本转语音（TTS）**。两者都通过标准的 Chat Completions 接口（`/chat/completions`）调用，因此可以方便地接入转写流程、语音助手和无障碍工具。

**代表模型：** `bosonai/asr`（语音转文本）、`bosonai/tts`（文本转语音）。完整列表与定价请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza)。

***

### 1. 使用场景

* **转写**：将会议、通话、讲座或语音笔记转换为可检索的文本。
* **语音助手**：结合 ASR、LLM 与 TTS，构建对话式语音体验。
* **字幕与说明文字**：为视频和音频内容生成字幕。
* **无障碍**：朗读内容，或让用户通过语音而非打字进行交互。

***

### 2. 使用方式

这两类模型都通过 `/chat/completions` 接入点和 `messages` 数组调用，与聊天模型的请求方式类似，区别主要在于输入和输出内容：

* **文本转语音（TTS）**：将待朗读文本作为普通用户消息发送。生成的音频会出现在 `choices[0].message.audio.data` 字段中，格式为 base64 编码的 **WAV**；解码后写入文件即可播放。
* **语音转文本（ASR）**：将音频以 `input_audio` 类型的内容片段发送（包含 base64 数据及 `wav` 等 `format` 信息）。转写结果会以纯文本形式返回在 `choices[0].message.content` 中。

支持的音频格式以及最大文件大小或时长因模型而异；请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza) → 模型详情。

***

### 3. 关键参数

* **TTS**：`model`（`bosonai/tts`）以及一条包含待朗读文本的用户 `messages` 条目。音频返回在 `message.audio.data` 下（base64 WAV）。
* **ASR**：`model`（`bosonai/asr`）以及一条用户消息，其 `content` 为包含 `{"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}` 的数组。

***

### 4. 计费与配额

* 语音模型通常按**音频时长**或**处理的字符数/token 数**计费，具体取决于模型。确切的计价单位请查看 [模型广场](https://console.siflow.cn/maas-api/model_plaza) → 模型详情。
* **建议**：对于较长录音，建议先切分为多个片段，再分段处理，以降低超时和重试成本。

***

### 5. 示例

#### 5.1 文本转语音（TTS）

```python theme={null}
import os
import base64
import requests

api_key = os.getenv("API_KEY") or "<YOUR API KEY>"
api_url = "https://api.siflow.cn/model-api/chat/completions"

response = requests.post(
    api_url,
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "model": "bosonai/tts",
        "messages": [
            {"role": "user", "content": "Welcome to the Siflow Model Inference API."}
        ],
    },
)

audio_b64 = response.json()["choices"][0]["message"]["audio"]["data"]
with open("welcome.wav", "wb") as f:
    f.write(base64.b64decode(audio_b64))
print("Saved welcome.wav")
```

#### 5.2 语音转文本（ASR）

```python theme={null}
import os
import base64
import requests

api_key = os.getenv("API_KEY") or "<YOUR API KEY>"
api_url = "https://api.siflow.cn/model-api/chat/completions"

with open("welcome.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    api_url,
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "model": "bosonai/asr",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}}
                ],
            }
        ],
    },
)

print(response.json()["choices"][0]["message"]["content"])
```

***

* 支持的音频格式与大小限制因模型而异；请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza) → 模型详情。
* 对于长音频，将其切分为较短的片段有助于保持在限制范围内并降低超时风险。