# 音频质量检测
Source: https://docs.senseaudio.cn/api-reference/endpoint/asr/analysis

api-reference/endpoint/asr/analysis.openapi.json POST /v1/audio/analysis
检测音频质量与噪声情况

## 说明

检测音频质量与噪声情况，帮助筛选或评估原始音频文件的质量。

* **接口地址**：`https://api.senseaudio.cn/v1/audio/analysis`
* **Content-Type**：`multipart/form-data`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)

## Authorizations

<ParamField type="string">
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`。
</ParamField>

## Body

<Note>`multipart/form-data`</Note>

<ParamField type="file">
  音频文件。
</ParamField>

<ParamField type="string">
  模型名称。目前仅支持 `senseaudio-asr-check-1.5-260319`。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="audio_info" type="object">
  音频信息。

  <Expandable title="child attributes">
    <ResponseField name="audio_info.duration" type="integer">
      音频时长（ms）。
    </ResponseField>

    <ResponseField name="audio_info.format" type="string">
      音频格式。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="result" type="object">
  检测结果。

  <Expandable title="child attributes">
    <ResponseField name="result.has_noise" type="boolean">
      是否有噪声。
    </ResponseField>

    <ResponseField name="result.noise_score" type="number">
      噪声评分。
    </ResponseField>

    <ResponseField name="result.severity" type="string">
      严重程度。
    </ResponseField>

    <ResponseField name="result.noise_types" type="string[]">
      噪声类型列表。
    </ResponseField>

    <ResponseField name="result.analysis" type="string">
      分析结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 相关指南

* [语音识别介绍](/guides/asr/overview)
* [语音识别转写](/api-reference/endpoint/asr/transcriptions)
* [计费说明](/guides/account/billing)


# 语音识别历史
Source: https://docs.senseaudio.cn/api-reference/endpoint/asr/records

api-reference/endpoint/asr/records.openapi.json GET /v1/audio/records
查询语音识别历史记录，支持按会话或 API Key 过滤

## 说明

获取语音识别历史，支持按会话 ID 或 API Key 过滤。历史最长保存 7 天（按会话结束时间计）。

* **接口地址**：`https://api.senseaudio.cn/v1/audio/records`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)

## Authorizations

<ParamField type="string">
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`。
</ParamField>

## Query parameters

<ParamField type="integer">
  页数。
</ParamField>

<ParamField type="integer">
  分页大小。
</ParamField>

<ParamField type="string">
  按会话 ID 筛选。
</ParamField>

<ParamField type="string">
  按 API Key 筛选。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="total" type="integer">
  调用记录总数。
</ResponseField>

<ResponseField name="list" type="object[]">
  查询得到的调用记录数据。

  <Expandable title="child attributes">
    <ResponseField name="list.api_key" type="string">
      此调用记录使用的 API Key。
    </ResponseField>

    <ResponseField name="list.audio" type="string">
      调用记录的音频文件 URL，格式为 PCM s16le，采样率与声道数依据此次会话的控制信息。
    </ResponseField>

    <ResponseField name="list.points" type="integer">
      此次调用消耗的积分。
    </ResponseField>

    <ResponseField name="list.session_id" type="string">
      会话 ID。
    </ResponseField>

    <ResponseField name="list.session_start" type="integer">
      会话开始时间，UNIX 时间戳。
    </ResponseField>

    <ResponseField name="list.session_end" type="integer">
      会话结束时间，UNIX 时间戳。
    </ResponseField>

    <ResponseField name="list.text" type="string">
      识别出的文本。
    </ResponseField>
  </Expandable>
</ResponseField>

## 相关指南

* [语音识别介绍](/guides/asr/overview)
* [语音识别转写](/api-reference/endpoint/asr/transcriptions)
* [计费说明](/guides/account/billing)


# 语音识别转写
Source: https://docs.senseaudio.cn/api-reference/endpoint/asr/transcriptions

api-reference/endpoint/asr/transcriptions.openapi.json POST /v1/audio/transcriptions
音频文件转写，支持多种 ASR 模型

## 说明

基于 HTTP 协议的语音识别服务，兼容 OpenAI Audio API 风格，便于从现有系统迁移。

* **接口地址**：`https://api.senseaudio.cn/v1/audio/transcriptions`
* **Content-Type**：`multipart/form-data`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **模型矩阵**：Lite / Standard / Pro / DeepThink，能力差异详见 [语音识别介绍](/guides/asr/overview#模型对比)
* **实时识别**：低延迟场景请使用 [WebSocket 实时识别](/api-reference/endpoint/asr/websocket)

## Authorizations

<ParamField type="string">
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`，其中 `SENSEAUDIO_API_KEY` 为您的 API Key。
</ParamField>

## Body

<Note>`multipart/form-data`</Note>

<ParamField type="file">
  音频文件（wav / mp3 / ogg / flac / aac / m4a / mp4 等），≤ 10 MB。
</ParamField>

<ParamField type="string">
  模型名称。可选值：`senseaudio-asr-lite-1.5-260319`、`senseaudio-asr-1.5-260319`、`senseaudio-asr-pro-1.5-260319`、`senseaudio-asr-deepthink-1.5-260319`。
</ParamField>

<ParamField type="string">
  音频内容语言代码（ISO-639-1，部分 ISO-639-3），如 `zh` / `en` / `ja`；不设置则自动检测。
</ParamField>

<ParamField type="string">
  响应格式：`json` / `text` / `verbose_json`。
</ParamField>

<ParamField type="boolean">
  是否流式返回（lite 不支持）。
</ParamField>

<ParamField type="boolean">
  自动标点（仅 asr / pro，deepthink 静默忽略）。
</ParamField>

<ParamField type="boolean">
  说话人分离（仅 asr / pro）。
</ParamField>

<ParamField type="integer">
  最大说话人数 1–20，配合说话人分离使用（仅 asr-pro 支持）。
</ParamField>

<ParamField type="string[]">
  时间戳粒度：`word` = 字级 / `segment` = 句级（仅 asr / pro）。
</ParamField>

<ParamField type="string">
  翻译目标语言代码（lite 不支持，pro / deepthink 支持）。
</ParamField>

<ParamField type="string">
  热词增强，英文逗号分隔（仅 lite）。
</ParamField>

<ParamField type="string">
  识别模式：`auto` / `record_only`（仅 deepthink 流式模式生效）。
</ParamField>

<ParamField type="boolean">
  缩写词自动替换。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="text" type="string">
  识别出的文本内容（所有 `response_format` 均返回）。
</ResponseField>

<ResponseField name="duration" type="number">
  音频时长（秒），`verbose_json` 下返回。
</ResponseField>

<ResponseField name="audio_info" type="object">
  音频元信息，`verbose_json` / 流式下返回。

  <Expandable title="child attributes">
    <ResponseField name="audio_info.duration" type="integer">
      音频时长（ms）。
    </ResponseField>

    <ResponseField name="audio_info.format" type="string">
      音频格式。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="segments" type="object[]">
  分段结果（需 `response_format=verbose_json` 或 `timestamp_granularities[]=segment`）。

  <Expandable title="child attributes">
    <ResponseField name="segments.id" type="integer">
      分段索引。
    </ResponseField>

    <ResponseField name="segments.start" type="number">
      起始时间（秒）。
    </ResponseField>

    <ResponseField name="segments.end" type="number">
      结束时间（秒）。
    </ResponseField>

    <ResponseField name="segments.text" type="string">
      本段识别文本。
    </ResponseField>

    <ResponseField name="segments.speaker" type="string">
      说话人标识，需开启 `enable_speaker_diarization`。
    </ResponseField>

    <ResponseField name="segments.translation" type="string">
      翻译结果，需设置 `target_language`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="words" type="object[]">
  字级结果，需设置 `timestamp_granularities[]=word`。

  <Expandable title="child attributes">
    <ResponseField name="words.word" type="string">
      字符。
    </ResponseField>

    <ResponseField name="words.start" type="number">
      起始时间（秒）。
    </ResponseField>

    <ResponseField name="words.end" type="number">
      结束时间（秒）。
    </ResponseField>
  </Expandable>
</ResponseField>

## 响应格式详解

### JSON（默认）

```json theme={null}
{ "text": "识别出的文本内容" }
```

### Text

纯文本，`Content-Type: text/plain`。

```text theme={null}
识别出的文本内容
```

### Verbose JSON

```json theme={null}
{
  "text": "道可道非常道",
  "duration": 2.1,
  "audio_info": { "duration": 5230, "format": "wav" },
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 2.0,
      "text": "道可道非常道",
      "speaker": "speaker_0",
      "translation": "Translated"
    }
  ],
  "words": [
    { "word": "道", "start": 0.27, "end": 0.51 },
    { "word": "可", "start": 0.57, "end": 0.81 }
  ]
}
```

### 流式响应 (SSE)

`Content-Type: text/event-stream`

```text theme={null}
data: {"delta": {"text": "增量文本"}, "finish_reason": null}
data: {"delta": {"text": "。"}, "finish_reason": "stop", "audio_info": {...}}
data: [DONE]
```

| 字段              | 说明                                   |
| :-------------- | :----------------------------------- |
| `delta.text`    | 本次返回的增量文本                            |
| `finish_reason` | `null`（进行中）/ `stop`（完成）/ `error`（错误） |

## 语言支持

`language` 用于指定音频内容的语言（留空则自动检测）；`target_language` 将识别结果翻译为另一语言。

### 各模型参数支持

| 模型                                    | `language` | `target_language` |
| :------------------------------------ | :--------: | :---------------: |
| `senseaudio-asr-lite-1.5-260319`      |      ✅     |         ❌         |
| `senseaudio-asr-1.5-260319`           |      ✅     |         ❌         |
| `senseaudio-asr-pro-1.5-260319`       |      ✅     |         ✅         |
| `senseaudio-asr-deepthink-1.5-260319` |      ✅     |         ✅         |

<Warning>
  部分模型仅支持 `language` 或 `target_language`，请以上表为准。
</Warning>

### senseaudio-asr-lite-1.5-260319 支持语种

| 代码         | 语言    | 代码   | 语言    | 代码    | 语言     |
| :--------- | :---- | :--- | :---- | :---- | :----- |
| `zh`       | 中文    | `en` | 英文    | `yue` | 粤语     |
| `ja`       | 日文    | `ko` | 韩文    | `vi`  | 越南语    |
| `id`       | 印尼语   | `th` | 泰语    | `ms`  | 马来语    |
| `tl`/`fil` | 菲律宾语  | `ar` | 阿拉伯语  | `hi`  | 印地语    |
| `bg`       | 保加利亚语 | `hr` | 克罗地亚语 | `cs`  | 捷克语    |
| `da`       | 丹麦语   | `nl` | 荷兰语   | `et`  | 爱沙尼亚语  |
| `fi`       | 芬兰语   | `el` | 希腊语   | `hu`  | 匈牙利语   |
| `ga`       | 爱尔兰语  | `lv` | 拉脱维亚语 | `lt`  | 立陶宛语   |
| `mt`       | 马耳他语  | `pl` | 波兰语   | `pt`  | 葡萄牙语   |
| `ro`       | 罗马尼亚语 | `sk` | 斯洛伐克语 | `sl`  | 斯洛文尼亚语 |
| `sv`       | 瑞典语   |      |       |       |        |

### senseaudio-asr-1.5-260319 / senseaudio-asr-pro-1.5-260319 支持语种

| 代码   | 语言   | 代码    | 语言   | 代码   | 语言   |
| :--- | :--- | :---- | :--- | :--- | :--- |
| `ar` | 阿拉伯语 | `yue` | 粤语   | `zh` | 中文   |
| `nl` | 荷兰语  | `en`  | 英文   | `fr` | 法语   |
| `de` | 德语   | `id`  | 印尼语  | `it` | 意大利语 |
| `ja` | 日文   | `ko`  | 韩文   | `ms` | 马来语  |
| `pt` | 葡萄牙语 | `ru`  | 俄语   | `es` | 西班牙语 |
| `th` | 泰语   | `tr`  | 土耳其语 | `ur` | 乌尔都语 |
| `vi` | 越南语  |       |      |      |      |

### senseaudio-asr-deepthink-1.5-260319 支持语种

同 `senseaudio-asr-1.5-260319` / `senseaudio-asr-pro-1.5-260319` 表，用于翻译输出。

## 各模型调用示例

### senseaudio-asr-lite-1.5-260319

轻量级模型。**热词增强示例**：

```bash theme={null}
curl https://api.senseaudio.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -F file="@meeting.wav" \
  -F model="senseaudio-asr-lite-1.5-260319" \
  -F language="zh" \
  -F hotwords="张三,李四,项目Alpha,季度复盘"
```

```json theme={null}
{ "text": "张三和李四负责项目Alpha的季度复盘工作" }
```

### senseaudio-asr-1.5-260319

标准模型。**字级 / 句级时间戳示例**：

```bash theme={null}
curl https://api.senseaudio.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -F file="@interview.wav" \
  -F model="senseaudio-asr-1.5-260319" \
  -F response_format="verbose_json" \
  -F "timestamp_granularities[]=word"
```

### senseaudio-asr-pro-1.5-260319

专业版。**说话人分离 + 字级时间戳 + 翻译**：

```bash theme={null}
curl https://api.senseaudio.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -F file="@meeting.wav" \
  -F model="senseaudio-asr-pro-1.5-260319" \
  -F response_format="verbose_json" \
  -F enable_speaker_diarization="true" \
  -F max_speakers="4" \
  -F "timestamp_granularities[]=word" \
  -F target_language="en"
```

### senseaudio-asr-deepthink-1.5-260319

深度理解模型。**翻译示例**：

```bash theme={null}
curl https://api.senseaudio.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -F file="@complex_audio.mp3" \
  -F model="senseaudio-asr-deepthink-1.5-260319" \
  -F target_language="en"
```

```json theme={null}
{ "text": "The weather is nice today, suitable for going out for a walk." }
```

## 错误处理

错误时返回非 200 状态码，响应体：

```json theme={null}
{
  "code": "invalid",
  "message": "file is required"
}
```

| HTTP | `code`             | 说明     |
| :--- | :----------------- | :----- |
| 400  | `invalid`          | 参数错误   |
| 429  | `rate_limit_error` | 请求频率过高 |
| 500  | `internal_error`   | 服务端错误  |

## 相关指南

* [语音识别介绍](/guides/asr/overview)
* [WebSocket 实时识别](/api-reference/endpoint/asr/websocket)
* [音频质量检测](/api-reference/endpoint/asr/analysis)
* [语音识别历史](/api-reference/endpoint/asr/records)
* [计费说明](/guides/account/billing)


# 语音识别 WebSocket (ASR)
Source: https://docs.senseaudio.cn/api-reference/endpoint/asr/websocket

基于 WebSocket 的实时 ASR 识别协议参考

## 说明

基于 WebSocket 的流式语音转文字接口，支持边录边转的实时交互，适用于实时字幕、语音助手、跨语言翻译、语音听写等低延迟场景。通信包含 JSON 控制消息与二进制音频消息两类。

* **接入地址**：`wss://api.senseaudio.cn/ws/v1/audio/transcriptions`
* **鉴权方式**：Bearer Token，格式 `Authorization: Bearer SENSEAUDIO_API_KEY`
* **音频格式**：PCM signed 16-bit little-endian，采样率 16000Hz，单声道
* **模型参数**：目前仅支持 `senseaudio-asr-deepthink-1.5-260319`
* **计费单位**：按音频时长计费，详见 [计费说明](/guides/account/billing)
* **离线转写**：文件批量转写请使用 [语音识别转写](/api-reference/endpoint/asr/transcriptions)

<Warning>
  - 音频必须为 **PCM 16-bit little-endian / 16kHz / 单声道**；其他采样率、格式、声道当前不支持。
  - 控制消息必须以 **JSON 文本帧** 发送，音频数据必须以 **二进制帧** 发送。
  - 客户端需等待 `connected_success` 后再发送 `task_start`，等待 `task_started` 后再开始推送音频。
</Warning>

## 请求头 (Request Headers)

| 参数名               | 必填 | 说明                                      | 示例                  |
| :---------------- | :- | :-------------------------------------- | :------------------ |
| **Authorization** | 是  | 鉴权 Token。格式：Bearer SENSEAUDIO\_API\_KEY | Bearer sk-123456... |

***

## 通信流程

```
1. 客户端建立 WebSocket 连接
   ↓
2. 服务端返回 connected_success 事件
   ↓
3. 客户端发送 task_start 事件（包含音频参数、VAD、识别配置）
   ↓
4. 服务端返回 task_started 事件
   ↓
5. 客户端持续发送二进制音频帧
   ↓
6. 服务端在 VAD 断句后返回 result_final 事件（可多次）
   ↓
7. 客户端发送 task_finish 事件
   ↓
8. 服务端返回 task_finished 事件并关闭连接
```

```mermaid theme={null}
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端

    Note over Client, Server: 1. 建立连接
    Client->>Server: WebSocket Connect (带 Auth Header)
    Server-->>Client: JSON: {"event": "connected_success", ...}

    Note over Client, Server: 2. 开启任务
    Client->>Server: JSON: {"event": "task_start", "model": "...", "audio_setting": {...}}
    Server-->>Client: JSON: {"event": "task_started", ...}

    Note over Client, Server: 3. 音频流传输 (循环)
    loop Audio Streaming
        Client->>Server: Binary Message (PCM Data)
        Server-->>Client: JSON: {"event": "result_final", "data": {...}}
    end

    Note over Client, Server: 4. 结束任务
    Client->>Server: JSON: {"event": "task_finish"}
    Server-->>Client: JSON: {"event": "task_finished", ...}
    Server-->>Client: Close Connection
```

***

## 客户端事件

### 1. task\_start - 开始任务

客户端发送 `task_start` 事件配置参数。服务端返回 `task_started` 后方可开始推送二进制音频帧。

**请求参数**

| 参数名                        | 类型     | 必填 | 说明                                               |
| :------------------------- | :----- | :- | :----------------------------------------------- |
| **event**                  | string | 是  | 固定值：**task\_start**                              |
| **model**                  | string | 是  | 模型名称，目前仅支持 `senseaudio-asr-deepthink-1.5-260319` |
| **audio\_setting**         | object | 是  | 音频参数设置，见下文详情                                     |
| **vad\_setting**           | object | 否  | VAD（语音活动检测）设置，见下文详情                              |
| **transcription\_setting** | object | 否  | 识别相关设置，见下文详情                                     |

#### audio\_setting

| 参数名              | 类型     | 必填 | 说明                   |
| :--------------- | :----- | :- | :------------------- |
| **sample\_rate** | int    | 是  | 采样率，目前仅支持 **16000**  |
| **channel**      | int    | 是  | 声道数，目前仅支持 **1**（单声道） |
| **format**       | string | 是  | 音频格式，目前仅支持 `pcm`     |

#### vad\_setting（可选）

| 参数名                         | 类型    | 说明                   | 默认值   |
| :-------------------------- | :---- | :------------------- | :---- |
| **silence\_duration**       | int   | 静音切分阈值 (ms)          | 500   |
| **min\_speech\_duration**   | int   | 最小语音时长 (ms)          | 300   |
| **soft\_max\_duration**     | int   | 软超时时长 (ms)           | 15000 |
| **hard\_max\_duration**     | int   | 硬超时时长 (ms)           | 30000 |
| **soft\_silence\_duration** | int   | 软超时后的静音阈值 (ms)       | 300   |
| **threshold**               | float | VAD 能量阈值 (0.0 - 1.0) | 0.5   |

#### transcription\_setting（可选）

| 参数名                  | 类型     | 说明           | 示例                                 |
| :------------------- | :----- | :----------- | :--------------------------------- |
| **target\_language** | string | 目标语言代码（详见下表） | `en`, `zh`                         |
| **recognize\_mode**  | string | 识别模式         | `auto`（默认）、`record_only`（仅识别不执行指令） |

**支持的语言列表 (`target_language`)**

| 代码   | 语言         | 代码    | 语言         | 代码   | 语言      |
| :--- | :--------- | :---- | :--------- | :--- | :------ |
| `ar` | Arabic     | `yue` | Cantonese  | `zh` | Chinese |
| `nl` | Dutch      | `en`  | English    | `fr` | French  |
| `de` | German     | `id`  | Indonesian | `it` | Italian |
| `ja` | Japanese   | `ko`  | Korean     | `ms` | Malay   |
| `pt` | Portuguese | `ru`  | Russian    | `es` | Spanish |
| `th` | Thai       | `tr`  | Turkish    | `ur` | Urdu    |
| `vi` | Vietnamese |       |            |      |         |

**请求示例**

```json theme={null}
{
  "event": "task_start",
  "model": "senseaudio-asr-deepthink-1.5-260319",
  "audio_setting": {
    "sample_rate": 16000,
    "format": "pcm",
    "channel": 1
  },
  "vad_setting": {
    "silence_duration": 500,
    "min_speech_duration": 300
  }
}
```

**响应参数**

| 参数名                         | 类型     | 说明      |
| --------------------------- | ------ | ------- |
| **event**                   | string | 事件类型    |
| **session\_id**             | string | 会话 ID   |
| **trace\_id**               | string | 链路追踪 ID |
| **base\_resp**              | object | 请求状态信息  |
| **base\_resp.status\_code** | int    | 状态码     |
| **base\_resp.status\_msg**  | string | 状态详情    |

**响应示例**

```json theme={null}
{
  "event": "task_started",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### 2. 音频流传输（Binary Message）

客户端持续发送二进制音频数据，无需额外封装。

* **格式要求**：PCM signed 16-bit little-endian，16kHz，单声道。
* **建议分片**：每片约 100ms（3200 字节）发送，便于模拟实时流。
* **断句机制**：服务端通过 VAD 自动断句，每识别完一句话会返回一次 `result_final`。

**服务端响应示例（`result_final`）**

```json theme={null}
{
  "event": "result_final",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "data": {
    "text": "你好，今天天气真不错。",
    "is_final": true,
    "segment_id": 1,
    "timestamp_end": 1773027072669
  },
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### 3. task\_finish - 结束任务

客户端发送 `task_finish` 事件通知音频发送完毕。服务端处理剩余音频后返回 `task_finished` 并关闭连接。

**请求参数**

| 参数名       | 类型     | 必填 | 说明                   |
| --------- | ------ | -- | -------------------- |
| **event** | string | 是  | 固定值：**task\_finish** |

**请求示例**

```json theme={null}
{ "event": "task_finish" }
```

**响应示例**

```json theme={null}
{
  "event": "task_finished",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

***

## 服务端事件

### connected\_success - 连接建立成功

初次请求接口时，表示 WebSocket 连接建立成功。

```json theme={null}
{
  "event": "connected_success",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### task\_started - 任务已开始

标志任务已成功开始，客户端可以开始推送音频帧。

```json theme={null}
{
  "event": "task_started",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### result\_final - 识别结果

每完成一句断句返回一次，`data` 中包含识别文本及时间戳等信息。

| 参数名                     | 类型      | 说明            |
| :---------------------- | :------ | :------------ |
| **event**               | string  | 事件类型          |
| **session\_id**         | string  | 会话 ID         |
| **trace\_id**           | string  | 链路追踪 ID       |
| **data.text**           | string  | 识别结果文本        |
| **data.is\_final**      | boolean | 识别是否结束        |
| **data.segment\_id**    | int     | 分句序号          |
| **data.timestamp\_end** | int64   | 该句结束时间（毫秒时间戳） |
| **base\_resp**          | object  | 请求状态信息        |

### task\_finished - 任务已结束

标志任务已结束，WebSocket 连接即将关闭。

```json theme={null}
{
  "event": "task_finished",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### task\_failed - 任务失败

标志任务失败，`base_resp.status_msg` 中包含错误信息，服务端可能随即关闭连接。

```json theme={null}
{
  "event": "task_failed",
  "session_id": "trace-id-xxx",
  "trace_id": "trace-id-xxx",
  "base_resp": { "status_code": 2013, "status_msg": "model is required" }
}
```

***

## 使用示例

请将示例代码中的 `SENSEAUDIO_API_KEY` 和 `AUDIO_FILE` 替换为实际值。

<Tabs>
  <Tab title="Python">
    依赖: **pip install websockets**

    ```python theme={null}
    import asyncio
    import json

    import websockets

    SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY"
    WS_URL = "wss://api.senseaudio.cn/ws/v1/audio/transcriptions"
    AUDIO_FILE = "test_audio_16k.pcm"  # 16kHz, 16bit, PCM 单声道

    async def receive_messages(websocket):
        async for message in websocket:
            msg_json = json.loads(message)
            print(f"< Received Event: {msg_json.get('event')}")

            if msg_json.get("event") == "result_final":
                print(f"  识别结果: {msg_json['data']['text']}")
            elif msg_json.get("event") == "task_finished":
                print("  任务完成")
                break

    async def speech_recognition():
        headers = {"Authorization": f"Bearer {SENSEAUDIO_API_KEY}"}
        async with websockets.connect(WS_URL, additional_headers=headers) as websocket:
            # 1. 接收连接成功消息
            resp = await websocket.recv()
            print(f"< Received: {resp}")

            # 2. 发送 task_start
            start_payload = {
                "event": "task_start",
                "model": "senseaudio-asr-deepthink-1.5-260319",
                "audio_setting": {"sample_rate": 16000, "format": "pcm", "channel": 1},
            }
            await websocket.send(json.dumps(start_payload))
            print("> Sent task_start")

            # 接收 task_started
            resp = await websocket.recv()
            print(f"< Received: {resp}")

            # 3. 接收结果（并发）+ 发送音频
            receive_task = asyncio.create_task(receive_messages(websocket))

            with open(AUDIO_FILE, "rb") as f:
                while True:
                    data = f.read(3200)  # 每次发送 3200 字节（约 100ms）
                    if not data:
                        break
                    await websocket.send(data)
                    await asyncio.sleep(0.1)  # 模拟实时流

            # 4. 发送 task_finish
            await websocket.send(json.dumps({"event": "task_finish"}))
            print("> Sent task_finish")

            await receive_task

    if __name__ == "__main__":
        asyncio.run(speech_recognition())
    ```
  </Tab>

  <Tab title="Go">
    依赖: **go get github.com/gorilla/websocket**

    ```go theme={null}
    package main

    import (
    	"encoding/json"
    	"fmt"
    	"io"
    	"log"
    	"net/http"
    	"os"
    	"time"

    	"github.com/gorilla/websocket"
    )

    const (
    	SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY"
    	WS_URL             = "wss://api.senseaudio.cn/ws/v1/audio/transcriptions"
    	AUDIO_FILE         = "test_audio_16k.pcm"
    )

    func main() {
    	header := http.Header{}
    	header.Add("Authorization", "Bearer "+SENSEAUDIO_API_KEY)

    	log.Printf("Connecting to %s", WS_URL)
    	c, _, err := websocket.DefaultDialer.Dial(WS_URL, header)
    	if err != nil {
    		log.Fatal("dial error:", err)
    	}
    	defer c.Close()

    	// 1. 读取连接成功 msg
    	readMessage(c)

    	// 2. 发送 task_start
    	startMsg := map[string]interface{}{
    		"event": "task_start",
    		"model": "senseaudio-asr-deepthink-1.5-260319",
    		"audio_setting": map[string]interface{}{
    			"sample_rate": 16000,
    			"format":      "pcm",
    			"channel":     1,
    		},
    	}
    	if err := c.WriteJSON(startMsg); err != nil {
    		log.Fatal("write startMsg error:", err)
    	}
    	fmt.Println("> Sent task_start")

    	// 读取 task_started
    	readMessage(c)

    	// 3. 准备并发读取结果
    	done := make(chan struct{})
    	go func() {
    		defer close(done)
    		for {
    			_, message, err := c.ReadMessage()
    			if err != nil {
    				if websocket.IsCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway) {
    					fmt.Println("< Connection closed normally")
    					return
    				}
    				log.Println("read error:", err)
    				return
    			}
    			fmt.Printf("< Received: %s\n", message)

    			var msgMap map[string]interface{}
    			if err := json.Unmarshal(message, &msgMap); err != nil {
    				log.Println("json unmarshal error:", err)
    				continue
    			}
    			if event, ok := msgMap["event"].(string); ok && event == "task_finished" {
    				return
    			}
    		}
    	}()

    	// 4. 发送音频（100ms 分片）
    	file, err := os.Open(AUDIO_FILE)
    	if err != nil {
    		log.Fatal("open audio file error:", err)
    	}
    	defer file.Close()

    	const chunkSize = 3200
    	buf := make([]byte, chunkSize)

    	for {
    		n, err := file.Read(buf)
    		if err == io.EOF {
    			break
    		}
    		if err != nil {
    			log.Fatal("read file error:", err)
    		}

    		if err := c.WriteMessage(websocket.BinaryMessage, buf[:n]); err != nil {
    			log.Fatal("write message error:", err)
    		}
    		fmt.Printf("> Sent %d bytes audio data\n", n)

    		// 模拟实时发送：100ms 的音频数据等待 100ms
    		if n == chunkSize {
    			time.Sleep(100 * time.Millisecond)
    		}
    	}

    	// 5. 发送 task_finish
    	if err := c.WriteJSON(map[string]string{"event": "task_finish"}); err != nil {
    		log.Fatal("write task_finish error:", err)
    	}

    	// 6. 等待服务端处理完成并返回 task_finished
    	<-done

    	fmt.Println("> Sent task_finish")
    	fmt.Println("All done!")
    }

    func readMessage(c *websocket.Conn) {
    	_, message, err := c.ReadMessage()
    	if err != nil {
    		if websocket.IsCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway) {
    			fmt.Println("< Connection closed")
    			return
    		}
    		log.Fatal("read message error:", err)
    	}
    	fmt.Printf("< Received: %s\n", message)
    }
    ```
  </Tab>

  <Tab title="Node.js">
    依赖: **npm install ws**

    ```javascript theme={null}
    const WebSocket = require('ws');
    const fs = require('fs');

    const SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY";
    const WS_URL = "wss://api.senseaudio.cn/ws/v1/audio/transcriptions";
    const AUDIO_FILE = "test_audio_16k.pcm";

    const ws = new WebSocket(WS_URL, {
      headers: {
        Authorization: `Bearer ${SENSEAUDIO_API_KEY}`,
      },
    });

    ws.on('open', () => console.log('Connected'));

    ws.on('message', (data, isBinary) => {
      if (isBinary) return;

      const msg = JSON.parse(data.toString());
      console.log('< Received:', msg.event);

      if (msg.event === 'connected_success') {
        const startMsg = {
          event: 'task_start',
          model: 'senseaudio-asr-deepthink-1.5-260319',
          audio_setting: { sample_rate: 16000, format: 'pcm', channel: 1 },
        };
        ws.send(JSON.stringify(startMsg));
        console.log('> Sent task_start');
      } else if (msg.event === 'task_started') {
        streamAudio();
      } else if (msg.event === 'result_final') {
        console.log('  Result:', msg.data.text);
      } else if (msg.event === 'task_finished') {
        process.exit(0);
      }
    });

    function streamAudio() {
      const stream = fs.createReadStream(AUDIO_FILE, { highWaterMark: 3200 });
      let processing = false;

      stream.on('data', (chunk) => {
        stream.pause();
        processing = true;
        ws.send(chunk);

        setTimeout(() => {
          processing = false;
          stream.resume();
        }, 100);
      });

      stream.on('end', () => {
        const checkAndFinish = () => {
          if (!processing) {
            ws.send(JSON.stringify({ event: 'task_finish' }));
            console.log('> Sent task_finish');
          } else {
            setTimeout(checkAndFinish, 50);
          }
        };
        checkAndFinish();
      });
    }
    ```
  </Tab>
</Tabs>

***

## 错误码说明

| 状态码  | 说明     | 解决方案                                |
| ---- | ------ | ----------------------------------- |
| 0    | 成功     | -                                   |
| 2013 | 缺少必填参数 | 检查 `task_start` 是否携带了 `model` 等必填字段 |

***

## 注意事项

1. **消息类型区分**：控制消息必须用文本帧发送 JSON，音频帧必须用二进制帧发送；混用会导致服务端解析失败。
2. **事件发送顺序**：必须按 `连接 → task_start → 音频帧 → task_finish` 顺序发送；仅在收到 `task_started` 后才可发送音频。
3. **音频参数**：当前仅支持 16kHz / 16-bit / 单声道 PCM；若录音源采样率不同，需在客户端重采样。
4. **实时流节奏**：建议每片约 100ms（3200 字节）发送，避免过快占满缓冲或过慢导致 VAD 误触发。
5. **连接关闭**：收到 `task_finished` 或 `task_failed` 后服务端会关闭连接，客户端应及时回收资源。

## 相关资源

<CardGroup>
  <Card title="离线转写 API" icon="file-audio" href="/api-reference/endpoint/asr/transcriptions">
    基于 HTTP 的文件识别接口。
  </Card>

  <Card title="WebSocket 实时识别指南" icon="bolt" href="/guides/asr/overview">
    WebSocket ASR 的应用场景与接入最佳实践。
  </Card>

  <Card title="ASR 总览" icon="book-open" href="/guides/asr/overview">
    语音识别能力与模型对比。
  </Card>

  <Card title="音频质量检测" icon="waveform-lines" href="/api-reference/endpoint/asr/analysis">
    离线音频噪声/可用性检测。
  </Card>
</CardGroup>


# 音频生成
Source: https://docs.senseaudio.cn/api-reference/endpoint/audio/generate

POST /v1/audio/generate
通过文本、参考音色和参考音频生成完整音频

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.senseaudio.cn/v1/audio/generate \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "senseaudio-a1",
      "prompt": "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
      "references": []
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.senseaudio.cn/v1/audio/generate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "senseaudio-a1",
          "prompt": "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
          "references": [],
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.senseaudio.cn/v1/audio/generate", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "senseaudio-a1",
      prompt: "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
      references: [],
    }),
  });
  console.log(await response.json());
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.senseaudio.cn/v1/audio/generate");
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer YOUR_API_KEY",
          "Content-Type: application/json",
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "model" => "senseaudio-a1",
          "prompt" => "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
          "references" => [],
      ], JSON_UNESCAPED_UNICODE),
      CURLOPT_RETURNTRANSFER => true,
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      body := []byte(`{"model":"senseaudio-a1","prompt":"@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。","references":[]}`)
      req, _ := http.NewRequest("POST", "https://api.senseaudio.cn/v1/audio/generate", bytes.NewReader(body))
      req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")
      resp, _ := http.DefaultClient.Do(req)
      defer resp.Body.Close()
      result, _ := io.ReadAll(resp.Body)
      fmt.Println(string(result))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class AudioGenerate {
    public static void main(String[] args) throws Exception {
      var request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.senseaudio.cn/v1/audio/generate"))
          .header("Authorization", "Bearer YOUR_API_KEY")
          .header("Content-Type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(
              "{\"model\":\"senseaudio-a1\",\"prompt\":\"@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。\",\"references\":[]}"))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println(response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "json"

  uri = URI("https://api.senseaudio.cn/v1/audio/generate")
  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer YOUR_API_KEY"
  request["Content-Type"] = "application/json"
  request.body = {
    model: "senseaudio-a1",
    prompt: "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
    references: []
  }.to_json
  puts Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request).body }
  ```
</RequestExample>

## 说明

通过提示词生成完整音频。你可以在提示词中编排角色对白、背景音乐和环境音效，并使用平台音色、个人音色或参考音频控制声音表现。

* **接口地址**：`POST https://api.senseaudio.cn/v1/audio/generate`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **模型**：`senseaudio-a1`
* **最大生成时长**：120 秒（以 `model_duration` 计）
* **计费**：按 `model_duration` 计费，每秒 85 积分。详见 [计费规则](/guides/account/billing)

<Note>
  生成音频的最终时长为 `duration`。当设置 `speech_rate` 时，最终时长可能与模型实际生成时长 `model_duration` 不同；计费始终以 `model_duration` 为准。
</Note>

## 请求参数

### 顶层参数

| 参数名            | 类型     |  必填 | 说明                                  |
| -------------- | ------ | :-: | ----------------------------------- |
| `model`        | string |  是  | 固定为 `senseaudio-a1`。                |
| `prompt`       | string |  是  | 音频生成提示词。可描述角色、台词、情绪、背景音乐、环境音效和声音顺序。 |
| `audio_config` | object |  否  | 输出音频配置。所有子字段均为可选。                   |
| `references`   | array  |  否  | 参考音频列表，最多包含 3 条参考音频。                |

### `audio_config` 参数

| 参数名               | 类型      | 默认值    | 说明                                                              |
| ----------------- | ------- | ------ | --------------------------------------------------------------- |
| `enable_subtitle` | boolean | `true` | 是否返回字幕信息。未传入时默认返回。                                              |
| `format`          | string  | —      | 输出格式：`wav`、`mp3`。                                               |
| `loudness_rate`   | integer | `0`    | 音量调整，范围 `[-50, 100]`。`-50` 表示音量减半，`100` 表示音量增加一倍。               |
| `pitch_rate`      | integer | `0`    | 音调调整，范围 `[-12, 12]`。                                            |
| `sample_rate`     | integer | —      | 采样率（Hz）：`8000`、`16000`、`24000`、`32000`、`40000`、`44100`、`48000`。 |
| `speech_rate`     | integer | `0`    | 语速调整，范围 `[-50, 100]`。`-50` 表示速度减半，`100` 表示速度增加一倍。               |

### `references` 元素

每个元素提供一条参考音频。

| 参数名                 | 类型     | 说明                           |
| ------------------- | ------ | ---------------------------- |
| `audio_url`         | string | 参考音频地址。最多 3 条，单条时长不得超过 30 秒。 |
| `audio_url` 支持以下格式： |        |                              |

* `http` / `https` URL，例如 `https://example.com/test.wav`
* Data URI，例如 `data:audio/x-wav;base64,...`

## 使用音色和参考音频

你可以在 `prompt` 中引用平台音色、个人音色和参考音频：

* 使用 `@<音色标签>` 引用平台内置音色或你已生成/克隆的音色，例如 `@male_0029_a`。
* 使用 `@音频<序号>` 引用 `references` 内的参考音频，序号从 1 开始，例如 `@音频1`。
* 如不希望 `@...` 被识别为音色或参考音频，请使用反斜杠转义，例如 `\@male_0029_a`。
* 音色标签数量与参考音频数量之和不得超过 3。

### 使用参考音频的请求示例

```json theme={null}
{
  "model": "senseaudio-a1",
  "prompt": "@音频1 别太在意他人评价，做好自己的事才是最实在的。",
  "references": [
    {
      "audio_url": "file-id:file-xxxxxxxx"
    }
  ]
}
```

## 响应参数

| 参数名                               | 类型      | 说明                                                       |
| --------------------------------- | ------- | -------------------------------------------------------- |
| `audio_url`                       | string  | 生成音频的访问地址。                                               |
| `duration`                        | number  | 最终音频总时长，单位为秒。                                            |
| `model_duration`                  | number  | 模型实际生成时长，单位为秒，也是计费时长。                                    |
| `subtitle`                        | object  | 字幕信息。仅当 `audio_config.enable_subtitle` 为 `true` 或未设置时返回。 |
| `subtitle.text`                   | string  | 全部字幕文本。                                                  |
| `subtitle.sentences`              | array   | 按句切分的字幕列表。                                               |
| `subtitle.sentences[].text`       | string  | 当前句文本。                                                   |
| `subtitle.sentences[].start_time` | integer | 当前句开始时间戳，单位为毫秒。                                          |
| `subtitle.sentences[].end_time`   | integer | 当前句结束时间戳，单位为毫秒。                                          |
| `subtitle.sentences[].words`      | array   | 按词切分的时间戳信息。                                              |

## 响应示例

```json theme={null}
{
  "audio_url": "https://example.com/generated-audio.wav",
  "duration": 5.215,
  "model_duration": 5.215,
  "subtitle": {
    "text": "别太在意他人评价，做好自己的事才是最实在的。",
    "sentences": [
      {
        "start_time": 0,
        "end_time": 5160,
        "text": "别太在意他人评价，做好自己的事才是最实在的。",
        "words": [
          {
            "start_time": 0,
            "end_time": 280,
            "text": "别"
          }
        ]
      }
    ]
  }
}
```


# 创建自定义 Agent
Source: https://docs.senseaudio.cn/api-reference/endpoint/custom-agent/create

POST /v1/agent
创建一个新的自定义 Agent，提供 Agent 的基本信息、角色介绍和适用场景等内容。创建成功后可以获得一个 Agent ID，用于后续的对话创建。

## 说明

管理账号下的自定义 Agent，所创建的 Agent 可在 [创建实时会话](/api-reference/endpoint/realtime/invoke) 中使用。

* **标识规则**：每个 Agent 拥有全局唯一 `id`，删除不可恢复
* **配置项**：提示词、工具、音色、LLM 模型均可按需组合


# 删除自定义 Agent
Source: https://docs.senseaudio.cn/api-reference/endpoint/custom-agent/delete

DELETE /v1/agent/{id}
删除一个已存在的自定义 Agent，删除后该 Agent 将无法再被使用。



# 获取自定义 Agent 列表
Source: https://docs.senseaudio.cn/api-reference/endpoint/custom-agent/list

GET /v1/agents
获取自定义Agent列表，包括Agent的基本信息、角色介绍和适用场景。支持分页查询。



# 更新自定义 Agent
Source: https://docs.senseaudio.cn/api-reference/endpoint/custom-agent/update

PUT /v1/agent/{id}
更新一个已存在的自定义 Agent，可以修改 Agent 的基本信息、角色介绍和适用场景等内容。



# 音色克隆上传文件
Source: https://docs.senseaudio.cn/api-reference/endpoint/files/upload

POST /v1/files/upload
上传音色克隆参考音频。Authorization 直接传 API Key，不需要 Bearer 前缀；purpose 固定传 voice_clone。

## 说明

上传音频文件并获取 `file_id`，用于后续音色克隆接口引用。音色克隆场景下，`purpose` 固定传 `voice_clone`。

* **音频要求**：建议上传 **3-30 秒** 的清晰人声音频，文件大小 **50MB 以内**，支持 **MP3、AAC、WAV** 格式。
* **请求格式**：使用 `multipart/form-data`，文件字段必须以二进制文件形式上传。
* **结果使用**：后续克隆接口中的 `file_id` 使用返回值里的 `file.file_id`。

## 调用示例

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/voice.wav"
```

<Note>
  上传文件接口的 `Authorization` 直接传 API Key，不需要 `Bearer` 前缀。`-F "file=@/path/to/voice.wav"` 中的 `@` 不能省略；省略后会上传字符串路径，而不是文件内容。
</Note>

## 成功返回示例

```json theme={null}
{
  "file": {
    "file_id": "file-E4avzR574Mm42YoCytmiND",
    "filename": "温柔御姐_1782460863330.wav",
    "bytes": 228778,
    "purpose": "voice_clone",
    "created_at": 1783326931
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

## 下一步

上传成功后，您可以选择以下任一方式生成克隆音色：

* [SenseAudio 音色克隆](/api-reference/endpoint/voice/clone-senseaudio)
* [Minimax 兼容音色克隆](/api-reference/endpoint/voice/clone)


# 异步图片生成
Source: https://docs.senseaudio.cn/api-reference/endpoint/image/async

api-reference/endpoint/image/image.openapi.json POST /v1/image/async

## 说明

异步方式生成图片，获得异步任务ID。获得异步任务ID后可使用[查询图片任务 API](/api-reference/endpoint/image/pending)轮询图片生成状态。

对于需要保持 HTTP 请求连接并最终返回图片数据的 API，见[同步图片生成 API](/api-reference/endpoint/image/sync)。

## 图片大小要求

不同模型具有不同的图片大小要求：

| 模型                          | 可选尺寸                                                                                                                                                                                                                                                                                |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| senseaudio-image-2.0-260319 | 1024x1024<br />1536x864<br />864x1536<br />2016x864<br />864x2016<br />2048x1024<br />1024x2048<br />2048x1152<br />1152x2048<br />2688x1152<br />1152x2688<br />2688x1344<br />1344x2688<br />3840x1648<br />1648x3840<br />3840x1920<br />1920x3840<br />3840x2160<br />2160x3840 |
| senseaudio-image-1.0-260319 | 1664x928<br />928x1664<br />1584x1056<br />1056x1584<br />1472x1140<br />1140x1472<br />1328x1328                                                                                                                                                                                   |
| doubao-seedream-5-0-260128  | 2304x1728<br />1728x2304<br />2496x1664<br />1664x2496<br />2048x2048<br />3136x1344<br />2848x1600<br />1600x2848<br />3456x2592<br />2592x3456<br />2496x3744<br />3744x2496<br />4096x2304<br />2304x4096<br />3072x3072<br />4704x2016                                          |
| sensenova-u1-fast           | 1664x2496<br />2496x1664<br />1760x2368<br />2368x1760<br />1824x2272<br />2272x1824<br />2048x2048<br />2752x1536<br />1536x2752<br />3072x1376<br />1344x3136                                                                                                                     |

如果模型不支持对应的图片大小，服务端将以 400 状态码返回报错。


# 查询图片任务
Source: https://docs.senseaudio.cn/api-reference/endpoint/image/pending

api-reference/endpoint/image/image.openapi.json GET /v1/image/pending

# 说明

使用异步方式生成图片任务后，使用此接口获取异步图片任务的状态和生成结果。


# 同步图片生成
Source: https://docs.senseaudio.cn/api-reference/endpoint/image/sync

api-reference/endpoint/image/image.openapi.json POST /v1/image/sync

## 说明

同步方式生成图片。在生成图片过程中需要保持 HTTP 请求连接。对于不需要持续连接的异步生成请求，见[异步图片生成 API](/api-reference/endpoint/image/async)。

## 图片大小要求

不同模型具有不同的图片大小要求：

| 模型                          | 可选尺寸                                                                                                                                                                                                                                                                                |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| senseaudio-image-2.0-260319 | 1024x1024<br />1536x864<br />864x1536<br />2016x864<br />864x2016<br />2048x1024<br />1024x2048<br />2048x1152<br />1152x2048<br />2688x1152<br />1152x2688<br />2688x1344<br />1344x2688<br />3840x1648<br />1648x3840<br />3840x1920<br />1920x3840<br />3840x2160<br />2160x3840 |
| senseaudio-image-1.0-260319 | 1664x928<br />928x1664<br />1584x1056<br />1056x1584<br />1472x1140<br />1140x1472<br />1328x1328                                                                                                                                                                                   |
| doubao-seedream-5-0-260128  | 2304x1728<br />1728x2304<br />2496x1664<br />1664x2496<br />2048x2048<br />3136x1344<br />2848x1600<br />1600x2848<br />3456x2592<br />2592x3456<br />2496x3744<br />3744x2496<br />4096x2304<br />2304x4096<br />3072x3072<br />4704x2016                                          |
| sensenova-u1-fast           | 1664x2496<br />2496x1664<br />1760x2368<br />2368x1760<br />1824x2272<br />2272x1824<br />2048x2048<br />2752x1536<br />1536x2752<br />3072x1376<br />1344x3136                                                                                                                     |

如果模型不支持对应的图片大小，服务端将以 400 状态码返回报错。


# 对话 (Chat) API
Source: https://docs.senseaudio.cn/api-reference/endpoint/llm/chat

api-reference/endpoint/llm/chat.openapi.json POST /v1/chat/completions
标准化多轮对话接口，兼容 OpenAI 规范，支持 Function Calling 与多模态输入

## 说明

提供标准化的对话接口，兼容主流规范，支持多轮对话、工具调用 (Function Calling) 及多模态输入。

* **接口地址**：`POST https://api.senseaudio.cn/v1/chat/completions`
* **Content-Type**：`application/json`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **流式输出**：`stream: true` 以 SSE 协议逐块返回；收到 `data: [DONE]` 标识流结束
* **模型列表**：见 [模型列表](/guides/account/model-list)
* **计费**：按输入 / 输出 token 计费，详见 [计费说明](/guides/account/billing)

## Authorizations

<ParamField type="string">
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`。
</ParamField>

## Body

<Note>`application/json`</Note>

<ParamField type="enum<string>">
  用于补全你提示词的模型。

  可用选项：`senseaudio-s2`，`senseaudio-s1`，`senseaudio-s2-flash`，`senseaudio-s2-lite`，`senseaudio-vl-1.0-260319`，`senseaudio-vl-lite-1.0-260319`，`sensenova-6.8-flash-lite`，`deepseek-v4-flash-0731`，`doubao-seed-2-0-pro-260215`，`glm-5.3-flash`，`glm-5.2`，`kimi-k2.6`，`minimax-m2.7`，`qwen3.8-27b`，`qwen3.6-35b-a3b`

  示例：`"senseaudio-s2"`
</ParamField>

<ParamField type="object[]">
  包含历史对话上下文和当前输入的消息列表。

  <Expandable title="child attributes">
    <ParamField type="string">
      发送消息的角色：`system` / `user` / `assistant` / `tool`。
    </ParamField>

    <ParamField type="string | object[]">
      消息内容。文本形式直接传字符串；多模态形式传对象数组（如图片 URL）。
    </ParamField>

    <ParamField type="string">
      参与者的名称，用于向模型提供特定的身份标识。
    </ParamField>

    <ParamField type="object[]">
      仅当 `role="assistant"` 时可能出现，表示触发的工具调用列表。
    </ParamField>

    <ParamField type="string">
      仅当 `role="tool"` 时必填，表示该条执行结果对应的工具调用请求 ID。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  模型可调用的工具列表，主要用于 Function Calling 场景。

  <Expandable title="child attributes">
    <ParamField type="string">
      工具类型。当前为 `"function"`。
    </ParamField>

    <ParamField type="object">
      函数工具定义对象，包含 `name`、`description`、`parameters`（JSON Schema）。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string | object">
  控制模型调用工具的行为：`none` / `auto` / `required`，或指定函数对象 `{type: 'function', function: {name: 'my_func'}}`。
</ParamField>

<ParamField type="boolean">
  是否开启流式响应，开启后通过 SSE 协议逐块返回。
</ParamField>

<ParamField type="object">
  流式响应选项（仅 `stream=true` 时有效）。

  <Expandable title="child attributes">
    <ParamField type="boolean">
      若为 `true`，会在终止块 `[DONE]` 前返回包含 `usage` 的最后一个 chunk。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  输出格式：`{type: 'text'}`（默认）、`{type: 'json_object'}`（强制 JSON）。
</ParamField>

<ParamField type="integer">
  限制生成的最大 token 数量。不设置则直至自然生成完毕或达到模型上限。
</ParamField>

<ParamField type="number">
  采样温度，范围 `[0.0, 2.0]`。值越高输出越随机，建议与 `top_p` 二选一调整。
</ParamField>

<ParamField type="number">
  核采样概率阈值，范围 `[0.0, 1.0]`。
</ParamField>

<ParamField type="integer">
  为每条输入消息生成的回复选项数量。
</ParamField>

<ParamField type="string | string[]">
  停止词序列（最多 4 个）。
</ParamField>

<ParamField type="number">
  频率惩罚系数，范围 `[-2.0, 2.0]`。
</ParamField>

<ParamField type="number">
  存在惩罚系数，范围 `[-2.0, 2.0]`。
</ParamField>

<ParamField type="object">
  调整特定 token 出现的概率。键为 Token ID，值为偏差 `[-100, 100]`。
</ParamField>

<ParamField type="boolean">
  是否返回输出 token 的对数概率。
</ParamField>

<ParamField type="integer">
  返回在每个位置最可能的 N 个 token 的概率（需开启 `logprobs`，范围 `[0, 20]`）。
</ParamField>

<ParamField type="integer">
  随机种子，用于尽可能的确定性采样。
</ParamField>

<ParamField type="string">
  最终用户的唯一标识，可用于协助监控及防滥用。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="id" type="string">
  本次请求的唯一标识符。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型。非流式为 `"chat.completion"`；流式为 `"chat.completion.chunk"`。
</ResponseField>

<ResponseField name="created" type="integer">
  生成成功的 Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="model" type="string">
  实际响应的模型名称。
</ResponseField>

<ResponseField name="system_fingerprint" type="string">
  模型运行的后端配置系统指纹。
</ResponseField>

<ResponseField name="choices" type="object[]">
  模型生成的回复选项列表。

  <Expandable title="child attributes">
    <ResponseField name="choices.index" type="integer">
      在数组中的索引下标。
    </ResponseField>

    <ResponseField name="choices.finish_reason" type="string">
      停止原因：`stop` / `length` / `tool_calls` / `content_filter`。
    </ResponseField>

    <ResponseField name="choices.message" type="object">
      模型返回的消息对象（非流式）。

      <Expandable title="message fields">
        <ResponseField name="message.role" type="string">
          始终为 `"assistant"`。
        </ResponseField>

        <ResponseField name="message.content" type="string">
          文本回复内容（仅调用工具时可能为空）。
        </ResponseField>

        <ResponseField name="message.tool_calls" type="object[]">
          决定的工具调用列表，包含 `id`、`type`、`function`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="choices.delta" type="object">
      流式模式下替代 `message`，增量内容对象（含 `role` / `content` / `tool_calls` 增量）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token 消耗统计。

  <Expandable title="child attributes">
    <ResponseField name="usage.prompt_tokens" type="integer">
      提示词消耗。
    </ResponseField>

    <ResponseField name="usage.completion_tokens" type="integer">
      补全结果消耗。
    </ResponseField>

    <ResponseField name="usage.total_tokens" type="integer">
      总消耗。
    </ResponseField>
  </Expandable>
</ResponseField>

## 流式响应示例

开启 `stream: true` 时，基于 SSE 协议逐块返回：

```text theme={null}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{"content":"黑洞"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

## 错误处理

错误时返回非 200 状态码，响应体包含 `error` 对象：

<ResponseField name="error" type="object">
  错误对象。

  <Expandable title="child attributes">
    <ResponseField name="error.message" type="string">错误的人类可读描述。</ResponseField>
    <ResponseField name="error.type" type="string">错误类别（如 `invalid_request_error`）。</ResponseField>
    <ResponseField name="error.code" type="string">固定错误码的内部代号。</ResponseField>
    <ResponseField name="error.param" type="string">触发该错误的对应参数名。</ResponseField>
  </Expandable>
</ResponseField>

## 相关指南

* [文本生成介绍](/guides/llm/overview)
* [模型响应 (Responses) API](/api-reference/endpoint/llm/responses)
* [消息 (Messages)](/api-reference/endpoint/llm/messages)
* [计费说明](/guides/account/billing)


# 消息 (Messages)
Source: https://docs.senseaudio.cn/api-reference/endpoint/llm/messages

api-reference/endpoint/llm/messages.openapi.json POST /v1/messages
发送结构化的输入消息列表（支持文本和/或图片内容），模型将在会话中生成下一条消息。



# 模型响应 (Responses) API
Source: https://docs.senseaudio.cn/api-reference/endpoint/llm/responses

api-reference/endpoint/llm/responses.openapi.json POST /v1/responses
通用模型生成接口，支持结构化输入输出与复杂推理控制

## 说明

通用模型生成接口，支持结构化输入输出，适用于更底层、更复杂的逻辑控制与推理场景。

* **接口地址**：`POST https://api.senseaudio.cn/v1/responses`
* **Content-Type**：`application/json`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **流式输出**：`stream: true` 以 SSE 协议逐块返回；收到 `data: [DONE]` 标识流结束
* **模型列表**：见 [模型列表](/guides/account/model-list)
* **计费**：按输入 / 输出 token 计费，详见 [计费说明](/guides/account/billing)

## Authorizations

<ParamField type="string">
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`。
</ParamField>

## Body

<Note>`application/json`</Note>

<ParamField type="enum<string>">
  用于补全你提示词的模型。

  可用选项：`senseaudio-s2`，`senseaudio-s1`，`senseaudio-s2-flash`，`senseaudio-s2-lite`，`senseaudio-vl-1.0-260319`，`senseaudio-vl-lite-1.0-260319`，`sensenova-6.8-flash-lite`，`deepseek-v4-flash-0731`，`doubao-seed-2-0-pro-260215`，`glm-5.3-flash`，`glm-5.2`，`kimi-k2.6`，`minimax-m2.7`，`qwen3.8-27b`，`qwen3.6-35b-a3b`

  示例：`"senseaudio-s2"`
</ParamField>

<ParamField type="string | object[]">
  输入内容。字符串视为一条纯文本用户消息；数组则是包含多个输入元素的列表。

  <Expandable title="数组元素类型">
    <ParamField type="string">
      元素类型：`message` / `input_text` / `input_image` / `function_call` / `function_call_output`。
    </ParamField>

    <ParamField type="string">
      仅 `message`：发送者角色（`system` / `user` / `assistant`）。
    </ParamField>

    <ParamField type="string | object[]">
      仅 `message`：文本或多模态对象数组。
    </ParamField>

    <ParamField type="string">
      仅 `input_text`：文本内容。
    </ParamField>

    <ParamField type="string">
      仅 `input_image`：图片 URL 或 base64 (data URL)。
    </ParamField>

    <ParamField type="string">
      仅 `input_image`：`low` / `high` / `auto`。
    </ParamField>

    <ParamField type="string">
      仅 `function_call`：工具函数名。
    </ParamField>

    <ParamField type="string">
      仅 `function_call` / `function_call_output`：调用的唯一 ID。
    </ParamField>

    <ParamField type="string">
      仅 `function_call`：JSON 格式的函数参数。
    </ParamField>

    <ParamField type="string">
      仅 `function_call_output`：工具执行后返回的输出结果。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  模型可调用的工具列表。

  <Expandable title="child attributes">
    <ParamField type="string">
      工具类型。当前为 `"function"`。
    </ParamField>

    <ParamField type="object">
      函数工具定义对象，包含 `name`、`description`、`parameters`（JSON Schema）。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string | object">
  控制模型调用工具的行为：`none` / `auto` / `required`，或指定函数对象。
</ParamField>

<ParamField type="boolean">
  是否开启 SSE 流式返回。
</ParamField>

<ParamField type="number">
  采样温度，范围 `[0.0, 2.0]`。
</ParamField>

<ParamField type="number">
  核采样概率阈值，范围 `[0.0, 1.0]`。
</ParamField>

<ParamField type="integer">
  限制生成的最大 token 数量。
</ParamField>

<ParamField type="object">
  输出格式：`{type: 'json_object'}`（强制 JSON）或 `{type: 'json_schema', json_schema: {...}}`（结构化输出）。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="id" type="string">
  本次响应的唯一标识符。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，固定为 `"response"`。
</ResponseField>

<ResponseField name="created" type="integer">
  响应创建的 Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="model" type="string">
  实际响应的模型名称。
</ResponseField>

<ResponseField name="status" type="string">
  请求状态：`completed` / `in_progress` / `incomplete`。
</ResponseField>

<ResponseField name="output" type="object">
  模型生成的核心内容对象。

  <Expandable title="child attributes">
    <ResponseField name="output.type" type="string">
      输出类别：`message` / `function_call` / `reasoning`。
    </ResponseField>

    <ResponseField name="output.role" type="string">
      仅 `message` 时存在，始终为 `"assistant"`。
    </ResponseField>

    <ResponseField name="output.content" type="string | object[]">
      仅 `message` 时存在，生成的回复内容。
    </ResponseField>

    <ResponseField name="output.name" type="string">
      仅 `function_call` 时存在，模型决定调用的目标函数名。
    </ResponseField>

    <ResponseField name="output.arguments" type="string">
      仅 `function_call` 时存在，生成的函数参数（JSON 字符串）。
    </ResponseField>

    <ResponseField name="output.call_id" type="string">
      仅 `function_call` 时存在，生成的唯一调用标识符。
    </ResponseField>

    <ResponseField name="output.summary" type="string[]">
      仅 `reasoning` 时存在，内部思维链推进过程的文本数组。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token 消耗统计。

  <Expandable title="child attributes">
    <ResponseField name="usage.input_tokens" type="integer">
      提示内容消耗。
    </ResponseField>

    <ResponseField name="usage.output_tokens" type="integer">
      生成结果消耗。
    </ResponseField>

    <ResponseField name="usage.total_tokens" type="integer">
      总消耗统计。
    </ResponseField>
  </Expandable>
</ResponseField>

## 流式响应示例

开启 `stream: true` 时，SSE 协议逐块返回，数据块前缀 `data: `：

```text theme={null}
data: {"object":"response.chunk","output":{"content":"闭包"}}

data: {"object":"response.chunk","output":{"content":"是指那些..."}}

data: [DONE]
```

流式 `output` 字段：`content`（文本片段）/ `arguments`（工具调用参数片段）。

## 错误处理

<ResponseField name="error" type="object">
  错误对象。

  <Expandable title="child attributes">
    <ResponseField name="error.message" type="string">错误详细描述。</ResponseField>
    <ResponseField name="error.type" type="string">错误类型（如 `invalid_request_error`）。</ResponseField>
    <ResponseField name="error.code" type="string">内部错误代码。</ResponseField>
    <ResponseField name="error.param" type="string">导致错误的对应参数名。</ResponseField>
  </Expandable>
</ResponseField>

## 相关指南

* [文本生成介绍](/guides/llm/overview)
* [对话 (Chat) API](/api-reference/endpoint/llm/chat)
* [消息 (Messages)](/api-reference/endpoint/llm/messages)
* [计费说明](/guides/account/billing)


# 歌词生成
Source: https://docs.senseaudio.cn/api-reference/endpoint/music/lyrics-create

api-reference/endpoint/music/music.openapi.json POST /v1/music/lyrics/create
根据主题和风格同步生成结构化歌词

## 说明

根据主题和风格同步生成结构化歌词，并返回标题、编曲信息与歌词正文。

<Info>
  该接口为同步接口，请求完成后直接返回歌词结果，不需要轮询任务状态。
</Info>


# 歌词改写
Source: https://docs.senseaudio.cn/api-reference/endpoint/music/lyrics-revise

api-reference/endpoint/music/music.openapi.json POST /v1/music/lyrics/revise
根据修改意见同步改写已有歌词，返回完整的新版本歌词

## 说明

根据修改意见同步改写已有歌词，返回完整的新版本歌词。

<Info>
  该接口为同步接口，请求完成后直接返回改写结果，不需要轮询任务状态。
</Info>

<Warning>
  `lyrics` 应传入完整歌词正文；接口返回完整改写结果，而不是差异片段。
</Warning>

## 接口能力

歌词改写接口适合在保留主题和结构的前提下，对已有歌词进行整体润色、情绪调整、措辞优化或段落重写。

**核心能力：**

* **保留原意**：在不改变主题的基础上改写表达方式
* **按反馈改写**：根据你提供的修改意见调整情绪、措辞或段落
* **返回完整结果**：输出完整的新歌词，而不是局部 diff

## 请求参数

| 参数         | 类型     | 必填 | 说明                                               |
| ---------- | ------ | -- | ------------------------------------------------ |
| `model`    | string | 是  | 已启用的音乐模型 label，当前为 `senseaudio-music-2.0-260626` |
| `lyrics`   | string | 是  | 需要改写的原歌词正文                                       |
| `feedback` | string | 是  | 明确的修改意见，例如情绪、措辞或段落调整                             |

## 请求示例

```bash theme={null}
curl --request POST \
  --url https://nightly.api.senseaudio.cn/v1/music/lyrics/revise \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "senseaudio-music-2.0-260626",
    "lyrics": "[verse]\n海风吹过无人的站台...",
    "feedback": "副歌更有记忆点，减少抽象意象，保留夏夜主题"
  }'
```

## 返回示例

```json theme={null}
{
  "data": [
    {
      "text": "[verse]\n海风吹过熟悉的站台..."
    }
  ]
}
```

## 使用建议

* 保留原歌词的主体结构，再用 `feedback` 说明你要强化的方向
* 如果你希望结果更明确，可以同时指出情绪、画面感、节奏或段落位置
* 需要改写后的歌词直接进入后续歌曲生成流程时，可以继续复用返回的 `data[].text`


# 歌曲生成 V1
Source: https://docs.senseaudio.cn/api-reference/endpoint/music/song-create-v1

api-reference/endpoint/music/music.openapi.json POST /v1/music/song/create
使用 Music 1.0 的历史参数创建异步歌曲任务

## 说明

使用 Music 1.0 的历史参数创建异步歌曲任务。该接口用于保持已有 V1 调用不受 V2 上线影响。

<Info>
  历史行为保持不变：`custom_mode=true` 时 `lyrics` 作为自定义歌词；`custom_mode=false` 时 `lyrics` 作为自然语言提示词。
</Info>

<Warning>
  该路径仅接受 Music 1.0 模型。Music 2.0 请使用 [歌曲生成 V2](/api-reference/endpoint/music/song-create-v2)。
</Warning>

## 歌曲格式

当参数 `custom_mode` 为 `false` 时，歌词需要按照指定格式输入。歌词由多个歌曲段组成，每个段以结构标签开头。模型通过这些标签引导歌曲结构和歌词发展。

| 标签              | 段落类型      | 是否需要歌词 | 时长参考      | 说明             |
| :-------------- | :-------- | :----- | :-------- | :------------- |
| \[intro-short]  | 前奏 Intro  | ❌ 无歌词  | \~0–10 秒  | 短前奏，纯伴奏引入      |
| \[intro-medium] | 前奏 Intro  | ❌ 无歌词  | \~10–20 秒 | 中长前奏版本         |
| \[inst-short]   | 纯伴奏段      | ❌ 无歌词  | \~0–10 秒  | 中间的器乐演奏段       |
| \[inst-medium]  | 纯伴奏段      | ❌ 无歌词  | \~10–20 秒 | 较长的器乐段         |
| \[outro-short]  | 尾奏 Outro  | ❌ 无歌词  | \~0–10 秒  | 短尾部收束          |
| \[outro-medium] | 尾奏 Outro  | ❌ 无歌词  | \~10–20 秒 | 中长尾部收束         |
| \[verse]        | 主歌 Verse  | ✅ 需要歌词 | 无固定时长     | 承担叙事内容，应有完整句子  |
| \[chorus]       | 副歌 Chorus | ✅ 需要歌词 | 无固定时长     | 歌曲主题部分，应朗朗上口   |
| \[bridge]       | 过渡 Bridge | ✅ 需要歌词 | 无固定时长     | 连接主歌与副歌，增强情绪转换 |


# 歌曲生成 V2
Source: https://docs.senseaudio.cn/api-reference/endpoint/music/song-create-v2

api-reference/endpoint/music/music.openapi.json POST /v2/music/song/create
使用 Music 2.0 的结构化参数创建异步歌曲任务

## 说明

使用 Music 2.0 的结构化参数创建异步歌曲任务，返回 `task_id` 后通过统一查询接口轮询结果。

<Info>
  该接口为异步接口，创建任务后请使用 [查询歌曲任务](/api-reference/endpoint/music/song-pending) 轮询结果。
</Info>

<Warning>
  V2 不接收 V1 的 `custom_mode`、`instrumental`、`title`、`style_weight` 或 `weirdness_constraint` 字段。
</Warning>

<Warning>
  仅顶层 `lyrics` 使用 `cl100k_base` 执行 1600 token 限制；`prebuilt_lyrics`、歌词生成和歌词改写不使用该限制。
</Warning>

<Warning>
  `prebuilt_lyrics` 用于精确回灌写词结果，与顶层 `lyrics` 互斥。
</Warning>

<Warning>
  `attachments` 仅支持 `audio` 类型，且需提供可公开访问的 URL。
</Warning>

<Warning>
  `audio_settings.format` 支持 `mp3`、`wav`、`wav32`。
</Warning>


# 查询歌曲任务
Source: https://docs.senseaudio.cn/api-reference/endpoint/music/song-pending

api-reference/endpoint/music/music.openapi.json GET /v1/music/song/pending/{task_id}
查询 V1 或 V2 异步歌曲任务的状态和生成结果

## 说明

根据 `task_id` 查询 V1 或 V2 异步歌曲任务的状态和生成结果。建议在 `PENDING` 状态下间隔数秒轮询。

<Info>
  `status` 可能为 `PENDING`、`SUCCESS` 或 `FAILED`。仅 `SUCCESS` 时 `response.data` 包含完整歌曲。
</Info>


# 音效生成
Source: https://docs.senseaudio.cn/api-reference/endpoint/sfx/create

api-reference/endpoint/sfx/sfx.openapi.json POST /v1/sound-effects/generations
根据文本描述同步生成 1-4 个音效变体

## 说明

根据文本描述同步生成 1-4 个音效变体，默认模型为 `senseaudio-sfx-1.0-260626`，完成媒体校验、文件上传和实际成功数量结算后返回结果。备注：按组计费，单组 0.08 元，单次最多生成 4 条。

<Info>
  至少一个变体成功时返回 HTTP 200，`status` 为 `completed` 或 `partial_success`；仅对成功变体计费。全部失败时返回业务错误并全额退款。
</Info>

<Warning>
  传入 `duration_seconds` 时会强制关闭 `smart_duration`，即使请求中 `smart_duration=true`。
</Warning>


# 同声传译 WebSocket
Source: https://docs.senseaudio.cn/api-reference/endpoint/simultaneous-interpretation/websocket

基于 WebSocket 的实时同声传译协议参考

## 说明

基于 WebSocket 的同声传译接口，支持实时语音识别、翻译与译文播报。通信包含 JSON 控制消息与二进制音频消息两类。

* **接入地址**：`wss://api.senseaudio.cn/ws/v1/audio/simulat-interpreting`
* **鉴权方式**：Bearer Token，格式 `Authorization: Bearer SENSEAUDIO_API_KEY`
* **音频格式**：PCM signed 16-bit little-endian，采样率 16000Hz，单声道
* **模型参数**：`sensenova-livetranslate-1.0`
* **计费单位**：按输入音频时长计费，详见 [计费说明](/guides/account/billing)
* **使用场景**：跨语言会议、实时交流、直播与国际活动

<Warning>
  - 音频必须为 **PCM 16-bit little-endian / 16kHz / 单声道**。
  - 控制消息必须以 **JSON 文本帧** 发送，音频数据必须以 **二进制帧** 发送。
  - 客户端需等待 `connected_success` 后再发送 `task_start`，等待 `task_started` 后再开始推送音频。
  - 当前 API 不支持断线恢复，连接断开后需要重新建立连接并创建新任务。
</Warning>

## 请求头 (Request Headers)

| 参数名               | 必填 | 说明                                      | 示例                  |
| :---------------- | :- | :-------------------------------------- | :------------------ |
| **Authorization** | 是  | 鉴权 Token。格式：Bearer SENSEAUDIO\_API\_KEY | Bearer sk-123456... |

***

## 通信流程

```
1. 客户端建立 WebSocket 连接
   ↓
2. 服务端返回 connected_success 事件
   ↓
3. 客户端发送 task_start 事件
   ↓
4. 服务端返回 task_started 事件
   ↓
5. 客户端持续发送二进制 PCM 音频帧
   ↓
6. 服务端返回原文、译文、译文 TTS 事件
   ↓
7. 客户端发送 task_finish 事件
   ↓
8. 服务端返回 task_finished 事件并关闭连接
```

```mermaid theme={null}
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端

    Client->>Server: WebSocket Connect + Authorization
    Server-->>Client: connected_success
    Client->>Server: task_start (JSON)
    Server-->>Client: task_started

    loop 实时推流
        Client->>Server: PCM Audio (binary)
        Server-->>Client: si_segment_start
        Server-->>Client: si_token
        opt 启用译文 TTS
            Server-->>Client: si_tts_start
            Server-->>Client: si_tts_file
            Server-->>Client: si_tts_end
        end
        Server-->>Client: si_segment_done
    end

    Client->>Server: task_finish (JSON)
    Server-->>Client: task_finished
    Server-->>Client: Close Connection
```

***

## 客户端事件

### 1. task\_start - 开始任务

客户端收到 `connected_success` 后发送 `task_start` 事件配置参数。服务端返回 `task_started` 后方可开始推送二进制音频帧。

**请求参数**

| 参数名                       | 类型     | 必填 | 说明                                      |
| :------------------------ | :----- | :- | :-------------------------------------- |
| **event**                 | string | 是  | 固定值：`task_start`                        |
| **model**                 | string | 是  | 模型名称，目前使用 `sensenova-livetranslate-1.0` |
| **audio\_setting**        | object | 是  | 音频参数设置                                  |
| **vad\_setting**          | object | 否  | VAD（语音活动检测）设置                           |
| **voice\_input\_setting** | object | 否  | 源语言与目标语言设置                              |
| **tts\_setting**          | object | 否  | 译文 TTS 输出设置                             |

#### audio\_setting

| 参数名              | 类型     | 必填 | 说明                 |
| :--------------- | :----- | :- | :----------------- |
| **sample\_rate** | int    | 是  | 采样率，目前仅支持 `16000`  |
| **channel**      | int    | 是  | 声道数，目前仅支持 `1`（单声道） |
| **format**       | string | 是  | 音频格式，目前仅支持 `pcm`   |

#### vad\_setting（可选）

| 参数名                         | 类型     | 说明                   | 默认值   |
| :-------------------------- | :----- | :------------------- | :---- |
| **threshold**               | number | VAD 阈值，有效范围 `(0, 1]` | 0.45  |
| **silence\_duration**       | int    | 静音断句时长，单位 ms         | 500   |
| **min\_speech\_duration**   | int    | 最短语音时长，单位 ms         | 500   |
| **soft\_max\_duration**     | int    | 分句软上限，单位 ms          | 10000 |
| **hard\_max\_duration**     | int    | 分句硬上限，单位 ms          | 20000 |
| **soft\_silence\_duration** | int    | 达到软上限后的静音断句时长，单位 ms  | 250   |

#### voice\_input\_setting

| 参数名                  | 类型        | 必填 | 说明                                   |
| :------------------- | :-------- | :- | :----------------------------------- |
| **language**         | string    | 否  | 输入语言，例如 `Chinese`、`English`          |
| **target\_language** | string    | 否  | 目标语言，例如 `English`、`Chinese`；为空时不生成译文 |
| **hot\_words**       | string\[] | 否  | 热词列表                                 |
| **abbreviations**    | object    | 否  | 缩写或专有词映射，键为原词，值为期望内容                 |

当前可用的输入语言与目标语言包括：

* `Chinese`
* `English`
* `Japanese`
* `Korean`
* `Cantonese`
* `German`
* `French`
* `Spanish`
* `Portuguese`
* `Italian`
* `Russian`

#### tts\_setting

| 字段            | 类型      | 默认值   | 说明                           |
| ------------- | ------- | ----- | ---------------------------- |
| **enable**    | boolean | false | 是否生成译文 TTS 音频                |
| **mode**      | string  | 空     | TTS 模式；可选 `clone` 或 `preset` |
| **voice\_id** | string  | 空     | TTS 音色 ID；启用 TTS 时应传入可用音色    |

**请求示例**

```json theme={null}
{
  "event": "task_start",
  "model": "sensenova-livetranslate-1.0",
  "audio_setting": {
    "sample_rate": 16000,
    "format": "pcm",
    "channel": 1
  },
  "voice_input_setting": {
    "language": "Chinese",
    "target_language": "English"
  },
  "tts_setting": {
    "enable": false
  }
}
```

任务启动成功后，服务端返回 `task_started`。

### 2. 发送音频

音频通过 WebSocket 二进制消息发送，不要放入 JSON，也不要进行 Base64 编码。

音频必须符合以下要求：

* PCM signed 16-bit
* 小端序（little-endian）
* 采样率 16000Hz
* 单声道

建议每次发送约 100ms 音频，即 3200 字节。

### 3. task\_finish

音频发送完成后，客户端发送：

```json theme={null}
{
  "event": "task_finish"
}
```

发送 `task_finish` 后，不要继续发送音频或其他业务事件。服务端会继续处理已经接收的剩余音频，随后返回 `task_finished`。

***

## 服务端事件

| 事件                  | 说明                       |
| ------------------- | ------------------------ |
| `connected_success` | 连接建立成功                   |
| `task_started`      | 任务已开始，客户端收到后才能发送音频       |
| `si_segment_start`  | 同传分句开始                   |
| `si_token`          | 同传增量输出                   |
| `si_segment_done`   | 同传分句完成，包含原文与译文           |
| `si_segment_error`  | 同传分句处理失败                 |
| `si_tts_start`      | 译文 TTS 开始                |
| `si_tts_file`       | 译文 TTS 文件，包含 Base64 音频数据 |
| `si_tts_end`        | 译文 TTS 结束                |
| `heartbeat`         | 服务端心跳事件                  |
| `task_finished`     | 任务完成                     |
| `task_failed`       | 任务失败，包含错误码与错误信息          |

### 通用消息格式

除 WebSocket Ping 控制帧外，服务端业务事件均为 JSON 文本消息：

```json theme={null}
{
  "event": "connected_success",
  "session_id": "session-id-xxx",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

| 字段                      | 类型     | 说明                    |
| ----------------------- | ------ | --------------------- |
| `event`                 | string | 事件类型                  |
| `session_id`            | string | 当前 WebSocket 任务的会话 ID |
| `data`                  | object | 事件数据。没有数据时不返回该字段      |
| `base_resp.status_code` | int    | 状态码，`0` 表示成功          |
| `base_resp.status_msg`  | string | 状态详情                  |

***

## 错误处理

连接建立后的错误通过 `task_failed.base_resp` 返回。客户端应同时记录 `status_code`、`status_msg` 和 `session_id`。

常见错误包括：

* 首条消息不是 `task_start`
* 建立连接后长时间未发送 `task_start`
* 重复发送 `task_start`
* 在 `task_started` 前发送音频
* 在 `task_finish` 后继续发送音频
* 使用文本帧发送音频
* 使用二进制帧发送 JSON
* 输入音频不是 16000Hz、16-bit、单声道 PCM
* 模型不存在或不支持同声传译
* 余额不足或并发受限

***

## 调用示例

### Python

依赖：

```bash theme={null}
pip install websockets
```

示例代码：

```python theme={null}
import asyncio
import json
import os

import websockets

WS_URL = "wss://api.senseaudio.cn/ws/v1/audio/simulat-interpreting"
API_KEY = os.environ["SENSEAUDIO_API_KEY"]
AUDIO_FILE = "input_16k_s16le_mono.pcm"


async def wait_for_event(ws, expected):
    while True:
        message = json.loads(await ws.recv())
        if message.get("event") == "task_failed":
            raise RuntimeError((message.get("base_resp") or {}).get("status_msg"))
        if message.get("event") == expected:
            return message


async def receive_events(ws):
    async for raw in ws:
        message = json.loads(raw)
        event = message.get("event")
        data = message.get("data") or {}

        if event == "si_segment_done":
            print(f"原文: {data.get('original_text', '')}")
            print(f"译文: {data.get('text', '')}")
        elif event == "task_failed":
            raise RuntimeError((message.get("base_resp") or {}).get("status_msg"))
        elif event == "task_finished":
            return


async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with websockets.connect(WS_URL, additional_headers=headers) as ws:
        await wait_for_event(ws, "connected_success")

        await ws.send(json.dumps({
            "event": "task_start",
            "model": "sensenova-livetranslate-1.0",
            "audio_setting": {
                "sample_rate": 16000,
                "format": "pcm",
                "channel": 1,
            },
            "voice_input_setting": {
                "language": "Chinese",
                "target_language": "English",
            },
            "tts_setting": {"enable": False},
        }))
        await wait_for_event(ws, "task_started")

        receive_task = asyncio.create_task(receive_events(ws))

        with open(AUDIO_FILE, "rb") as audio:
            while chunk := audio.read(3200):
                await ws.send(chunk)
                await asyncio.sleep(0.1)

        await ws.send(json.dumps({"event": "task_finish"}))
        await receive_task


asyncio.run(main())
```

### Node.js

依赖：

```bash theme={null}
npm install ws
```

示例代码：

```javascript theme={null}
const fs = require('fs')
const WebSocket = require('ws')

const WS_URL = 'wss://api.senseaudio.cn/ws/v1/audio/simulat-interpreting'
const API_KEY = process.env.SENSEAUDIO_API_KEY
const AUDIO_FILE = 'input_16k_s16le_mono.pcm'

const ws = new WebSocket(WS_URL, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})

let audioStream = null

ws.on('message', (raw, isBinary) => {
  if (isBinary) return

  const message = JSON.parse(raw.toString())
  const event = message.event
  const data = message.data || {}

  switch (event) {
    case 'connected_success':
      ws.send(JSON.stringify({
        event: 'task_start',
        model: 'sensenova-livetranslate-1.0',
        audio_setting: {
          sample_rate: 16000,
          format: 'pcm',
          channel: 1,
        },
        voice_input_setting: {
          language: 'Chinese',
          target_language: 'English',
        },
        tts_setting: { enable: false },
      }))
      break

    case 'task_started':
      audioStream = fs.createReadStream(AUDIO_FILE, { highWaterMark: 3200 })
      audioStream.on('data', (chunk) => {
        audioStream.pause()
        ws.send(chunk, { binary: true }, () => {
          setTimeout(() => audioStream.resume(), 100)
        })
      })
      audioStream.on('end', () => {
        ws.send(JSON.stringify({ event: 'task_finish' }))
      })
      break

    case 'si_segment_done':
      console.log('原文:', data.original_text || '')
      console.log('译文:', data.text || '')
      break

    case 'task_failed':
      console.error('任务失败:', message.base_resp?.status_msg)
      break
  }
})
```

***

## 计费说明

请参考 [计费规则](/guides/account/billing)。

***

## 相关资源

<CardGroup>
  <Card title="同声传译介绍" icon="book-open" href="/guides/simultaneous-interpretation/overview">
    查看同声传译能力概览、使用场景与参数建议。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看同声传译模型与其他可调用模型。
  </Card>
</CardGroup>


# 端到端实时语音模型
Source: https://docs.senseaudio.cn/api-reference/endpoint/tts/end-to-end-wss

基于 WebSocket 的实时语音对话协议参考

## 说明

基于 WebSocket 的实时语音对话接口，支持客户端持续发送语音输入，服务端实时返回用户语音转写、模型文本回复与模型语音回复。文本帧均为 JSON，二进制帧用于传输 PCM 音频数据。

* **接入地址**：`wss://api.senseaudio.cn/ws/v1/realtime/voice-dialog`
* **鉴权方式**：Bearer Token，格式 `Authorization: Bearer SENSEAUDIO_API_KEY`
* **客户端文本帧**：JSON 文本帧，必须包含 `type` 字段
* **客户端音频帧**：`pcm_s16le`、采样率 `16000Hz`、单声道；建议每 `40ms` 发送一帧（`1280` 字节）
* **服务端音频帧**：`pcm_s16le`、采样率 `24000Hz`、单声道
* **计费单位**：按二进制帧传输的 PCM 音频总长度计费，不足 1 秒按 1 秒计

<Warning>
  - `start` 必须作为连接后的第一个客户端消息发送，且同一连接内不能重复发送。
  - 客户端必须等待服务端返回 `ready` 后，才能开始发送二进制音频帧。
  - `update` 不能修改 `model` 和 `audio_setting`。
  - `greeting` 非空时会产生独立的开场白轮次及其 `turn.done`。客户端不能把该事件误认为用户语音轮次结束。
</Warning>

## 请求头

| 参数名               | 必填 | 说明                                      | 示例                  |
| :---------------- | :- | :-------------------------------------- | :------------------ |
| **Authorization** | 是  | 鉴权 Token。格式：Bearer SENSEAUDIO\_API\_KEY | Bearer sk-123456... |

<Note>
  本文完整示例面向 Python 服务端程序。浏览器原生 `WebSocket` API 不能设置自定义 `Authorization` 请求头，也不应把长期 API Key 暴露在浏览器代码中；浏览器场景应通过受控后端代理或专用的短期鉴权机制接入。
</Note>

## 接入流程

```text theme={null}
1. 客户端建立 WebSocket 连接
   ↓
2. 客户端发送 start 事件，初始化模型与对话配置
   ↓
3. 服务端返回 ready 事件，表示模型连接建立完成
   ↓
4. greeting 非空时，服务端先返回开场白音频及对应的 turn.done
   ↓
5. 客户端按实时节奏发送 PCM 二进制音频帧
   ↓
6. 客户端发送 commit 手动提交本轮音频，或由服务端自动判断语音结束
   ↓
7. 服务端返回 user.transcript.done、模型文本回复与模型语音
   ↓
8. 服务端返回 turn.done；模型回复期间客户端可发送 cancel 打断回复
   ↓
9. 客户端发送 end 结束会话，服务端以关闭码 1000 正常关闭连接
```

```mermaid theme={null}
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端

    Client->>Server: WebSocket Connect (带 Auth Header)
    Client->>Server: JSON: {"type": "start", "model": "senseaudio-realtime-1.0", "greeting": ""}
    Server-->>Client: JSON: {"type": "ready", "session_id": "session_50173901836217346"}
    loop 连接期间每 40ms 一帧
        Client->>Server: Binary PCM audio frame (1280 bytes)
    end
    Server-->>Client: JSON: {"type": "speech.started"}
    Server-->>Client: JSON: {"type": "user.transcript.delta", "text": "今天天气怎么样？"}
    Note over Client,Server: 服务端 VAD 自动判断本轮结束；麦克风帧持续上行
    Server-->>Client: JSON: {"type": "user.transcript.done", "text": "今天天气怎么样？"}
    Server-->>Client: JSON: {"type": "assistant.text.delta", "text": "今天"}
    Server-->>Client: JSON: {"type": "assistant.audio.start", "response_id": "tts_3", "sample_rate": 24000, "format": "pcm_s16le"}
    Server-->>Client: Binary PCM audio frames
    Server-->>Client: JSON: {"type": "assistant.text.done", "text": "今天的天气……"}
    Server-->>Client: JSON: {"type": "assistant.audio.done", "response_id": "tts_3"}
    Server-->>Client: JSON: {"type": "turn.done"}
    Client->>Server: JSON: {"type": "end"}
    Server-->>Client: Close 1000
```

## 客户端事件

### 1. start - 开始语音对话

`start` 用于初始化实时语音对话，必须作为第一个消息发送。同一连接内重复发送 `start` 会触发 `bad_request`，服务端随后以 `1008` 断开连接。

**请求参数**

| 参数名                         | 类型      | 必填 | 说明                                            | 示例                        |
| :-------------------------- | :------ | :- | :-------------------------------------------- | :------------------------ |
| `type`                      | string  | 是  | 固定值：`start`                                   | `start`                   |
| `model`                     | string  | 是  | 模型 ID，当前仅支持 `senseaudio-realtime-1.0`         | `senseaudio-realtime-1.0` |
| `voice`                     | string  | 否  | 对话音色 ID；不传时由服务端选择默认音色，字面值 `default` 不是有效音色 ID | `f_y_0035_c`              |
| `instructions`              | string  | 否  | 系统提示词                                         | `你是SenseAudio助手`          |
| `greeting`                  | string  | 否  | 开场白，可以为空；非空时会产生独立的开场白轮次                       | `你好，我是SenseAudio语音助手`     |
| `audio_setting`             | object  | 否  | 输入音频设置，不传时使用默认配置                              | -                         |
| `audio_setting.sample_rate` | integer | 否  | 采样率，当前仅支持 `16000`                             | `16000`                   |
| `audio_setting.format`      | string  | 否  | 音频格式，当前仅支持 `pcm_s16le`                        | `pcm_s16le`               |
| `audio_setting.channel`     | integer | 否  | 声道数，当前仅支持 `1`                                 | `1`                       |
| `tools`                     | array   | 否  | 完整的函数工具架构数组，最多包含 32 个工具。省略或传空数组表示不启用函数调用      | `[]`                      |

**请求示例**

```json theme={null}
{
  "type": "start",
  "model": "senseaudio-realtime-1.0",
  "voice": "f_y_0035_c",
  "instructions": "你是SenseAudio助手",
  "greeting": "",
  "audio_setting": {
    "sample_rate": 16000,
    "format": "pcm_s16le",
    "channel": 1
  },
  "tools": [
    {
      "type": "function",
      "name": "query_weather",
      "description": "查询指定城市的当前天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市名称，例如上海"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "温度单位"
          }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ]
}
```

<Note>
  `greeting` 非空时，服务端会在 `ready` 后返回开场白音频，并以一个独立的 `turn.done` 结束该轮。若客户端需要等开场白播放完再上传用户语音，应先等待这个 `turn.done`；完整代码示例将 `greeting` 设为空，以便只演示用户语音轮次。
</Note>

### 2. update - 更新对话配置

`update` 用于在已经开始的对话中修改配置。除 `type` 外，至少需要包含一个可更新字段；未包含的字段保持不变。无效音色等可恢复错误不会断开连接。发送 `model`、`audio_setting` 或其他不支持的字段会触发致命的 `bad_request`，服务端随后以 `1008` 断开连接。

<Note>
  `update` 不支持修改 `model` 和 `audio_setting`。
</Note>

**请求参数**

| 参数名            | 类型     | 必填 | 说明                                       | 示例               |
| :------------- | :----- | :- | :--------------------------------------- | :--------------- |
| `type`         | string | 是  | 固定值：`update`                             | `update`         |
| `voice`        | string | 否  | 更新对话音色 ID，必须使用“音色列表”中的值；字面值 `default` 无效 | `f_y_0035_c`     |
| `instructions` | string | 否  | 更新系统提示词                                  | `你是SenseAudio助手` |

**请求示例**

```json theme={null}
{
  "type": "update",
  "voice": "f_y_0035_c",
  "instructions": "你是SenseAudio助手"
}
```

### 3. 音频流传输（二进制消息）

客户端必须在收到服务端 `ready` 后发送二进制音频帧。

* **格式**：`pcm_s16le`
* **采样率**：`16000Hz`
* **声道数**：`1`
* **推荐帧长**：`40ms`，即 `640` 个采样点、`1280` 字节
* **发送节奏**：按音频实际时长发送，不要将整个文件作为一个大二进制消息突发上传
* **计费规则**：按二进制帧传输的 PCM 音频总长度计费，不足 1 秒按 1 秒计

### 4. commit - 手动提交本轮音频

`commit` 用于手动提交当前已缓冲的音频，表示此轮用户音频输入结束。后续二进制帧不属于已提交的这一轮，而会进入新的输入缓冲。

```json theme={null}
{ "type": "commit" }
```

<Warning>
  `commit` 不会关闭 WebSocket 或持续麦克风流。实时客户端通常会继续发送麦克风帧，以支持下一轮输入和打断。
</Warning>

### 5. cancel - 打断模型回复

`cancel` 用于打断并取消当前模型回复。

```json theme={null}
{ "type": "cancel" }
```

### 6. tool.result - 工具调用结果

客户端收到 `tool.call` 并执行完成后回传。`call_id` 必须原样回传 `tool.call.call_id`。`result` 必须可序列化为 JSON，大小不能超过 32 KiB。

```json theme={null}
{
  "type": "tool.result",
  "call_id": "call_weather_1",
  "result": {
    "city": "上海",
    "temperature": 31,
    "unit": "celsius"
  }
}
```

若某个客户端工具完成后需要先播报一句话再结束 AI 会话，可在成功的 `tool.result` 中附加通用动作 `session_action`。工具名称和业务含义不写死，客户端按自身业务决定何时附加该动作。

```json theme={null}
{
  "type": "tool.result",
  "call_id": "call_action_1",
  "result": {
    "status": "accepted",
    "reason": "用户明确要求人工客服"
  },
  "session_action": {
    "type": "announce_and_close",
    "text": "好的，正在为您转接人工中……"
  }
}
```

`session_action` 只能附加在包含 `result` 的帧上。`session_action.text` 必须是非空字符串，最长 500 个字符。无效的 `session_action` 会触发致命 `error` 并关闭连接。

### 7. end - 结束对话

`end` 用于结束当前对话。服务端收到后会以 `1000` 关闭 WebSocket 连接。

```json theme={null}
{ "type": "end" }
```

## 函数调用

在 `start` 中通过 `tools` 注册客户端可执行的函数。省略 `tools` 或传空数组表示不启用函数调用。

### `tools` 字段

| 参数名     | 类型    | 必填 | 说明                      | 示例   |
| :------ | :---- | :- | :---------------------- | :--- |
| `tools` | array | 否  | 完整的函数工具架构数组，最多包含 32 个工具 | `[]` |

### 函数工具架构

| 字段            | 类型     | 必填 | 说明                                               |
| :------------ | :----- | :- | :----------------------------------------------- |
| `type`        | string | 是  | 固定为 `function`                                   |
| `name`        | string | 是  | 工具名称，最长 64 个字符，只能包含字母、数字、`_`、`-`，且不能有首尾空格        |
| `description` | string | 否  | 帮助模型判断何时调用工具，最长 2048 个字符                         |
| `parameters`  | object | 是  | Draft 2020-12 JSON Schema，顶层 `type` 必须为 `object` |

### 请求示例

```json theme={null}
{
  "type": "start",
  "model": "senseaudio-realtime-1.0",
  "voice": "f_y_0035_c",
  "instructions": "你是SenseAudio助手",
  "greeting": "",
  "audio_setting": {
    "sample_rate": 16000,
    "format": "pcm_s16le",
    "channel": 1
  },
  "tools": [
    {
      "type": "function",
      "name": "query_weather",
      "description": "查询指定城市的当前天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市名称，例如上海"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "温度单位"
          }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ]
}
```

### 调用流程

1. 在 `start` 中传入 `tools`。
2. 模型触发工具调用后，服务端下发 `tool.call`。
3. 客户端执行对应的工具处理器，并用同一 `call_id` 回传 `tool.result`。
4. 若客户端发送 `cancel`，服务端会下发 `tool.cancelled`。

## 服务端事件

### tool.call - 工具调用请求

模型触发函数调用时，服务端会下发该事件。客户端收到后应执行本地处理器，并回传同一 `call_id` 的 `tool.result`。

```json theme={null}
{
  "type": "tool.call",
  "batch_id": "event_12",
  "call_id": "call_weather_1",
  "name": "query_weather",
  "arguments": {
    "city": "上海",
    "unit": "celsius"
  },
  "timeout_ms": 30000
}
```

### tool.cancelled - 工具调用取消

当客户端显式发送 `cancel`，或工具调用超时，服务端会下发该事件。

```json theme={null}
{
  "type": "tool.cancelled",
  "call_id": "call_weather_1",
  "reason": "timeout"
}
```

### session.action.completed - 会话动作完成

`announce_and_close` 会依次产生 `assistant.text.done`、`assistant.audio.start`、二进制音频帧和 `assistant.audio.done`。播报完成后，服务端发送 `session.action.completed` 并关闭 WebSocket。此流程不返回 `turn.done`。

```json theme={null}
{
  "type": "session.action.completed",
  "action": "announce_and_close",
  "call_id": "call_action_1",
  "message": "好的，正在为您转接人工中……"
}
```

### ready - 连接就绪

表示服务端到模型的连接已经建立，可以开始发送音频数据。若 `start.greeting` 非空，`ready` 后还会收到一轮开场白事件；该轮也会以 `turn.done` 结束。

```json theme={null}
{
  "type": "ready",
  "session_id": "session_50173901836217346"
}
```

### speech.started - 检测到用户开口

表示服务端检测到用户已经开始说话。

```json theme={null}
{ "type": "speech.started" }
```

### user.transcript.delta - 用户转写增量

用户语音转写的增量结果。该结果会随用户语音输入逐渐修正，前端渲染时建议使用最新值替换展示。

```json theme={null}
{
  "type": "user.transcript.delta",
  "text": "今天天气怎么样？"
}
```

### user.transcript.done - 用户转写最终稿

用户语音结束后返回的最终转写结果。语音结束包括服务端自动判断结束和客户端手动 `commit` 提交。

```json theme={null}
{
  "type": "user.transcript.done",
  "text": "今天天气怎么样？"
}
```

### assistant.text.delta - 模型回复文本增量

模型回复文本的增量片段。客户端需要将本字段追加到之前收到的文本后，得到当前模型回复内容。

```json theme={null}
{
  "type": "assistant.text.delta",
  "text": "今天"
}
```

### assistant.text.done - 模型回复文本全文

本轮模型回复文本的完整内容。

```json theme={null}
{
  "type": "assistant.text.done",
  "text": "今天的天气情况可以打开天气应用查看。如果你告诉我所在城市，我可以帮你整理出行建议。"
}
```

### assistant.audio.start - 模型回复音频开始

表示模型回复音频开始。之后收到的二进制帧均为本轮模型回复音频。当前服务端输出为单声道 PCM。

```json theme={null}
{
  "type": "assistant.audio.start",
  "response_id": "tts_3",
  "sample_rate": 24000,
  "format": "pcm_s16le"
}
```

### assistant.audio.done - 模型回复音频结束

表示本轮模型回复音频结束，`response_id` 与 `assistant.audio.start` 中的 `response_id` 一致。

```json theme={null}
{
  "type": "assistant.audio.done",
  "response_id": "tts_3"
}
```

### turn.done - 本轮结束

表示一个对话轮次结束。非空 `greeting` 的开场白轮次和每个用户语音轮次都会分别返回 `turn.done`；客户端应维护会话状态，不能无条件在第一个 `turn.done` 后结束连接。

```json theme={null}
{ "type": "turn.done" }
```

### error - 错误通知

发生错误时，服务端返回 `error`。错误分为致命错误和非致命错误；致命错误会在服务端发送该消息后断开 WebSocket，非致命错误不会断开连接。

```json theme={null}
{
  "type": "error",
  "code": "bad_request",
  "message": "客户端发送的 start 消息配置无效"
}
```

## 使用示例

<ExampleHtmlDownload />

以下示例直接采集系统麦克风，并把模型返回的音频实时播放到扬声器。建议使用耳机，避免扬声器声音被麦克风重新采集后触发误识别或错误打断。

运行前先设置 API Key：

```bash theme={null}
export SENSEAUDIO_API_KEY='YOUR_API_KEY'
```

示例在收到 `ready` 后持续上传 `16000Hz / 单声道 / pcm_s16le` 麦克风帧，由服务端 VAD 自动判断每轮语音结束，因此不会主动发送 `commit`。模型音频按服务端声明的 `24000Hz / 单声道 / pcm_s16le` 实时播放；普通 `turn.done` 只表示一轮完成，连接会继续用于下一轮。正常使用时按 `Ctrl+C` 发送 `end`。当服务端在模型播报期间返回 `speech.started` 时，示例会发送一次 `cancel` 并清除尚未播放的旧回复。若 `greeting` 非空，示例会先播完开场白再开启麦克风，避免开场白回采形成错误的用户轮次。
依赖：**Python 3.9+、`websocket-client` 和 `sounddevice`**

`sounddevice` 基于 PortAudio。Windows 和 macOS 的 pip 包通常包含 PortAudio；Linux 如果安装或运行时报 PortAudio 错误，需要先通过系统包管理器安装运行库，例如 Ubuntu / Debian 可执行 `sudo apt-get install libportaudio2`。

示例中的 `query_weather` 返回固定的模拟天气。接入真实工具时，请替换 `handle_tool_call` 中的业务逻辑，并保留参数校验、超时和取消处理。

```python realtime_voice.py expandable theme={null}
import json
import os
import queue
import sys
import threading
import time

import sounddevice as sd
import websocket


def parse_device(name):
    value = os.environ.get(name)
    if not value:
        return None
    try:
        return int(value)
    except ValueError:
        return value


if "--list-devices" in sys.argv:
    print(sd.query_devices())
    raise SystemExit(0)


API_KEY = os.environ.get("SENSEAUDIO_API_KEY")
WS_URL = os.environ.get(
    "SENSEAUDIO_WS_URL",
    "wss://api.senseaudio.cn/ws/v1/realtime/voice-dialog",
)
GREETING = os.environ.get("SENSEAUDIO_GREETING", "")
VOICE = os.environ.get("SENSEAUDIO_VOICE", "")
INPUT_DEVICE = parse_device("SENSEAUDIO_INPUT_DEVICE")
OUTPUT_DEVICE = parse_device("SENSEAUDIO_OUTPUT_DEVICE")

INPUT_SAMPLE_RATE = 16000
INPUT_BLOCK_FRAMES = 640       # 40ms
OUTPUT_SAMPLE_RATE = 24000
OUTPUT_BLOCK_FRAMES = 480      # 20ms，降低打断后的播放尾音
OUTPUT_BLOCK_BYTES = OUTPUT_BLOCK_FRAMES * 2
MIC_QUEUE_BLOCKS = 25          # 最多缓存约 1 秒上行音频
PLAY_QUEUE_BLOCKS = 3000       # 最多缓存约 60 秒下行音频

if not API_KEY:
    raise RuntimeError("请先设置 SENSEAUDIO_API_KEY 环境变量")


class RealtimeVoiceClient:
    def __init__(self):
        self.stop_event = threading.Event()
        self.closed_event = threading.Event()
        self.mic_enabled = threading.Event()
        self.start_sent = threading.Event()
        self.fatal_event = threading.Event()
        self.mic_dropped = threading.Event()
        self.input_warning = threading.Event()
        self.playback_backlog = threading.Event()
        self.output_busy = threading.Event()

        self.mic_queue = queue.Queue(maxsize=MIC_QUEUE_BLOCKS)
        self.play_queue = queue.Queue(maxsize=PLAY_QUEUE_BLOCKS)
        self.state_lock = threading.Lock()
        self.send_lock = threading.Lock()
        self.output_stream_lock = threading.Lock()

        self.waiting_greeting = bool(GREETING)
        self.response_active = False
        self.downlink_audio_active = False
        self.cancel_sent = False
        self.drop_current_response = False
        self.assistant_text_started = False
        self.playback_epoch = 0
        self.downlink_buffer = bytearray()
        self.ending = False
        self.fatal_reason = None
        self.pending_tool_calls = {}

        self.input_stream = None
        self.output_stream = None
        self.uplink_thread = None
        self.output_thread = None
        self.websocket_thread = None

        self.ws = websocket.WebSocketApp(
            WS_URL,
            header=[f"Authorization: Bearer {API_KEY}"],
            on_open=self.on_open,
            on_message=self.on_message,
            on_close=self.on_close,
            on_error=self.on_error,
        )

    def set_fatal(self, reason):
        with self.state_lock:
            if self.fatal_reason is None:
                self.fatal_reason = reason
        self.fatal_event.set()

    def send_json(self, payload):
        message = json.dumps(payload, ensure_ascii=False)
        with self.send_lock:
            self.ws.send(message)

    def send_binary(self, payload):
        with self.send_lock:
            if self.stop_event.is_set():
                return False
            self.ws.send(payload, opcode=websocket.ABNF.OPCODE_BINARY)
            return True

    def dispatch_tool_call(self, event):
        call_id = event.get("call_id")
        if not isinstance(call_id, str) or not call_id:
            print("\n忽略缺少 call_id 的工具调用")
            return

        cancel_event = threading.Event()
        with self.state_lock:
            if call_id in self.pending_tool_calls:
                print(f"\n忽略重复的工具调用：{call_id}")
                return
            self.pending_tool_calls[call_id] = cancel_event

        threading.Thread(
            target=self.handle_tool_call,
            args=(event, cancel_event),
            name=f"senseaudio-tool-{call_id}",
            daemon=True,
        ).start()

    def handle_tool_call(self, event, cancel_event):
        call_id = event["call_id"]
        timeout_ms = event.get("timeout_ms", 30000)
        if not isinstance(timeout_ms, int) or timeout_ms <= 0:
            timeout_ms = 30000
        deadline = time.monotonic() + timeout_ms / 1000

        try:
            name = event.get("name")
            arguments = event.get("arguments")

            if name != "query_weather":
                result = {
                    "error": {
                        "code": "unsupported_tool",
                        "message": f"不支持工具 {name}",
                    }
                }
            elif not isinstance(arguments, dict):
                result = {
                    "error": {
                        "code": "invalid_arguments",
                        "message": "arguments 必须是 JSON 对象",
                    }
                }
            else:
                city = arguments.get("city")
                unit = arguments.get("unit", "celsius")
                if not isinstance(city, str) or not city.strip():
                    result = {
                        "error": {
                            "code": "invalid_arguments",
                            "message": "city 必须是非空字符串",
                        }
                    }
                elif unit not in {"celsius", "fahrenheit"}:
                    result = {
                        "error": {
                            "code": "invalid_arguments",
                            "message": "unit 必须是 celsius 或 fahrenheit",
                        }
                    }
                else:
                    # 模拟结果。真实工具 I/O 也应在此工作线程中执行。
                    result = {
                        "city": city,
                        "temperature": 31,
                        "unit": unit,
                    }

            if (
                cancel_event.is_set()
                or self.stop_event.is_set()
                or time.monotonic() >= deadline
            ):
                return

            self.send_json(
                {
                    "type": "tool.result",
                    "call_id": call_id,
                    "result": result,
                }
            )
        except websocket.WebSocketConnectionClosedException:
            pass
        except Exception as error:
            print(f"\n工具调用失败：{error}")
        finally:
            with self.state_lock:
                if self.pending_tool_calls.get(call_id) is cancel_event:
                    del self.pending_tool_calls[call_id]

    def handle_tool_cancelled(self, event):
        call_id = event.get("call_id")
        with self.state_lock:
            cancel_event = self.pending_tool_calls.pop(call_id, None)
        if cancel_event is not None:
            cancel_event.set()
        print(
            f"\n工具调用已取消：{call_id or 'unknown'} "
            f"({event.get('reason', '')})"
        )

    # PortAudio 实时回调中不能执行网络请求、打印或其他阻塞操作。
    def input_callback(self, indata, frames, time_info, status):
        if status:
            self.input_warning.set()
        if self.stop_event.is_set() or not self.mic_enabled.is_set():
            return

        # indata 的内存在回调返回后会被复用，必须复制。
        payload = bytes(indata)
        try:
            self.mic_queue.put_nowait(payload)
        except queue.Full:
            # 实时对话优先保留最新音频，避免积压带来数秒延迟。
            self.mic_dropped.set()
            try:
                self.mic_queue.get_nowait()
                self.mic_queue.task_done()
            except queue.Empty:
                pass
            try:
                self.mic_queue.put_nowait(payload)
            except queue.Full:
                pass

    def uplink_worker(self):
        try:
            next_send_at = time.monotonic()
            while not self.stop_event.is_set():
                try:
                    payload = self.mic_queue.get(timeout=0.1)
                except queue.Empty:
                    continue
                try:
                    if self.mic_enabled.is_set():
                        # 即使虚拟设备突发产帧，也按 PCM 实际时长发送。
                        now = time.monotonic()
                        if next_send_at < now - 1:
                            next_send_at = now
                        if self.stop_event.wait(max(0, next_send_at - now)):
                            return
                        if not self.send_binary(payload):
                            return
                        next_send_at = max(next_send_at, now) + (
                            len(payload) / (INPUT_SAMPLE_RATE * 2)
                        )
                finally:
                    self.mic_queue.task_done()
        except websocket.WebSocketConnectionClosedException:
            pass
        except Exception as error:
            self.set_fatal(f"发送麦克风音频失败：{error}")

    def output_worker(self):
        try:
            while not self.stop_event.is_set():
                try:
                    epoch, payload = self.play_queue.get(timeout=0.1)
                except queue.Empty:
                    continue
                try:
                    with self.output_stream_lock:
                        with self.state_lock:
                            valid = (
                                epoch == self.playback_epoch
                                and not self.drop_current_response
                            )
                        if valid and not self.stop_event.is_set():
                            self.output_busy.set()
                            try:
                                self.output_stream.write(payload)
                            finally:
                                self.output_busy.clear()
                finally:
                    self.play_queue.task_done()
        except Exception as error:
            if not self.stop_event.is_set():
                self.set_fatal(f"播放模型音频失败：{error}")

    def clear_playback_queue(self):
        while True:
            try:
                self.play_queue.get_nowait()
            except queue.Empty:
                return
            else:
                self.play_queue.task_done()

    def enqueue_playback(self, epoch, payload):
        try:
            self.play_queue.put_nowait((epoch, payload))
        except queue.Full:
            self.playback_backlog.set()
            try:
                self.play_queue.get_nowait()
                self.play_queue.task_done()
            except queue.Empty:
                pass
            try:
                self.play_queue.put_nowait((epoch, payload))
            except queue.Full:
                self.set_fatal("扬声器播放队列持续堆积，请检查输出设备或降低播放负载")

    def handle_binary_audio(self, message):
        payload = bytes(message)
        with self.state_lock:
            if (
                not self.downlink_audio_active
                or self.drop_current_response
                or self.ending
            ):
                return
            epoch = self.playback_epoch

        self.downlink_buffer.extend(payload)
        while len(self.downlink_buffer) >= OUTPUT_BLOCK_BYTES:
            block = bytes(self.downlink_buffer[:OUTPUT_BLOCK_BYTES])
            del self.downlink_buffer[:OUTPUT_BLOCK_BYTES]
            self.enqueue_playback(epoch, block)

    def finish_downlink_audio(self):
        with self.state_lock:
            valid = (
                self.downlink_audio_active
                and not self.drop_current_response
                and not self.ending
            )
            epoch = self.playback_epoch
            self.downlink_audio_active = False

        if valid and self.downlink_buffer:
            if len(self.downlink_buffer) % 2:
                self.set_fatal("服务端返回了长度不是 16-bit 对齐的 PCM 音频")
            else:
                self.enqueue_playback(epoch, bytes(self.downlink_buffer))
        self.downlink_buffer.clear()

    def interrupt_assistant(self):
        with self.state_lock:
            had_audio = (
                self.downlink_audio_active
                or not self.play_queue.empty()
                or self.output_busy.is_set()
            )
            self.playback_epoch += 1
            should_cancel = (
                self.response_active
                and not self.cancel_sent
                and not self.ending
            )
            self.response_active = False
            self.downlink_audio_active = False
            if should_cancel:
                self.cancel_sent = True
                self.drop_current_response = True

        self.downlink_buffer.clear()
        self.clear_playback_queue()

        if had_audio and self.output_stream is not None:
            try:
                with self.output_stream_lock:
                    self.output_stream.abort(ignore_errors=False)
                    if not self.stop_event.is_set():
                        self.output_stream.start()
            except Exception as error:
                self.set_fatal(f"重置扬声器失败：{error}")

        if should_cancel:
            print("\n检测到用户打断，已取消当前模型回复")
            try:
                self.send_json({"type": "cancel"})
            except websocket.WebSocketConnectionClosedException:
                pass

    def enable_mic_after_greeting(self):
        # turn.done 到达时开场白二进制帧已经全部入队，排空后再开麦避免回声。
        self.play_queue.join()
        if self.stop_event.is_set():
            return
        try:
            with self.output_stream_lock:
                # stop() 会等待 PortAudio 和硬件中的待播缓冲全部完成。
                self.output_stream.stop(ignore_errors=False)
                if self.stop_event.is_set():
                    return
                self.output_stream.start()
        except Exception as error:
            self.set_fatal(f"等待开场白播放完成失败：{error}")
            return
        self.mic_enabled.set()
        print("开场白播放完成，可以开始说话；按 Ctrl+C 结束会话")

    def request_end(self, reason):
        with self.state_lock:
            if self.ending:
                return
            self.ending = True
            self.playback_epoch += 1
            tool_cancellations = list(self.pending_tool_calls.values())
            self.pending_tool_calls.clear()

        print(f"\n结束会话：{reason}")
        for cancel_event in tool_cancellations:
            cancel_event.set()
        self.mic_enabled.clear()
        self.stop_event.set()
        self.downlink_buffer.clear()
        self.clear_playback_queue()

        if self.start_sent.is_set():
            threading.Thread(
                target=self.send_end,
                name="senseaudio-end",
                daemon=True,
            ).start()
        else:
            self.abort_websocket()

    def send_end(self):
        try:
            self.send_json({"type": "end"})
        except Exception:
            self.abort_websocket()

    def abort_websocket(self):
        # 低层 abort 可唤醒卡在 send()/recv() 中的线程。
        sock = self.ws.sock
        if sock is not None:
            try:
                sock.abort()
            except Exception:
                pass

    def on_open(self, ws):
        if self.stop_event.is_set():
            self.abort_websocket()
            return

        start = {
            "type": "start",
            "model": "senseaudio-realtime-1.0",
            "instructions": "你是SenseAudio助手",
            "greeting": GREETING,
            "audio_setting": {
                "sample_rate": INPUT_SAMPLE_RATE,
                "format": "pcm_s16le",
                "channel": 1,
            },
            "tools": [
                {
                    "type": "function",
                    "name": "query_weather",
                    "description": "查询指定城市的当前天气",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "description": "城市名称，例如上海",
                            },
                            "unit": {
                                "type": "string",
                                "enum": ["celsius", "fahrenheit"],
                                "description": "温度单位",
                            },
                        },
                        "required": ["city"],
                        "additionalProperties": False,
                    },
                },
            ],
        }
        if VOICE:
            start["voice"] = VOICE

        try:
            self.send_json(start)
            self.start_sent.set()
        except Exception as error:
            self.set_fatal(f"发送 start 失败：{error}")

    def on_message(self, ws, message):
        if self.stop_event.is_set():
            return

        if isinstance(message, (bytes, bytearray, memoryview)):
            self.handle_binary_audio(message)
            return

        try:
            event = json.loads(message)
        except json.JSONDecodeError as error:
            self.set_fatal(f"服务端返回了无效 JSON：{error}")
            return

        event_type = event.get("type")

        if event_type == "ready":
            if self.waiting_greeting:
                print("连接已就绪，正在播放开场白")
            else:
                self.mic_enabled.set()
                print("可以开始说话；按 Ctrl+C 结束会话")
            return

        if event_type == "speech.started":
            self.interrupt_assistant()
            return

        if event_type == "user.transcript.delta":
            print(f"\r用户转写中：{event.get('text', '')}", end="", flush=True)
            return

        if event_type == "user.transcript.done":
            with self.state_lock:
                # 新用户轮次开始生成回复，解除上一轮 cancel 的丢弃状态。
                self.cancel_sent = False
                self.drop_current_response = False
                self.response_active = True
                self.assistant_text_started = False
            print(f"\n你：{event.get('text', '')}")
            return

        if event_type == "assistant.text.delta":
            with self.state_lock:
                if self.drop_current_response:
                    return
                self.response_active = True
                first_delta = not self.assistant_text_started
                self.assistant_text_started = True
            if first_delta:
                print("\n助手：", end="", flush=True)
            print(event.get("text", ""), end="", flush=True)
            return

        if event_type == "assistant.text.done":
            with self.state_lock:
                suppressed = self.drop_current_response
                text_started = self.assistant_text_started
                if not suppressed:
                    self.response_active = True
                    self.assistant_text_started = False
            if suppressed:
                return
            if text_started:
                print()
            elif event.get("text"):
                print(f"\n助手：{event['text']}")
            return

        if event_type == "assistant.audio.start":
            if (
                event.get("sample_rate") != OUTPUT_SAMPLE_RATE
                or event.get("format") != "pcm_s16le"
            ):
                self.set_fatal("服务端输出音频不是预期的 pcm_s16le / 24000Hz")
                return
            self.downlink_buffer.clear()
            with self.state_lock:
                self.downlink_audio_active = True
                if not self.drop_current_response:
                    self.response_active = True
            return

        if event_type == "assistant.audio.done":
            self.finish_downlink_audio()
            return

        if event_type == "tool.call":
            self.dispatch_tool_call(event)
            return

        if event_type == "tool.cancelled":
            self.handle_tool_cancelled(event)
            return

        if event_type == "session.action.completed":
            print(f"\n会话动作完成：{event.get('action', '')}")
            return

        if event_type == "turn.done":
            # 正常情况下 audio.done 已先到达；这里也做一次幂等收尾。
            self.finish_downlink_audio()
            with self.state_lock:
                greeting_done = self.waiting_greeting
                text_incomplete = self.assistant_text_started
                self.waiting_greeting = False
                self.response_active = False
                self.downlink_audio_active = False
                self.cancel_sent = False
                self.drop_current_response = False
                self.assistant_text_started = False

            if text_incomplete:
                print()
            if greeting_done:
                threading.Thread(
                    target=self.enable_mic_after_greeting,
                    name="senseaudio-greeting-drain",
                    daemon=True,
                ).start()
            else:
                print("本轮结束，继续监听麦克风")
            return

        if event_type == "error":
            print(
                "\n服务端错误："
                f"{event.get('code', 'unknown')} - {event.get('message', '')}"
            )
            if event.get("code") == "no_active_response":
                with self.state_lock:
                    self.cancel_sent = False
                    self.drop_current_response = False
                    self.response_active = False
                    self.assistant_text_started = False
            return

        print("收到未知服务端事件：", event)

    def on_close(self, ws, code, reason):
        self.mic_enabled.clear()
        self.stop_event.set()
        self.closed_event.set()
        print(f"\n连接关闭：{code} {reason or ''}")

    def on_error(self, ws, error):
        if not self.ending:
            print(f"\n连接错误：{error}")

    def open_audio_devices(self):
        try:
            sd.check_input_settings(
                device=INPUT_DEVICE,
                channels=1,
                dtype="int16",
                samplerate=INPUT_SAMPLE_RATE,
            )
            sd.check_output_settings(
                device=OUTPUT_DEVICE,
                channels=1,
                dtype="int16",
                samplerate=OUTPUT_SAMPLE_RATE,
            )
            self.input_stream = sd.RawInputStream(
                device=INPUT_DEVICE,
                samplerate=INPUT_SAMPLE_RATE,
                channels=1,
                dtype="int16",
                blocksize=INPUT_BLOCK_FRAMES,
                latency="low",
                callback=self.input_callback,
            )
            self.output_stream = sd.RawOutputStream(
                device=OUTPUT_DEVICE,
                samplerate=OUTPUT_SAMPLE_RATE,
                channels=1,
                dtype="int16",
                blocksize=OUTPUT_BLOCK_FRAMES,
                latency="low",
            )
        except Exception as error:
            if self.input_stream is not None:
                self.input_stream.close()
                self.input_stream = None
            if self.output_stream is not None:
                self.output_stream.close()
                self.output_stream = None
            raise RuntimeError(
                "无法打开 16kHz 麦克风或 24kHz 扬声器；"
                "请运行 uv run --with sounddevice python -m sounddevice 检查设备"
            ) from error

    def run(self):
        self.open_audio_devices()
        self.uplink_thread = threading.Thread(
            target=self.uplink_worker,
            name="senseaudio-uplink",
            daemon=True,
        )
        self.output_thread = threading.Thread(
            target=self.output_worker,
            name="senseaudio-playback",
            daemon=True,
        )
        self.websocket_thread = threading.Thread(
            target=lambda: self.ws.run_forever(
                ping_interval=20,
                ping_timeout=10,
            ),
            name="senseaudio-websocket",
            daemon=True,
        )

        try:
            self.output_stream.start()
            self.input_stream.start()
            self.uplink_thread.start()
            self.output_thread.start()
            self.websocket_thread.start()

            while self.websocket_thread.is_alive():
                if self.mic_dropped.is_set():
                    self.mic_dropped.clear()
                    print("\n警告：网络发送较慢，已丢弃过期麦克风帧")
                if self.input_warning.is_set():
                    self.input_warning.clear()
                    print("\n警告：麦克风发生丢帧或输入溢出")
                if self.playback_backlog.is_set():
                    self.playback_backlog.clear()
                    print("\n警告：播放队列已满，已丢弃最早的音频块")
                if self.fatal_event.is_set():
                    self.request_end(self.fatal_reason or "本地音频错误")
                    break
                self.websocket_thread.join(0.1)

        except KeyboardInterrupt:
            self.request_end("用户按下 Ctrl+C")
        finally:
            if self.websocket_thread.is_alive() and not self.closed_event.wait(2):
                self.abort_websocket()
                try:
                    self.ws.close()
                except Exception:
                    pass

            self.stop_event.set()
            self.mic_enabled.clear()
            self.clear_playback_queue()

            for stream in (self.input_stream, self.output_stream):
                if stream is not None:
                    try:
                        stream.abort()
                    except Exception:
                        pass

            if self.uplink_thread is not None and self.uplink_thread.ident is not None:
                self.uplink_thread.join(timeout=1)
            if self.output_thread is not None and self.output_thread.ident is not None:
                self.output_thread.join(timeout=1)

            for stream in (self.input_stream, self.output_stream):
                if stream is not None:
                    try:
                        stream.close()
                    except Exception:
                        pass

            if (
                self.websocket_thread is not None
                and self.websocket_thread.ident is not None
            ):
                self.websocket_thread.join(timeout=1)


if __name__ == "__main__":
    RealtimeVoiceClient().run()
```

将上方代码保存为 `realtime_voice.py`，然后查看设备或直接运行：

```bash theme={null}
uv run --with sounddevice python -m sounddevice
export SENSEAUDIO_INPUT_DEVICE='输入设备名称或编号'
export SENSEAUDIO_OUTPUT_DEVICE='输出设备名称或编号'
uv run --with websocket-client --with sounddevice realtime_voice.py
```

<Warning>
  示例没有实现声学回声消除（AEC），请优先使用耳机。`sounddevice` 能否打开目标采样率取决于操作系统和设备。若初始化失败，请选择支持重采样的系统设备或音频后端，不要直接修改协议规定的输入 `16000Hz` 与当前输出 `24000Hz`。
</Warning>

<Note>
  示例会在终端输出用户转写和工具事件。生产环境中请对日志脱敏，不要记录 API Key、完整转写、工具参数或会话标识。
</Note>

## 错误码说明

| 错误码                  | 类型    | 说明                                                                                                                                                                      | 关闭码    |
| :------------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
| `bad_request`        | 致命错误  | JSON 格式错误、`type` 无效、`start` 配置错误（包括音色无效）、重复发送 `start`、`update` 修改了 `model` 或 `audio_setting`、`tool.result` 缺少 `call_id` 或 `result`，或 `commit` / `cancel` / `end` 携带额外字段 | `1008` |
| `model_not_found`    | 致命错误  | `start` 中传入的模型错误                                                                                                                                                        | `1008` |
| `insufficient_funds` | 致命错误  | 账户没有足够配额完成接下来的语音对话                                                                                                                                                      | `1008` |
| `internal_error`     | 致命错误  | 服务端没有正确连接到模型服务                                                                                                                                                          | `1011` |
| `fatal`              | 致命错误  | 服务端发生其他错误，包括无效的 `session_action`                                                                                                                                        | `1011` |
| `empty_audio_buffer` | 非致命错误 | 没有上传音频，或上次手动提交后没有新的音频上传时发送了 `commit`，服务端会忽略本次提交                                                                                                                         | 不断开    |
| `no_active_response` | 非致命错误 | 模型没有回复时发送了 `cancel`，服务端会忽略本次打断                                                                                                                                          | 不断开    |
| `invalid_voice`      | 非致命错误 | `update` 修改的音色不存在，服务端忽略本次更新并继续使用之前的音色                                                                                                                                   | 不断开    |

<Note>
  鉴权发生在 WebSocket Upgrade 阶段。缺少 Token、Token 无效或鉴权格式错误时，服务端返回 HTTP `401`，不会先建立 WebSocket 再发送 JSON `error`。
</Note>

## 音色列表

| 序号 | 音色ID            | 音色名  | 情感   |
| :- | :-------------- | :--- | :--- |
| 1  | `m_c_0001`      | 可爱萌娃 | 开心   |
| 2  | `f_y_0035_a`    | 清风少女 | 傲娇   |
| 3  | `f_y_0035_c`    | 清风少女 | 平稳   |
| 4  | `f_y_0039_c`    | 知心少女 | 广告中插 |
| 5  | `f_y_0039_d`    | 知心少女 | 轻松铺陈 |
| 6  | `f_y_0037_f`    | 青春女声 | 主题升华 |
| 7  | `f_y_0041_c`    | 亲切女孩 | 致歉安慰 |
| 8  | `m_y_0022`      | 沙哑青年 | 深情   |
| 9  | `m_y_0021`      | 撒娇青年 | 平稳   |
| 10 | `m_y_0027`      | 粘人男友 | 平稳   |
| 11 | `m_y_0027_a`    | 粘人男友 | 深情   |
| 12 | `m_y_0028`      | 温柔霸总 | 平稳   |
| 13 | `m_y_0034_d`    | 可靠青叔 | 细心提问 |
| 14 | `m_y_0034_e`    | 可靠青叔 | 主题升华 |
| 15 | `m_y_0036_e`    | 利落青年 | 细心提问 |
| 16 | `5min_f_y_0003` | 天真少女 | 平稳   |
| 17 | `f_m_0006`      | 温柔御姐 | 深情   |
| 18 | `f_y_0020`      | 俏皮女孩 | 开心   |
| 19 | `f_y_0021_a`    | 冷酷少女 | 平稳   |
| 20 | `f_y_0025_a`    | 管家女仆 | 开心   |
| 21 | `f_y_0029_a`    | 专业女播 | 平稳   |
| 22 | `f_y_0030_a`    | 魅力姐姐 | 撒娇   |
| 23 | `m_y_0020`      | 温柔青年 | 平稳   |
| 24 | `f_m_0007_a`    | 羞涩御姐 | 低落   |
| 25 | `f_y_0031_c`    | 温柔月光 | 傲娇   |
| 26 | `5min_f_y_0005` | 乐天女孩 | 开心   |
| 27 | `f_y_0014`      | 优雅台妹 | 平稳   |
| 28 | `f_y_0020_b`    | 俏皮女孩 | 傲娇   |
| 29 | `f_y_0021_b`    | 冷酷少女 | 低落   |
| 30 | `f_y_0026_d`    | 赛博少女 | 撒娇   |
| 31 | `f_y_0027_a`    | 羞涩甜妹 | 开心   |
| 32 | `f_y_0028_b`    | 成熟姐姐 | 深情   |
| 33 | `f_y_0034_d`    | 嗲嗲台妹 | 委屈   |
| 34 | `f_y_0040_c`    | 自然少女 | 温柔   |
| 35 | `5min_m_y_0004` | 霸道男神 | 平稳   |
| 36 | `m_y_0030_b`    | 柔弱公子 | 开心   |
| 37 | `m_y_0018`      | 阳光少年 | 平稳   |
| 38 | `m_y_0029_b`    | 乐观少年 | 深情   |
| 39 | `m_y_0036_a`    | 利落青年 | 内容剖析 |
| 40 | `f_m_0009_a`    | 气质学姐 | 开心   |
| 41 | `f_m_0009_b`    | 气质学姐 | 平稳   |
| 42 | `f_y_0019_a`    | 哭泣少女 | 生气   |
| 43 | `f_y_0020_a`    | 俏皮女孩 | 低落   |
| 44 | `f_y_0025`      | 管家女仆 | 平稳   |
| 45 | `f_y_0030_e`    | 魅力姐姐 | 傲娇   |
| 46 | `f_y_0034_e`    | 嗲嗲台妹 | 生气   |
| 47 | `5min_m_y_0002` | 纨绔青年 | 平稳   |
| 48 | `m_y_0026`      | 阳光甜弟 | 撒娇   |
| 49 | `m_y_0030`      | 柔弱公子 | 平稳   |
| 50 | `m_y_0029`      | 乐观少年 | 平稳   |
| 51 | `f_y_0023`      | 冷艳御姐 | 平稳   |
| 52 | `f_y_0025_b`    | 管家女仆 | 生气   |
| 53 | `f_y_0028`      | 成熟姐姐 | 妩媚   |
| 54 | `f_y_0031_b`    | 温柔月光 | 妩媚   |
| 55 | `m_y_0024`      | 清冷师尊 | 低落   |
| 56 | `m_m_0012`      | 风流浪子 | 开心   |
| 57 | `m_y_0034`      | 可靠青叔 | 内容剖析 |

## 注意事项

1. **首条消息要求**：`start` 必须作为第一个消息发送，且同一连接内只能发送一次。
2. **音频发送时机**：必须等待 `ready` 后再发送二进制音频帧。
3. **开场白轮次**：`greeting` 非空时，应区分开场白的 `turn.done` 与用户语音轮次的 `turn.done`。
4. **文本帧格式**：客户端与服务端的文本帧均为 JSON，且必须包含 `type` 字段。
5. **音频帧格式**：客户端上传音频必须为裸 `pcm_s16le / 16000Hz / 单声道`，建议按 `1280` 字节 / `40ms` 分帧发送。
6. **持续上行与超时**：长连接客户端应持续处理麦克风流，并设置应用层连接与设备超时；结束、关闭或出错时必须停止采集和发送。
7. **服务端音频解析**：模型返回的二进制音频帧按 `assistant.audio.start` 中的 `sample_rate` 与 `format` 解析，当前为单声道；实时播放应使用有界队列，避免阻塞 WebSocket 接收回调。
8. **打断处理**：用户在模型播报期间开口时，可在收到 `speech.started` 后发送一次 `cancel`，同时丢弃已取消回复中尚未播放以及仍在途的音频帧。
9. **回声控制**：示例没有实现 AEC，建议使用耳机，避免模型播报被麦克风回采并触发新的用户轮次。
10. **结束连接**：如需主动结束对话，请发送 `end`，服务端会以关闭码 `1000` 正常关闭连接。

## 相关资源

<CardGroup>
  <Card title="语音合成 WebSocket" icon="waveform-lines" href="/api-reference/endpoint/tts/websocket">
    基于 WebSocket 的实时文本转语音合成协议。
  </Card>

  <Card title="语音识别 WebSocket" icon="mic" href="/api-reference/endpoint/asr/websocket">
    基于 WebSocket 的实时语音识别协议。
  </Card>
</CardGroup>


# 语音合成 (TTS)
Source: https://docs.senseaudio.cn/api-reference/endpoint/tts/synthesize

api-reference/endpoint/tts/synthesize.openapi.json POST /v1/t2a_v2

## 说明

将文本合成为高自然度的语音音频，支持 70+ 系统音色、克隆音色与文生音色。本页介绍非流式合成（`stream=false`），一次性返回完整音频。

* **接入域名**：`https://api.senseaudio.cn`
* **计费单位**：按合成字符数计费，详见 [计费说明](/guides/account/billing)
* **音色入参**：`voice_id` 必须为当前账号可用音色，参考 [音色列表](/guides/voice/catalog)
* **流式 (SSE) 合成**：参考 [语音合成 HTTP 流式](/api-reference/endpoint/tts/synthesize-stream)
* **WebSocket 合成**：参考 [语音合成 WebSocket](/api-reference/endpoint/tts/websocket)

## 相关指南

* [语音合成与音色概览](/guides/tts/overview)
* [自定义音色（音色克隆与文生音色）](/guides/voice/custom)


# 语音合成 HTTP 流式 (TTS-SSE)
Source: https://docs.senseaudio.cn/api-reference/endpoint/tts/synthesize-stream

api-reference/endpoint/tts/synthesize-stream.openapi.json POST /v1/t2a_v2
基于 SSE 的流式 TTS 合成接口参考

## 说明

将文本通过 SSE 协议流式合成为语音，适用于低延迟、边合成边播放的实时场景。请求参数与 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize) 完全相同，仅需将 `stream` 设为 `true`；响应为 `text/event-stream`。

* **接口地址**：`https://api.senseaudio.cn/v1/t2a_v2`
* **Content-Type（请求）**：`application/json`
* **Content-Type（响应）**：`text/event-stream; charset=utf-8`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **语音合成**：参考 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)
* **WebSocket 合成**：参考 [语音合成 WebSocket](/api-reference/endpoint/tts/websocket)

<Note>
  流式模式要求 `stream` 固定为 `true`；响应采用 SSE 格式，每个事件以 `data: ` 前缀 + JSON 对象返回，`extra_info` 仅在最后一个 chunk 返回。
</Note>

## SSE 响应格式

响应 `Content-Type: text/event-stream; charset=utf-8`。每个数据块以 `data: ` 开头，后跟一个 JSON 对象，字段与同步返回的 `TTSResponse` 一致，`data.status` 用于标识分片顺序。

<ResponseField name="data" type="object">
  合成数据对象，可能为 null，需进行非空判断。

  <Expandable title="child attributes">
    <ResponseField name="data.audio" type="string">
      合成后的音频数据，hex 编码，格式与请求中指定的 `audio_setting.format` 一致。
    </ResponseField>

    <ResponseField name="data.status" type="integer">
      当前音频流状态：`1` 表示合成中，`2` 表示合成结束。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extra_info" type="object">
  音频附加信息，**仅在最后一个 chunk 返回**。

  <Expandable title="child attributes">
    <ResponseField name="extra_info.audio_length" type="integer">音频时长（毫秒）。</ResponseField>
    <ResponseField name="extra_info.audio_sample_rate" type="integer">音频采样率。</ResponseField>
    <ResponseField name="extra_info.audio_size" type="integer">音频文件大小（字节）。</ResponseField>
    <ResponseField name="extra_info.bitrate" type="integer">音频比特率。</ResponseField>
    <ResponseField name="extra_info.audio_format" type="string">音频格式：`mp3` / `pcm` / `flac` / `wav`。</ResponseField>
    <ResponseField name="extra_info.audio_channel" type="integer">声道数：`1` 单声道 / `2` 双声道。</ResponseField>
    <ResponseField name="extra_info.word_count" type="integer">字数：按 grapheme cluster 统计，排除纯空白/标点/控制符。</ResponseField>
    <ResponseField name="extra_info.usage_characters" type="integer">字符数：按 Unicode 码点统计。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="trace_id" type="string">链路追踪 ID。</ResponseField>

<ResponseField name="base_resp" type="object">
  本次请求的状态码和详情。

  <Expandable title="child attributes">
    <ResponseField name="base_resp.status_code" type="integer">状态码，`0` 表示成功。</ResponseField>
    <ResponseField name="base_resp.status_msg" type="string">状态详情。</ResponseField>
  </Expandable>
</ResponseField>

### 流式响应示例

```
data: {"data":{"audio":"49443304...","status":1},"extra_info":null,"trace_id":"69c20e38c8761996a85d57881fe4d817","base_resp":{"status_code":0,"status_msg":""}}

data: {"data":{"audio":"fffb9864...","status":1},"extra_info":null,"trace_id":"69c20e38c8761996a85d57881fe4d817","base_resp":{"status_code":0,"status_msg":""}}

data: {"data":{"audio":"fffb9864...","status":2},"extra_info":{"audio_length":2306,"audio_sample_rate":32000,"audio_size":36908,"bitrate":128000,"audio_format":"mp3","audio_channel":2,"word_count":24,"usage_characters":30},"trace_id":"69c20e38c8761996a85d57881fe4d817","base_resp":{"status_code":0,"status_msg":"success"}}
```

## 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.senseaudio.cn/v1/t2a_v2 \
    -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sensenova-tts-2.0",
      "text": "这是一个流式输出的例子。",
      "stream": true,
      "voice_setting": {
        "voice_id": "male_0004_a",
        "latex_read": false
      },
      "stream_options": {
        "exclude_aggregated_audio": true
      }
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  API_URL = "https://api.senseaudio.cn/v1/t2a_v2"
  HEADERS = {
      "Authorization": "Bearer SENSEAUDIO_API_KEY",
      "Content-Type": "application/json"
  }

  def tts_stream():
      payload = {
          "model": "sensenova-tts-2.0",
          "text": "这是一个流式输出的例子。",
          "stream": True,
          "voice_setting": {
              "voice_id": "male_0004_a",
              "latex_read": False
          },
          "stream_options": {
              "exclude_aggregated_audio": True
          }
      }
      with requests.post(API_URL, json=payload, headers=HEADERS, stream=True) as r:
          with open("stream_output.mp3", "wb") as f:
              for line in r.iter_lines():
                  if line:
                      line_str = line.decode('utf-8')
                      if line_str.startswith("data: "):
                          line_str = line_str[6:]
                      resp = json.loads(line_str)
                      if "data" in resp and "audio" in resp["data"]:
                          f.write(bytes.fromhex(resp["data"]["audio"]))
          print("流式合成完成")

  if __name__ == "__main__":
      tts_stream()
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
  const fs = require('fs');

  const API_URL = 'https://api.senseaudio.cn/v1/t2a_v2';
  const HEADERS = {
      'Authorization': 'Bearer SENSEAUDIO_API_KEY',
      'Content-Type': 'application/json'
  };

  async function ttsStream() {
      try {
          const payload = {
              model: 'sensenova-tts-2.0',
              text: '这是一个流式输出的例子。',
              stream: true,
              voice_setting: {
                  voice_id: 'male_0004_a',
                  latex_read: false
              },
              stream_options: {
                  exclude_aggregated_audio: true
              }
          };

          const res = await axios.post(API_URL, payload, {
              headers: HEADERS,
              responseType: 'stream'
          });

          const writeStream = fs.createWriteStream('stream_output.mp3');

          res.data.on('data', (chunk) => {
              const lines = chunk.toString().split('\n');
              for (const line of lines) {
                  if (line.startsWith('data: ')) {
                      try {
                          const json = JSON.parse(line.slice(6));
                          if (json.data && json.data.audio) {
                              writeStream.write(Buffer.from(json.data.audio, 'hex'));
                          }
                      } catch (e) {}
                  }
              }
          });

          res.data.on('end', () => {
              writeStream.end();
              console.log('流式合成完成');
          });
      } catch (err) {
          console.error('请求异常:', err.message);
      }
  }

  ttsStream();
  ```

  ```go Go theme={null}
  package main

  import (
      "bufio"
      "bytes"
      "encoding/hex"
      "encoding/json"
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  const (
      APIURL             = "https://api.senseaudio.cn/v1/t2a_v2"
      SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY"
  )

  type TTSRequest struct {
      Model         string        `json:"model"`
      Text          string        `json:"text"`
      Stream        bool          `json:"stream"`
      VoiceSetting  VoiceSetting  `json:"voice_setting"`
      StreamOptions StreamOptions `json:"stream_options"`
  }

  type StreamOptions struct {
      ExcludeAggregatedAudio bool `json:"exclude_aggregated_audio"`
  }

  type VoiceSetting struct {
      VoiceID   string `json:"voice_id"`
      LatexRead bool   `json:"latex_read"`
  }

  type SSEResponse struct {
      Data struct {
          Audio  string `json:"audio"`
          Status int    `json:"status"`
      } `json:"data"`
      BaseResp struct {
          StatusCode    int    `json:"status_code"`
          StatusMessage string `json:"status_msg"`
      } `json:"base_resp"`
  }

  func main() {
      payload := TTSRequest{
          Model:  "sensenova-tts-2.0",
          Text:   "这是一个流式输出的例子。",
          Stream: true,
          VoiceSetting: VoiceSetting{
              VoiceID:   "male_0004_a",
              LatexRead: false,
          },
          StreamOptions: StreamOptions{
              ExcludeAggregatedAudio: true,
          },
      }

      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", APIURL, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer "+SENSEAUDIO_API_KEY)
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          fmt.Println("请求失败:", err)
          return
      }
      defer resp.Body.Close()

      file, _ := os.Create("stream_output.mp3")
      defer file.Close()

      scanner := bufio.NewScanner(resp.Body)
      for scanner.Scan() {
          line := scanner.Text()
          if strings.HasPrefix(line, "data: ") {
              var result SSEResponse
              json.Unmarshal([]byte(line[6:]), &result)
              if result.Data.Audio != "" {
                  audioData, _ := hex.DecodeString(result.Data.Audio)
                  file.Write(audioData)
              }
          }
      }
      fmt.Println("流式合成完成")
  }
  ```

  ```java Java theme={null}
  import java.io.*;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import org.json.JSONObject;

  public class SenseAudioTTSStream {
      private static final String API_URL = "https://api.senseaudio.cn/v1/t2a_v2";
      private static final String SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY";

      public static void main(String[] args) {
          try {
              JSONObject voiceSetting = new JSONObject();
              voiceSetting.put("voice_id", "male_0004_a");
              voiceSetting.put("latex_read", false);

              JSONObject payload = new JSONObject();
              payload.put("model", "sensenova-tts-2.0");
              payload.put("text", "这是一个流式输出的例子。");
              payload.put("stream", true);
              payload.put("voice_setting", voiceSetting);
              payload.put("stream_options", new JSONObject().put("exclude_aggregated_audio", true));

              URL url = new URL(API_URL);
              HttpURLConnection conn = (HttpURLConnection) url.openConnection();
              conn.setRequestMethod("POST");
              conn.setRequestProperty("Authorization", "Bearer " + SENSEAUDIO_API_KEY);
              conn.setRequestProperty("Content-Type", "application/json");
              conn.setDoOutput(true);

              try (OutputStream os = conn.getOutputStream()) {
                  byte[] input = payload.toString().getBytes("utf-8");
                  os.write(input, 0, input.length);
              }

              try (BufferedReader br = new BufferedReader(
                      new InputStreamReader(conn.getInputStream(), "utf-8"));
                   FileOutputStream fos = new FileOutputStream("stream_output.mp3")) {

                  String line;
                  while ((line = br.readLine()) != null) {
                      if (line.startsWith("data: ")) {
                          String jsonStr = line.substring(6);
                          JSONObject result = new JSONObject(jsonStr);
                          if (result.has("data")) {
                              JSONObject data = result.getJSONObject("data");
                              if (data.has("audio")) {
                                  String audioHex = data.getString("audio");
                                  byte[] audioData = new byte[audioHex.length() / 2];
                                  for (int i = 0; i < audioData.length; i++) {
                                      int index = i * 2;
                                      int val = Integer.parseInt(audioHex.substring(index, index + 2), 16);
                                      audioData[i] = (byte) val;
                                  }
                                  fos.write(audioData);
                              }
                          }
                      }
                  }
                  System.out.println("流式合成完成");
              }
          } catch (Exception e) {
              System.out.println("请求异常: " + e.getMessage());
              e.printStackTrace();
          }
      }
  }
  ```
</CodeGroup>

## 相关指南

* [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)
* [语音合成 WebSocket](/api-reference/endpoint/tts/websocket)
* [语音合成与音色概览](/guides/tts/overview)
* [自定义音色（克隆与文生音色）](/guides/voice/custom)


# 语音合成 WebSocket (TTS)
Source: https://docs.senseaudio.cn/api-reference/endpoint/tts/websocket

基于 WebSocket 的实时 TTS 合成协议参考

## 说明

基于 WebSocket 的实时文本到语音合成接口，支持增量式文本输入与流式音频输出，适用于实时对话、在线客服、边生成边播报等低延迟场景。单次连接支持多次合成任务，最大文本长度 10000 字符。

* **接入地址**：`wss://api.senseaudio.cn/ws/v1/t2a_v2`
* **鉴权方式**：Bearer Token，格式 `Authorization: Bearer SENSEAUDIO_API_KEY`
* **消息格式**：`application/json`，音频仅返回 hex 编码字符串
* **计费单位**：按合成字符数计费，详见 [计费说明](/guides/account/billing)
* **音色入参**：`voice_id` 必须为当前账号可用音色，参考 [音色列表](/guides/voice/catalog)
* **标准 HTTP 合成**：参考 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)
* **SSE 合成**：参考 [语音合成 HTTP 流式](/api-reference/endpoint/tts/synthesize-stream)

<Warning>
  - WebSocket 接口只支持返回 **hex 格式** 的音频数据。
  - 当最后一次收到服务端返回结果后超过 **120 秒** 没有发送新事件时，WebSocket 连接自动断开。
  - 音色模型名称：**sensenova-tts-2.0**。
</Warning>

## 请求头 (Request Headers)

| 参数名               | 必填 | 说明                                      | 示例                  |
| :---------------- | :- | :-------------------------------------- | :------------------ |
| **Authorization** | 是  | 鉴权 Token。格式：Bearer SENSEAUDIO\_API\_KEY | Bearer sk-123456... |
| **Content-Type**  | 是  | 内容类型。固定为 application/json               | application/json    |

***

## 通信流程

```
1. 客户端建立 WebSocket 连接
   ↓
2. 服务端返回 connected_success 事件
   ↓
3. 客户端发送 task_start 事件（包含音色、音频格式等配置）
   ↓
4. 服务端返回 task_started 事件
   ↓
5. 客户端发送 task_continue 事件（发送待合成文本）
   ↓
6. 服务端返回音频数据（可多次发送 task_continue）
   ↓
7. 客户端发送 task_finish 事件
   ↓
8. 服务端返回 task_finished 事件并关闭连接
```

```mermaid theme={null}
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端

    Note over Client, Server: 1. 建立连接
    Client->>Server: WebSocket Connect (带 Auth Header)
    Server-->>Client: JSON: {"event": "connected_success", ...}

    Note over Client, Server: 2. 开启任务
    Client->>Server: JSON: {"event": "task_start", "model": "...", "voice_setting": {...}}
    Server-->>Client: JSON: {"event": "task_started", ...}

    Note over Client, Server: 3. 文本合成 (循环)
    loop 分段合成
        Client->>Server: JSON: {"event": "task_continue", "text": "..."}
        Server-->>Client: JSON: {"event": "task_continued", "data": {"audio": "..."}}
    end

    Note over Client, Server: 4. 结束任务
    Client->>Server: JSON: {"event": "task_finish"}
    Server-->>Client: JSON: {"event": "task_finished", ...}
    Server-->>Client: Close Connection
```

***

## 客户端事件

### 1. task\_start - 开始任务

发送此事件正式开始合成任务。当服务端返回 **task\_started** 事件时，标志着任务已成功开始。只有在接收到该事件后，才能向服务器发送 **task\_continue** 或 **task\_finish** 事件。

**请求参数**

| 参数名                             | 类型      | 必填 | 默认值    | 说明                                                       |
| ------------------------------- | ------- | -- | ------ | -------------------------------------------------------- |
| **event**                       | string  | 是  | 无      | 固定值：**task\_start**                                      |
| **model**                       | string  | 是  | 无      | 模型名称，示例值：**sensenova-tts-2.0、senseaudio-tts-1.5-260319** |
| **voice\_setting**              | object  | 是  | 无      | 声音设置                                                     |
| **voice\_setting.voice\_id**    | string  | 是  | 无      | 主音色名称                                                    |
| **voice\_setting.speed**        | float   | 否  | 1.0    | 语速，取值范围 \[0.5, 2.0]                                      |
| **voice\_setting.vol**          | float   | 否  | 1.0    | 音量，取值范围 \[0.01, 10.0]                                    |
| **voice\_setting.pitch**        | int     | 否  | 0      | 音调，取值范围 \[-12, 12]，0 表示保持原始音调                            |
| **voice\_setting.latex\_read**  | boolean | 否  | false  | 数学公式朗读，支持 LaTeX、MathML、Unicode 数学符号等格式。（会产生额外的性能损耗）      |
| **audio\_setting**              | object  | 否  | 无      | 音频格式设置                                                   |
| **audio\_setting.sample\_rate** | int     | 否  | 32000  | 音频采样率，取值范围 \[8000, 16000, 22050, 24000, 32000, 44100]    |
| **audio\_setting.bitrate**      | int     | 否  | 128000 | 音频码率，取值范围 \[32000, 64000, 128000, 256000]                |
| **audio\_setting.format**       | string  | 否  | mp3    | 输出格式：mp3、wav、pcm、flac                                    |
| **audio\_setting.channel**      | int     | 否  | 2      | 音频声道，1：单声道，2：双声道                                         |

**请求示例**

```json theme={null}
{
  "event": "task_start",
  "model": "sensenova-tts-2.0",
  "voice_setting": {
    "voice_id": "male_0004_a",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "latex_read": false
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  }
}
```

**响应参数**

| 参数名                         | 类型      | 说明      |
| --------------------------- | ------- | ------- |
| **session\_id**             | string  | 会话 ID   |
| **event**                   | string  | 事件类型    |
| **trace\_id**               | string  | 链路追踪 ID |
| **base\_resp**              | object  | 请求状态信息  |
| **base\_resp.status\_code** | integer | 状态码     |
| **base\_resp.status\_msg**  | string  | 状态详情    |

**响应示例**

```json theme={null}
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_started",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### 2. task\_continue - 任务继续

当收到服务端返回的 **task\_started** 事件后，任务正式开始，可通过发送 **task\_continue** 事件发送要合成的文本。支持顺序发送多个 **task\_continue** 事件，实现分段文本合成。

**请求参数**

| 参数名            | 类型     | 必填 | 说明                                           | 示例                                                |
| -------------- | ------ | -- | -------------------------------------------- | ------------------------------------------------- |
| **event**      | string | 是  | 固定值：**task\_continue**                       |                                                   |
| **text**       | string | 是  | 合成文本内容，支持中英文；支持 `<break>` 停顿符，详见下方停顿符说明      |                                                   |
| **dictionary** | array  | 否  | 多音字配置列表（**模型必须为 senseaudio-tts-1.5-260319**） | `[{"original": "好干净","replacement": "[hao4]干净"}]` |

#### LaTeX 公式说明

控制是否朗读 latex 公式，默认为 false。

* 请求中的公式需要在公式的首尾加上 `$$`。
* 请求中公式若有 `\`，需转义成 `\\`。

示例：动能公式

<img alt="动能公式" />

表示为：`$$E_k = \\frac{1}{2} m v^2$$`

```json theme={null}
{
  "event": "task_continue",
  "text": "$$E_k = \\frac{1}{2} m v^2$$"
}
```

#### `<break>` 停顿符说明

**`<break>`** 用于在语音合成中插入停顿。

```xml theme={null}
<break time=500>
```

* **time** 单位为毫秒（ms）
* **500** 表示停顿 500 毫秒
* **最小值为 100 毫秒，最大值无限制**

示例：

```json theme={null}
{
  "event": "task_continue",
  "text": "你好，这是来自 <break time=5000> SenseAudio 的第一条语音"
}
```

#### dictionary (多音字纠正)

| 参数名             | 类型     | 必填 | 描述     | 默认值 | 示例        |
| :-------------- | :----- | :- | :----- | :-- | :-------- |
| **original**    | string | 是  | 原始文本。  | 无   | 好干净       |
| **replacement** | string | 是  | 多音字配置。 | 无   | \[hao4]干净 |

**请求示例**

```json theme={null}
{
  "event": "task_continue",
  "text": "好干净",
  "dictionary": [
    { "original": "好干净", "replacement": "[hao4]干净" }
  ]
}
```

**响应参数**

| 参数名                                 | 类型      | 说明                                          |
| ----------------------------------- | ------- | ------------------------------------------- |
| **session\_id**                     | string  | 会话 ID                                       |
| **event**                           | string  | 事件类型                                        |
| **trace\_id**                       | string  | 链路追踪 ID                                     |
| **is\_final**                       | boolean | 当前 `task_continue` 语音合成任务是否结束               |
| **base\_resp**                      | object  | 请求状态信息                                      |
| **base\_resp.status\_code**         | integer | 状态码                                         |
| **base\_resp.status\_msg**          | string  | 状态详情                                        |
| **data**                            | object  | 返回的合成数据对象（可能为 null）                         |
| **data.audio**                      | string  | 合成后的音频数据（hex 编码）                            |
| **data.status**                     | integer | 音频流状态：1 表示合成中，2 表示合成结束                      |
| **extra\_info**                     | object  | 音频附加信息（流式返回时只有最后一个 chunk 会返回）               |
| **extra\_info.audio\_length**       | integer | 音频时长（毫秒）                                    |
| **extra\_info.audio\_sample\_rate** | integer | 音频采样率                                       |
| **extra\_info.audio\_size**         | integer | 音频文件大小（字节）                                  |
| **extra\_info.bitrate**             | integer | 音频比特率                                       |
| **extra\_info.audio\_format**       | string  | 音频格式，取值范围 \[mp3, pcm, flac, wav]            |
| **extra\_info.audio\_channel**      | integer | 音频声道数，1：单声道，2：双声道                           |
| **extra\_info.word\_count**         | integer | 字数统计（按字素簇 grapheme cluster 统计，排除纯空白/标点/控制符） |
| **extra\_info.usage\_characters**   | integer | 字符数统计（按 Unicode 码点统计）                       |

**响应示例**

```json theme={null}
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_continued",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "is_final": false,
  "data": { "audio": "hex编码的音频数据...", "status": 1 },
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### 3. task\_finish - 结束任务

服务端收到此事件后，会等待当前队列中所有合成任务完成后，关闭 WebSocket 连接并结束任务。

**请求参数**

| 参数名       | 类型     | 必填 | 说明                   |
| --------- | ------ | -- | -------------------- |
| **event** | string | 是  | 固定值：**task\_finish** |

**请求示例**

```json theme={null}
{ "event": "task_finish" }
```

**响应示例**

```json theme={null}
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_finished",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

***

## 服务端事件

### connected\_success - 连接建立成功

初次请求接口时，表示 WebSocket 连接建立成功。

```json theme={null}
{
  "session_id": "xxxx",
  "event": "connected_success",
  "trace_id": "xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### task\_started - 任务已开始

标志任务已成功开始，客户端可以开始发送 **task\_continue** 事件。

```json theme={null}
{
  "session_id": "xxxx",
  "event": "task_started",
  "trace_id": "xxxxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### task\_finished - 任务已结束

标志任务已结束，WebSocket 连接即将关闭。

```json theme={null}
{
  "session_id": "xxxx",
  "event": "task_finished",
  "trace_id": "xxxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}
```

### task\_failed - 任务失败

标志任务失败，`base_resp.status_msg` 中包含错误信息。

```json theme={null}
{
  "session_id": "xxxx",
  "event": "task_failed",
  "trace_id": "xxxxx",
  "base_resp": { "status_code": 1004, "status_msg": "具体错误信息" }
}
```

***

## 使用示例

<Tabs>
  <Tab title="Node.js">
    依赖：**npm install ws**

    ```javascript theme={null}
    const fs = require('fs')
    const WebSocket = require('ws')

    const WS_URL = 'wss://api.senseaudio.cn/ws/v1/t2a_v2'
    const API_KEY = process.env.SENSEAUDIO_API_KEY
    if (!API_KEY) throw new Error('Missing env: SENSEAUDIO_API_KEY')

    const output = fs.createWriteStream('output.mp3')
    const ws = new WebSocket(WS_URL, {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
    })

    ws.on('open', () => console.log('WebSocket 连接已建立'))

    ws.on('message', (data) => {
      const response = JSON.parse(data.toString())
      console.log('收到服务端事件:', response.event)

      if (response.event === 'connected_success') {
        ws.send(JSON.stringify({
          event: 'task_start',
          model: 'senseaudio-tts-1.5-260319',
          voice_setting: { voice_id: 'male_0004_a', speed: 1.0, vol: 1.0, pitch: 0, latex_read: false },
          audio_setting: { sample_rate: 32000, bitrate: 128000, format: 'mp3', channel: 1 },
        }))
        return
      }

      if (response.event === 'task_started') {
        ws.send(JSON.stringify({ event: 'task_continue', text: '道可道，非常道。名可名，非常名。无名天地之始，有名万物之母。' }))
        ws.send(JSON.stringify({ event: 'task_continue', text: '故常无欲，以观其妙；常有欲，以观其徼。' }))
        ws.send(JSON.stringify({ event: 'task_finish' }))
        return
      }

      if (response?.data?.audio) {
        output.write(Buffer.from(response.data.audio, 'hex'))
      }

      if (response.event === 'task_finished') { output.end(); ws.close() }
      if (response.event === 'task_failed') {
        console.error('任务失败:', response?.base_resp?.status_msg)
        output.end(); ws.close()
      }
    })

    ws.on('error', (err) => console.error('WebSocket 错误:', err))
    ws.on('close', () => console.log('WebSocket 连接已关闭'))
    ```
  </Tab>

  <Tab title="Python">
    依赖：**pip install websocket-client**

    ```python theme={null}
    import json
    import os

    import websocket

    WS_URL = "wss://api.senseaudio.cn/ws/v1/t2a_v2"
    API_KEY = os.getenv("SENSEAUDIO_API_KEY")
    if not API_KEY:
      raise RuntimeError("Missing env: SENSEAUDIO_API_KEY")

    output_file = open("output.mp3", "wb")

    def on_open(ws):
      print("WebSocket 连接已建立")

    def on_message(ws, message: str):
      resp = json.loads(message)
      event = resp.get("event")
      print("收到服务端事件:", event)

      if event == "connected_success":
        ws.send(json.dumps({
          "event": "task_start",
          "model": "senseaudio-tts-1.5-260319",
          "voice_setting": {"voice_id": "male_0004_a", "speed": 1.0, "vol": 1.0, "pitch": 0, "latex_read": False},
          "audio_setting": {"sample_rate": 32000, "bitrate": 128000, "format": "mp3", "channel": 1}
        }))
        return

      if event == "task_started":
        ws.send(json.dumps({"event": "task_continue", "text": "道可道，非常道。名可名，非常名。无名天地之始，有名万物之母。"}))
        ws.send(json.dumps({"event": "task_continue", "text": "故常无欲，以观其妙；常有欲，以观其徼。"}))
        ws.send(json.dumps({"event": "task_finish"}))
        return

      data = resp.get("data") or {}
      audio_hex = data.get("audio")
      if audio_hex:
        output_file.write(bytes.fromhex(audio_hex))

      if event in ("task_finished", "task_failed"):
        if event == "task_failed":
          print("任务失败:", (resp.get("base_resp") or {}).get("status_msg"))
        output_file.close(); ws.close()

    def on_error(ws, err): print("WebSocket 错误:", err)
    def on_close(ws, status_code, msg): print("WebSocket 连接已关闭:", status_code, msg)

    ws = websocket.WebSocketApp(
      WS_URL,
      header=[f"Authorization: Bearer {API_KEY}", "Content-Type: application/json"],
      on_open=on_open, on_message=on_message, on_error=on_error, on_close=on_close,
    )
    ws.run_forever()
    ```
  </Tab>

  <Tab title="Go">
    依赖：**go get github.com/gorilla/websocket**

    ```go theme={null}
    package main

    import (
      "encoding/hex"
      "encoding/json"
      "log"
      "net/http"
      "os"

      "github.com/gorilla/websocket"
    )

    const wsURL = "wss://api.senseaudio.cn/ws/v1/t2a_v2"

    func mustMarshal(v any) []byte { b, err := json.Marshal(v); if err != nil { panic(err) }; return b }

    func main() {
      apiKey := os.Getenv("SENSEAUDIO_API_KEY")
      if apiKey == "" { log.Fatal("Missing env: SENSEAUDIO_API_KEY") }

      header := http.Header{}
      header.Set("Authorization", "Bearer "+apiKey)
      header.Set("Content-Type", "application/json")

      c, _, err := websocket.DefaultDialer.Dial(wsURL, header)
      if err != nil { log.Fatal("dial:", err) }
      defer c.Close()

      out, err := os.Create("output.mp3")
      if err != nil { log.Fatal(err) }
      defer out.Close()

      for {
        _, msg, err := c.ReadMessage()
        if err != nil { log.Fatal("read:", err) }
        var resp map[string]any
        if err := json.Unmarshal(msg, &resp); err != nil { log.Fatal(err) }

        event, _ := resp["event"].(string)
        log.Println("收到服务端事件:", event)

        switch event {
        case "connected_success":
          _ = c.WriteMessage(websocket.TextMessage, mustMarshal(map[string]any{
            "event": "task_start",
            "model": "senseaudio-tts-1.5-260319",
            "voice_setting": map[string]any{"voice_id": "male_0004_a", "speed": 1.0, "vol": 1.0, "pitch": 0, "latex_read": false},
            "audio_setting": map[string]any{"sample_rate": 32000, "bitrate": 128000, "format": "mp3", "channel": 1},
          }))
        case "task_started":
          _ = c.WriteMessage(websocket.TextMessage, mustMarshal(map[string]any{"event": "task_continue", "text": "道可道，非常道。名可名，非常名。无名天地之始，有名万物之母。"}))
          _ = c.WriteMessage(websocket.TextMessage, mustMarshal(map[string]any{"event": "task_continue", "text": "故常无欲，以观其妙；常有欲，以观其徼。"}))
          _ = c.WriteMessage(websocket.TextMessage, mustMarshal(map[string]any{"event": "task_finish"}))
        case "task_failed", "task_finished":
          if event == "task_failed" {
            if baseResp, ok := resp["base_resp"].(map[string]any); ok {
              if msg, ok := baseResp["status_msg"].(string); ok { log.Println("任务失败:", msg) }
            }
          }
          return
        }

        if data, ok := resp["data"].(map[string]any); ok {
          if audioHex, ok := data["audio"].(string); ok && audioHex != "" {
            b, err := hex.DecodeString(audioHex)
            if err != nil { log.Fatal(err) }
            if _, err := out.Write(b); err != nil { log.Fatal(err) }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    依赖：OkHttp + Jackson

    ```java theme={null}
    import com.fasterxml.jackson.databind.JsonNode;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import okhttp3.*;
    import okio.ByteString;

    import java.io.FileOutputStream;
    import java.util.HashMap;
    import java.util.Map;

    public class SenseAudioTtsWsExample {
      private static final String WS_URL = "wss://api.senseaudio.cn/ws/v1/t2a_v2";

      public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("SENSEAUDIO_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) throw new RuntimeException("Missing env: SENSEAUDIO_API_KEY");

        OkHttpClient client = new OkHttpClient();
        ObjectMapper mapper = new ObjectMapper();

        Request request = new Request.Builder()
          .url(WS_URL)
          .addHeader("Authorization", "Bearer " + apiKey)
          .addHeader("Content-Type", "application/json")
          .build();

        FileOutputStream out = new FileOutputStream("output.mp3");

        client.newWebSocket(request, new WebSocketListener() {
          @Override public void onOpen(WebSocket webSocket, Response response) { System.out.println("WebSocket 连接已建立"); }

          @Override public void onMessage(WebSocket webSocket, String text) {
            try {
              JsonNode resp = mapper.readTree(text);
              String event = resp.path("event").asText();
              System.out.println("收到服务端事件: " + event);

              if ("connected_success".equals(event)) {
                Map<String, Object> payload = new HashMap<>();
                payload.put("event", "task_start");
                payload.put("model", "senseaudio-tts-1.5-260319");

                Map<String, Object> voice = new HashMap<>();
                voice.put("voice_id", "male_0004_a"); voice.put("speed", 1.0); voice.put("vol", 1.0);
                voice.put("pitch", 0); voice.put("latex_read", false);
                payload.put("voice_setting", voice);

                Map<String, Object> audio = new HashMap<>();
                audio.put("sample_rate", 32000); audio.put("bitrate", 128000);
                audio.put("format", "mp3"); audio.put("channel", 1);
                payload.put("audio_setting", audio);

                webSocket.send(mapper.writeValueAsString(payload));
                return;
              }

              if ("task_started".equals(event)) {
                webSocket.send(mapper.writeValueAsString(Map.of("event", "task_continue", "text", "道可道，非常道。名可名，非常名。无名天地之始，有名万物之母。")));
                webSocket.send(mapper.writeValueAsString(Map.of("event", "task_continue", "text", "故常无欲，以观其妙；常有欲，以观其徼。")));
                webSocket.send(mapper.writeValueAsString(Map.of("event", "task_finish")));
                return;
              }

              JsonNode audioHex = resp.path("data").path("audio");
              if (!audioHex.isMissingNode() && !audioHex.isNull()) {
                byte[] bytes = ByteString.decodeHex(audioHex.asText()).toByteArray();
                out.write(bytes);
              }

              if ("task_finished".equals(event) || "task_failed".equals(event)) {
                if ("task_failed".equals(event)) System.err.println("任务失败: " + resp.path("base_resp").path("status_msg").asText());
                out.close(); webSocket.close(1000, "done");
              }
            } catch (Exception e) { e.printStackTrace(); webSocket.close(1001, "error"); }
          }

          @Override public void onFailure(WebSocket webSocket, Throwable t, Response response) {
            t.printStackTrace();
            try { out.close(); } catch (Exception ignored) {}
          }
        });

        Thread.sleep(60_000);
        client.dispatcher().executorService().shutdown();
      }
    }
    ```
  </Tab>
</Tabs>

***

## 技术规格

* **模型名称**：**senseaudio-tts-1.5-260319**
* **最大文本长度**：10000 字符
* **连接超时**：最后一次收到服务端返回后 120 秒无新事件时自动断开

### 音频参数范围

| 参数      | 取值范围                                         | 默认值    | 说明        |
| ------- | -------------------------------------------- | ------ | --------- |
| **语速**  | \[0.5, 2.0]                                  | 1.0    | 数值越大语速越快  |
| **音量**  | \[0.01, 10.0]                                | 1.0    | 数值越大音量越大  |
| **音调**  | \[-12, 12]                                   | 0      | 正值提高，负值降低 |
| **采样率** | 8000, 16000, 22050, 24000, 32000, 44100 (Hz) | 32000  | 推荐 32000  |
| **码率**  | 32000, 64000, 128000, 256000 (bps)           | 128000 | 仅 MP3 格式  |
| **声道**  | 1 (单声道), 2 (双声道)                             | 2      | -         |

### 支持的音频格式

* **MP3**：推荐，压缩率高，兼容性好。
* **WAV**：无损音质，文件较大。
* **PCM**：原始音频数据。
* **FLAC**：无损压缩。

***

## 错误码说明

| 状态码  | 说明   | 解决方案          |
| ---- | ---- | ------------- |
| 0    | 成功   | -             |
| 1001 | 参数错误 | 检查请求参数格式和取值范围 |

***

## 注意事项

1. **音频数据格式**：WebSocket 接口只支持返回 hex 编码的音频数据，需要在客户端将 hex 字符串转换为二进制数据；音频格式由 `audio_setting.format` 决定。
2. **连接超时机制**：最后一次收到服务端返回后 120 秒内无新事件发送时连接自动断开；建议在任务完成后主动发送 `task_finish`，长时间无操作时可发送心跳保持连接。
3. **事件发送顺序**：必须按照 `task_start → task_continue → task_finish` 顺序发送；只有在收到 `task_started` 后才能发送 `task_continue`；可以发送多个 `task_continue` 事件。

## 相关资源

<CardGroup>
  <Card title="语音合成 HTTP" icon="waveform-lines" href="/api-reference/endpoint/tts/synthesize">
    标准 HTTP 合成接口参数详解。
  </Card>

  <Card title="语音合成 HTTP 流式" icon="bolt" href="/api-reference/endpoint/tts/synthesize-stream">
    流式 HTTP 合成接口参数详解。
  </Card>

  <Card title="语音合成介绍" icon="book-open" href="/guides/tts/overview">
    TTS 核心特性与音色生态。
  </Card>

  <Card title="音色列表" icon="list" href="/guides/voice/catalog">
    系统音色清单与 `voice_id` 规则。
  </Card>
</CardGroup>


# 创建视频生成任务
Source: https://docs.senseaudio.cn/api-reference/endpoint/video/create

POST /v1/video/create

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.senseaudio.cn/v1/video/create \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "model": "doubao-seedance-2-0-260128",
      "content": [
        {
          "type": "text",
          "text": "黄昏海边，海浪轻轻拍打礁石，镜头缓慢推进"
        },
        {
          "type": "image",
          "url": "https://example.com/first.jpg",
          "role": "first_frame"
        }
      ],
      "duration": 10,
      "resolution": "720p",
      "ratio": "16:9",
      "timeout": 88200,
      "watermark": true,
      "provider_specific": {
        "generate_audio": true
      }
    }'
  ```
</RequestExample>

## 说明

创建视频生成任务，支持 Seedance 系列模型的文本生成视频、首尾帧图生视频、参考素材生成视频等模式。

<Note>
  视频生成为异步任务，创建成功后返回 `task_id`，请通过
  [查询视频生成状态](/api-reference/endpoint/video/status) 轮询进度与最终结果。
</Note>

## 接口概览

| 项目           | 值                                           |
| :----------- | :------------------------------------------ |
| 接口地址         | `https://api.senseaudio.cn/v1/video/create` |
| 请求方式         | `POST`                                      |
| Content-Type | `application/json`                          |
| 鉴权方式         | Bearer Token                                |

## 请求头

| 参数名             |  必填 | 说明                           | 示例                    |
| :-------------- | :-: | :--------------------------- | :-------------------- |
| `Authorization` |  是  | 鉴权 Token，格式 `Bearer API_KEY` | `Bearer sk-123456...` |
| `Content-Type`  |  是  | 固定为 `application/json`       | `application/json`    |

## 请求参数

### 顶层参数

| 参数名                 | 类型     |  必填 | 描述                                    |
| :------------------ | :----- | :-: | :------------------------------------ |
| `model`             | string |  是  | 模型名称                                  |
| `content`           | array  |  是  | 视频内容描述（文本、图片、音频或视频）                   |
| `duration`          | int    |  是  | 视频时长（秒）                               |
| `resolution`        | string |  是  | 分辨率，如 `480p`、`720p`、`1080p`           |
| `ratio`             | string |  是  | 宽高比，如 `16:9`、`9:16`、`4:3`、`3:4`、`1:1` |
| `timeout`           | int    |  否  | 最大超时时间（秒），min：3600，max：172800         |
| `watermark`         | bool   |  否  | 是否添加水印，默认添加                           |
| `provider_specific` | object |  否  | 厂商特定参数（JSON 对象）                       |

### content 元素

| 参数名         | 类型     |  必填 | 描述                                                      |
| :---------- | :----- | :-: | :------------------------------------------------------ |
| `type`      | string |  是  | 内容类型：`text`、`image`、`audio`、`video`                     |
| `text`      | string |  否  | 当 `type` 为 `text` 时，填写文本内容（提示词）                         |
| `url`       | string |  否  | 当 `type` 为 `image` 时，填写图片 URL（支持 http/https 及 data URL） |
| `role`      | string |  否  | 当 `type` 为 `image` 时，指定图片作用，取值见下表                       |
| `audio_url` | string |  否  | 当 `type` 为 `audio` 时，填写音频 URL                           |
| `video_url` | string |  否  | 当 `type` 为 `video` 时，填写视频 URL                           |

## 模型说明

以下为 `doubao-seedance-2-0-260128` 支持的参数、`content` 组合与 `provider_specific` 说明及示例。

**支持参数**

* `ratio`：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`
* `resolution`：`480p`、`720p`、`1080p`
* `duration`：4 \~ 15 秒之间的整数
* `provider_specific`：`{"generate_audio": true}`

**content 组合（两种模式不可混用）**

* 首尾帧模式：`text`（可选，最多 1 条）+ `image`（仅 `first_frame` / `last_frame`，首帧必传，尾帧可选）
* 参考素材模式：`text`（可选，最多 1 条）+ `reference` 图片（≤ 9 张）+ `audio`（≤ 3 条）+ `video`（≤ 3 条）

<Warning>
  不支持同一请求中混用首尾帧与参考素材；仅传 `audio` 不合法，必须至少搭配 `image` 或 `video`。
</Warning>

**代码示例**

<CodeGroup>
  ```bash 纯文本 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "黄昏海边，海浪轻轻拍打礁石，镜头缓慢推进"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 10,
    "watermark": true,
    "provider_specific": {"generate_audio": true}
  }'
  ```

  ```bash 首帧图生视频 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "镜头从女孩侧脸缓慢推进，发丝被微风吹动"},
      {"type": "image", "url": "https://example.com/first.jpg", "role": "first_frame"}
    ],
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5,
    "watermark": false,
    "provider_specific": {"generate_audio": false}
  }'
  ```

  ```bash 首尾帧图生视频 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "镜头从街头咖啡店门口推进到室内，最后停在窗边座位"},
      {"type": "image", "url": "https://example.com/first.jpg", "role": "first_frame"},
      {"type": "image", "url": "https://example.com/last.jpg", "role": "last_frame"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 8,
    "watermark": false,
    "provider_specific": {"generate_audio": false}
  }'
  ```

  ```bash 参考图 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "保留人物服饰与场景氛围，生成一段自然运镜的短视频"},
      {"type": "image", "url": "https://example.com/ref1.jpg", "role": "reference"},
      {"type": "image", "url": "https://example.com/ref2.jpg", "role": "reference"}
    ],
    "resolution": "720p",
    "ratio": "3:4",
    "duration": 10,
    "watermark": false,
    "provider_specific": {"generate_audio": true}
  }'
  ```

  ```bash 参考图+音频 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "根据参考图生成广告短片，整体节奏贴合背景音乐"},
      {"type": "image", "url": "https://example.com/ref1.jpg", "role": "reference"},
      {"type": "audio", "audio_url": "https://example.com/bgm.mp3"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 10,
    "watermark": false,
    "provider_specific": {"generate_audio": true}
  }'
  ```

  ```bash 参考视频+参考图+音频 theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告..."},
      {"type": "image", "url": "https://example.com/pic1.jpg", "role": "reference"},
      {"type": "image", "url": "https://example.com/pic2.jpg", "role": "reference"},
      {"type": "audio", "audio_url": "https://example.com/audio1.mp3"},
      {"type": "video", "video_url": "https://example.com/video1.mp4"}
    ],
    "duration": 10,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "provider_specific": {"generate_audio": true}
  }'
  ```
</CodeGroup>

## 字段细则

<AccordionGroup>
  <Accordion title="role 字段说明" icon="image">
    * `doubao-seedance-2-0-260128`支持 `first_frame` / `last_frame` 或 `reference`，两种模式不可混用
  </Accordion>

  <Accordion title="provider_specific 字段说明" icon="sliders">
    * 该字段传入 JSON 对象，仅 `doubao-seedance-2-0-260128`支持
    * `doubao-seedance-2-0-260128`：`{"generate_audio": true}`
    * 传入不支持的字段会直接忽略
  </Accordion>
</AccordionGroup>

## 素材格式要求

<AccordionGroup>
  <Accordion title="图片" icon="image">
    * **格式**：jpeg、png、webp、bmp、tiff、gif；
    * **宽高比（宽 / 高）**：(0.4, 2.5)
    * **宽高尺寸（px）**：(300, 6000)
    * **大小**：单张 ≤ 30 MB，请求体 ≤ 64 MB；大文件请勿使用 Base64 编码
  </Accordion>

  <Accordion title="音频" icon="music">
    * **格式**：wav、mp3 - **时长**：单条 \[2, 15] s，最多 3 条，总时长 ≤ 15 s -
      **大小**：单条 ≤ 15 MB，请求体 ≤ 64 MB；大文件请勿使用 Base64 编码
  </Accordion>

  <Accordion title="视频" icon="video">
    * **格式**：mp4、mov
    * **分辨率**：480p、720p
    * **时长**：单条 \[2, 15] s，最多 3 条，总时长 ≤ 15 s
    * **宽高比（宽 / 高）**：\[0.4, 2.5]
    * **宽高尺寸（px）**：\[300, 6000]
    * **总像素数**：\[640×640=409600, 834×1112=927408]
    * **大小**：单条 ≤ 50 MB
    * **帧率 (FPS)**：\[24, 60]
  </Accordion>
</AccordionGroup>

## 响应结构

| 参数名       | 类型     | 描述               |
| :-------- | :----- | :--------------- |
| `task_id` | string | 任务 ID，用于查询视频生成状态 |

```json 响应示例 theme={null}
{
  "task_id": "task_1234567890"
}
```

## 通用代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.senseaudio.cn/v1/video/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "根据参考图生成一段自然运镜的商品短片"},
      {"type": "image", "url": "https://example.com/ref1.jpg", "role": "reference"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 10,
    "watermark": false,
    "provider_specific": {"generate_audio": true}
  }'
  ```

  ```python Python theme={null}
  import requests

  API_URL = "https://api.senseaudio.cn/v1/video/create"
  HEADERS = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  def create_video(content, model="doubao-seedance-2-0-260128", **kwargs):
      data = {"model": model, "content": content, **kwargs}
      resp = requests.post(API_URL, headers=HEADERS, json=data)
      return resp.json() if resp.status_code == 200 else None

  result = create_video(
      content=[
          {"type": "text", "text": "根据参考图生成一段自然运镜的商品短片"},
          {"type": "image", "url": "https://example.com/ref1.jpg", "role": "reference"}
      ],
      ratio="16:9",
      duration=10,
      resolution="720p",
      provider_specific={"generate_audio": True}
  )
  print(f"任务ID: {result['task_id']}")
  ```

  ```javascript JavaScript theme={null}
  const axios = require("axios");

  const API_URL = "https://api.senseaudio.cn/v1/video/create";
  const HEADERS = {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  };

  async function createVideo(content, model = "doubao-seedance-2-0-260128", options = {}) {
    const data = { model, content, ...options };
    const res = await axios.post(API_URL, data, { headers: HEADERS });
    return res.data;
  }

  createVideo(
    [
      { type: "text", text: "根据参考图生成一段自然运镜的商品短片" },
      { type: "image", url: "https://example.com/ref1.jpg", role: "reference" },
    ],
    "doubao-seedance-2-0-260128",
    {
      ratio: "16:9",
      duration: 10,
      resolution: "720p",
      provider_specific: { generate_audio: true },
    },
  ).then((r) => console.log(`任务ID: ${r.task_id}`));
  ```
</CodeGroup>

## 注意事项

<Note>
  * **内容描述**：`text`
    元素建议清晰描述场景、动作、风格等信息，有助于提升稳定性 -
    **素材组合**：`doubao-seedance-2-0-260128` 的首尾帧模式与参考素材模式不可混用 -
    **音频限制**：仅传 `audio` 不合法，必须至少搭配 `image` 或 `video` -
    **处理时间**：视频生成耗时较长，建议使用轮询方式
    [查询任务状态](/api-reference/endpoint/video/status)
</Note>


# 查询视频生成状态
Source: https://docs.senseaudio.cn/api-reference/endpoint/video/status

GET /v1/video/status

## 说明

根据任务 ID 查询视频生成任务的当前状态、进度与最终结果。

<Note>
  视频生成为异步任务，建议创建任务后每 5–10 秒轮询一次状态，直到返回 `completed` 或 `failed`。
</Note>

## 接口概览

| 项目           | 值                                           |
| :----------- | :------------------------------------------ |
| 接口地址         | `https://api.senseaudio.cn/v1/video/status` |
| 请求方式         | `GET`                                       |
| Content-Type | `application/json`                          |
| 鉴权方式         | Bearer Token                                |

## 请求头

| 参数名             |  必填 | 说明                                      | 示例                    |
| :-------------- | :-: | :-------------------------------------- | :-------------------- |
| `Authorization` |  是  | 鉴权 Token，格式 `Bearer SENSEAUDIO_API_KEY` | `Bearer sk-123456...` |
| `Content-Type`  |  是  | 固定为 `application/json`                  | `application/json`    |

## 请求参数（Query）

| 参数名  | 类型     |  必填 | 描述            |
| :--- | :----- | :-: | :------------ |
| `id` | string |  是  | 创建任务时返回的任务 ID |

## 响应结构

| 参数名                 | 类型      | 描述                      |
| :------------------ | :------ | :---------------------- |
| `id`                | string  | 记录 ID                   |
| `model`             | string  | 模型名称                    |
| `task_id`           | string  | 任务 ID                   |
| `status`            | string  | 任务状态，见下表                |
| `progress`          | int64   | 进度百分比                   |
| `video_url`         | string  | 视频 URL（`completed` 后返回） |
| `duration`          | int64   | 实际视频时长（秒）               |
| `is_new`            | boolean | 是否为新视频                  |
| `error_message`     | string  | 错误信息（`failed` 时返回）      |
| `created_at`        | int64   | 创建时间戳                   |
| `completed_at`      | int64   | 完成时间戳                   |
| `prompt`            | string  | 提示词                     |
| `resolution`        | string  | 分辨率，如 `720p`            |
| `ratio`             | string  | 宽高比，如 `16:9`、`9:16`     |
| `content`           | array   | 描述视频的文字或图片              |
| `provider_specific` | object  | 模型特殊参数                  |

### 状态说明

| 状态值          | 说明   |
| :----------- | :--- |
| `pending`    | 等待处理 |
| `processing` | 处理中  |
| `completed`  | 已完成  |
| `failed`     | 失败   |

### 响应示例

```json theme={null}
{
  "id": "52e0c397-2f78-4c1f-8774-d51aba5e4e3c",
  "model": "Seedance-2.0",
  "task_id": "c4666acd-60fa-4e1e-8c8b-72ae129f7a4d",
  "status": "pending",
  "progress": 0,
  "duration": 10,
  "is_new": true,
  "created_at": 1773822549,
  "prompt": "",
  "resolution": "720p",
  "content": [
    {
      "type": "text",
      "text": "黄昏海边，海浪轻轻拍打礁石，镜头缓慢推进"
    }
  ],
  "ratio": "16:9"
}
```

## 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.senseaudio.cn/v1/video/status?id=task_1234567890" \
  -H "Authorization: Bearer SENSEAUDIO_API_KEY" \
  -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  import requests
  import time

  API_URL = "https://api.senseaudio.cn/v1/video/status"
  HEADERS = {
      "Authorization": "Bearer SENSEAUDIO_API_KEY",
      "Content-Type": "application/json"
  }

  def get_video_status(task_id):
      resp = requests.get(API_URL, headers=HEADERS, params={"id": task_id})
      return resp.json() if resp.status_code == 200 else None

  def poll_video_status(task_id, max_attempts=60):
      """轮询视频状态直到完成"""
      for _ in range(max_attempts):
          result = get_video_status(task_id)
          if result:
              status = result.get("status")
              progress = result.get("progress", 0)
              print(f"状态: {status}, 进度: {progress}%")
              if status == "completed":
                  print(f"视频生成完成: {result.get('video_url')}")
                  return result
              if status == "failed":
                  print(f"生成失败: {result.get('error_message')}")
                  return result
          time.sleep(5)
      return None

  result = poll_video_status("task_1234567890")
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const API_URL = 'https://api.senseaudio.cn/v1/video/status';
  const HEADERS = {
    'Authorization': 'Bearer SENSEAUDIO_API_KEY',
    'Content-Type': 'application/json'
  };

  async function getVideoStatus(taskId) {
    const res = await axios.get(API_URL, { headers: HEADERS, params: { id: taskId } });
    return res.data;
  }

  async function pollVideoStatus(taskId, maxAttempts = 60) {
    for (let i = 0; i < maxAttempts; i++) {
      const result = await getVideoStatus(taskId);
      if (result) {
        const { status, progress } = result;
        console.log(`状态: ${status}, 进度: ${progress}%`);
        if (status === 'completed') {
          console.log(`视频生成完成: ${result.video_url}`);
          return result;
        }
        if (status === 'failed') {
          console.log(`生成失败: ${result.error_message}`);
          return result;
        }
      }
      await new Promise(r => setTimeout(r, 5000));
    }
    return null;
  }

  pollVideoStatus('task_1234567890').then(console.log);
  ```
</CodeGroup>

## 注意事项

<Note>
  * **轮询建议**：视频生成需要时间，建议每 5–10 秒查询一次状态
  * **超时处理**：如果长时间处于 `processing` 状态，可能需要重新创建任务
  * **错误处理**：当 `status` 为 `failed` 时，查看 `error_message` 了解失败原因
</Note>


# 异步人声分离
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice-isolation/async

api-reference/endpoint/voice-isolation/voice-isolation.openapi.json POST /v1/isolation/async
异步上传音频文件并创建人声分离任务。接口会立即返回任务 ID。

## 说明

异步方式进行人声分离。接口会在任务创建后立即返回 `task_id`。获得 `task_id` 后，可使用[查询人声分离任务 API](/api-reference/endpoint/voice-isolation/pending)轮询任务状态与分离结果。

对于需要保持 HTTP 请求连接并直接返回分离结果的场景，见[同步人声分离 API](/api-reference/endpoint/voice-isolation/sync)。

## 音频要求

* 上传字段固定为 `file`
* 支持的音频格式、时长与文件大小限制以服务端校验规则为准
* 当文件不符合模型要求或音频格式非法时，服务端将返回 `400`

<Warning>
  在线 Playground 会先通过文档站代理上传文件，较大的音视频文件可能触发 `413 Request Entity Too Large`。如需测试较大文件，请使用下方 `curl` 示例或 SDK 从本地直连 `https://api.senseaudio.cn`。
</Warning>

## 请求示例

```bash theme={null}
curl --request POST 'https://api.senseaudio.cn/v1/isolation/async' \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'model=senseaudio-voice-isolation-1.0-260319' \
  --form 'file=@/path/to/sample.wav'
```


# 查询人声分离任务
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice-isolation/pending

api-reference/endpoint/voice-isolation/voice-isolation.openapi.json GET /v1/isolation/pending
查询异步人声分离任务的处理状态与结果。

## 说明

使用异步方式提交人声分离任务后，可通过本接口查询任务状态与分离结果。

## 状态说明

| 状态          | 说明                         |
| ----------- | -------------------------- |
| `pending`   | 任务已提交，正在排队或处理中             |
| `completed` | 任务处理成功，可读取 `result_url`    |
| `failed`    | 任务处理失败，可读取 `error_message` |

## 请求示例

```bash theme={null}
curl --request GET 'https://api.senseaudio.cn/v1/isolation/pending?task_id=9e4f0f7c-1c5c-4a1d-8a73-2d86d58c0d1b' \
  --header 'Authorization: Bearer <API_KEY>'
```


# 同步人声分离
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice-isolation/sync

api-reference/endpoint/voice-isolation/voice-isolation.openapi.json POST /v1/isolation/sync
同步上传音频文件并执行人声分离。接口会在处理完成后直接返回分离结果。

## 说明

同步方式进行人声分离。请求需要上传音频文件，并在 HTTP 连接中等待处理完成。处理成功后，接口会直接返回分离后的人声音频 URL。

对于不需要持续保持 HTTP 连接、希望先获取任务 ID 再查询结果的场景，见[异步人声分离 API](/api-reference/endpoint/voice-isolation/async)。

## 音频要求

* 上传字段固定为 `file`
* 支持的音频格式、时长与文件大小限制以服务端校验规则为准
* 当文件不符合模型要求或音频格式非法时，服务端将返回 `400`

<Warning>
  在线 Playground 会先通过文档站代理上传文件，较大的音视频文件可能触发 `413 Request Entity Too Large`。如需测试较大文件，请使用下方 `curl` 示例或 SDK 从本地直连 `https://api.senseaudio.cn`。
</Warning>

## 请求示例

```bash theme={null}
curl --request POST 'https://api.senseaudio.cn/v1/isolation/sync' \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'model=senseaudio-voice-isolation-1.0-260319' \
  --form 'file=@/path/to/sample.wav'
```


# Minimax 兼容音色克隆
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice/clone

POST /v1/voice_clone

## 说明

使用 Minimax 兼容格式生成克隆音色。调用前请先通过 [上传文件](/api-reference/endpoint/files/upload) 获取 `file_id`。

* **生成链路**：上传音频获取 `file_id` → 调用本接口生成音色 ID → 在 TTS 接口中使用该音色。
* **音色 ID**：本接口使用 `voice_id` 作为自定义音色 ID，生成后继续在 `voice_setting.voice_id` 中传入。
* **克隆模型**：当前使用 `sensenova-tts-multilingual-2.0`。

## 调用示例

### 1. 上传参考音频

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/voice.wav"
```

上传成功后，从返回结果中读取 `file.file_id`：

```json theme={null}
{
  "file": {
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "filename": "voice.wav",
    "bytes": 228778,
    "purpose": "voice_clone"
  }
}
```

### 2. 生成克隆音色

```bash theme={null}
curl --request POST \
  --url https://api.senseaudio.cn/v1/voice_clone \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "model": "sensenova-tts-multilingual-2.0",
    "text": "你好，这是我的 Minimax 兼容克隆音色试听。",
    "voice_id": "wenrou_yujie_minimax_001"
  }'
```

## 使用克隆音色

生成成功后，将 `voice_id` 传入 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)：

```json theme={null}
{
  "model": "sensenova-tts-2.0",
  "text": "你好，这是使用 Minimax 兼容克隆音色生成的音频。",
  "voice_setting": {
    "voice_id": "wenrou_yujie_minimax_001"
  }
}
```


# SenseAudio 音色克隆
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice/clone-senseaudio

POST /v1/voice/clone

## 说明

使用已上传的参考音频生成克隆音色。调用前请先通过 [上传文件](/api-reference/endpoint/files/upload) 获取 `file_id`。

* **生成链路**：上传音频获取 `file_id` → 调用本接口生成音色 ID → 在 TTS 接口中使用该音色。
* **音色 ID**：本接口使用 `label` 作为自定义音色 ID，生成后在 `voice_setting.voice_id` 中传入该 `label`。
* **克隆模型**：当前使用 `sensenova-tts-multilingual-2.0`。

## 调用示例

### 1. 上传参考音频

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/voice.wav"
```

上传成功后，从返回结果中读取 `file.file_id`：

```json theme={null}
{
  "file": {
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "filename": "voice.wav",
    "bytes": 228778,
    "purpose": "voice_clone"
  }
}
```

### 2. 生成克隆音色

```bash theme={null}
curl --request POST \
  --url https://api.senseaudio.cn/v1/voice/clone \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "温柔御姐，普通话，语气自然",
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "model": "sensenova-tts-multilingual-2.0",
    "text": "你好，这是我的克隆音色试听。",
    "label": "wenrou_yujie_001"
  }'
```

## 使用克隆音色

生成成功后，将 `label` 作为 `voice_setting.voice_id` 传入 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)：

```json theme={null}
{
  "model": "sensenova-tts-2.0",
  "text": "你好，这是使用克隆音色生成的音频。",
  "voice_setting": {
    "voice_id": "wenrou_yujie_001"
  }
}
```

## 与 Minimax 兼容接口的区别

| 项目       | SenseAudio 音色克隆                  | Minimax 兼容音色克隆                      |
| -------- | -------------------------------- | ----------------------------------- |
| 路径       | `/v1/voice/clone`                | `/v1/voice_clone`                   |
| 音色 ID 字段 | `label`                          | `voice_id`                          |
| 音色描述     | 支持 `description`                 | 不包含 `description`                   |
| 生成后使用方式  | `voice_setting.voice_id = label` | `voice_setting.voice_id = voice_id` |


# 查询可用音色
Source: https://docs.senseaudio.cn/api-reference/endpoint/voice/list

POST /v1/get_voice



# 接口概览
Source: https://docs.senseaudio.cn/api-reference/introduction

SenseAudio 开放平台全模态 API 接口速览

SenseAudio 开放平台提供覆盖**文本、语音、音频、图像、视频、音乐、智能体**七大方向的 RESTful API。所有接口采用统一的鉴权方式与错误语义，开发者可基于本页快速定位所需能力。

## 服务地址

所有接口均在以下地址提供服务：

```
https://api.senseaudio.cn
```

## 鉴权

所有接口均使用 **Bearer Token** 鉴权，请在请求头中携带您的 API Key：

```http theme={null}
Authorization: Bearer <Your_API_Key>
```

API Key 的创建与管理详见 [快速接入](/guides/account/quick-access)，或直接前往 [SenseAudio API 平台 API 密钥](https://senseaudio.cn/api-platform/api-key)。

## 接口分组

<CardGroup>
  <Card title="语音合成" icon="waveform-lines" href="/api-reference/endpoint/tts/synthesize">
    将文本合成为富有情感的 AI 语音，支持多情绪、多风格、多音字纠正、公式朗读。
  </Card>

  <Card title="音频生成" icon="file-audio" href="/api-reference/endpoint/audio/generate">
    通过提示词、参考音色、参考音频和参考图片生成多角色对白、背景音乐与环境音效。
  </Card>

  <Card title="语音识别" icon="ear" href="/api-reference/endpoint/asr/transcriptions">
    音频转写、质检分析与历史记录查询，覆盖通用、极速、语义、整编、质检五档模型。
  </Card>

  <Card title="同声传译" icon="language" href="/api-reference/endpoint/simultaneous-interpretation/websocket">
    实时接收 PCM 音频，流式返回识别原文、译文和可选的译文语音。
  </Card>

  <Card title="人声分离" icon="headphones" href="/api-reference/endpoint/voice-isolation/sync">
    上传音频并分离人声，支持同步返回结果或异步轮询任务状态。
  </Card>

  <Card title="文本生成" icon="sparkles" href="/api-reference/endpoint/llm/chat">
    兼容 OpenAI / Anthropic 协议的多模态大模型接口，支持对话、消息与响应三种风格。
  </Card>

  <Card title="图片生成" icon="image" href="/api-reference/endpoint/image/sync">
    同步 / 异步图片生成与任务状态查询，覆盖常规尺寸与高分辨率输出。
  </Card>

  <Card title="音乐生成" icon="music" href="/api-reference/endpoint/music/song-create-v2">
    歌词生成、歌词改写与完整歌曲合成，支持风格控制、结构化歌词与纯音乐模式。
  </Card>

  <Card title="音效生成" icon="music-4" href="/api-reference/endpoint/sfx/create">
    根据文本描述同步生成 1-4 个音效变体，支持时长、变体数量和输出格式控制。
  </Card>

  <Card title="视频生成" icon="video" href="/api-reference/endpoint/video/create">
    视频生成服务面向短视频创作、营销素材制作、内容可视化和创意分镜生成等场景。
  </Card>

  <Card title="实时智能体" icon="robot" href="/api-reference/endpoint/realtime/invoke">
    实时语音对话式智能体，支持会话邀请、状态查询与离会。
  </Card>

  <Card title="自定义智能体" icon="cog" href="/api-reference/endpoint/custom-agent/create">
    创建、更新、查询与删除自定义智能体，可绑定 LLM 模型与系统音色。
  </Card>
</CardGroup>

## 全部接口一览

### 语音合成

| 接口                                                            | 方法        | 路径              |
| ------------------------------------------------------------- | --------- | --------------- |
| [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)           | POST      | `/v1/t2a_v2`    |
| [语音合成 HTTP 流式](/api-reference/endpoint/tts/synthesize-stream) | POST      | `/v1/t2a_v2`    |
| [语音合成 WebSocket](/api-reference/endpoint/tts/websocket)       | WebSocket | `/ws/v1/t2a_v2` |

### 音频生成

| 接口                                             | 方法   | 路径                   |
| ---------------------------------------------- | ---- | -------------------- |
| [音频生成](/api-reference/endpoint/audio/generate) | POST | `/v1/audio/generate` |

### 克隆音色

| 接口                                           | 方法   | 路径              |
| -------------------------------------------- | ---- | --------------- |
| [查询可用音色](/api-reference/endpoint/voice/list) | POST | `/v1/get_voice` |

### 语音识别

| 接口                                                      | 方法        | 路径                            |
| ------------------------------------------------------- | --------- | ----------------------------- |
| [语音识别转写](/api-reference/endpoint/asr/transcriptions)    | POST      | `/v1/audio/transcriptions`    |
| [语音识别 WebSocket](/api-reference/endpoint/asr/websocket) | WebSocket | `/ws/v1/audio/transcriptions` |
| [音频质量检测](/api-reference/endpoint/asr/analysis)          | POST      | `/v1/audio/analysis`          |
| [语音识别历史](/api-reference/endpoint/asr/records)           | GET       | `/v1/audio/records`           |

### 同声传译

| 接口                                                                              | 方法        | 路径                                  |
| ------------------------------------------------------------------------------- | --------- | ----------------------------------- |
| [同声传译 WebSocket](/api-reference/endpoint/simultaneous-interpretation/websocket) | WebSocket | `/ws/v1/audio/simulat-interpreting` |

### 人声分离

| 接口                                                          | 方法   | 路径                      |
| ----------------------------------------------------------- | ---- | ----------------------- |
| [同步人声分离](/api-reference/endpoint/voice-isolation/sync)      | POST | `/v1/isolation/sync`    |
| [异步人声分离](/api-reference/endpoint/voice-isolation/async)     | POST | `/v1/isolation/async`   |
| [查询人声分离任务](/api-reference/endpoint/voice-isolation/pending) | GET  | `/v1/isolation/pending` |

### 文本生成

| 接口                                                          | 方法   | 路径                     |
| ----------------------------------------------------------- | ---- | ---------------------- |
| [对话（Chat）API](/api-reference/endpoint/llm/chat)             | POST | `/v1/chat/completions` |
| [消息（Messages）](/api-reference/endpoint/llm/messages)        | POST | `/v1/messages`         |
| [模型响应（Responses）API](/api-reference/endpoint/llm/responses) | POST | `/v1/responses`        |

### 图片生成

| 接口                                              | 方法   | 路径                  |
| ----------------------------------------------- | ---- | ------------------- |
| [同步图片生成](/api-reference/endpoint/image/sync)    | POST | `/v1/image/sync`    |
| [异步图片生成](/api-reference/endpoint/image/async)   | POST | `/v1/image/async`   |
| [查询图片任务](/api-reference/endpoint/image/pending) | GET  | `/v1/image/pending` |

### 音乐生成

| 接口                                                      | 方法   | 路径                                 |
| ------------------------------------------------------- | ---- | ---------------------------------- |
| [歌词生成](/api-reference/endpoint/music/lyrics-create)     | POST | `/v1/music/lyrics/create`          |
| [歌词改写](/api-reference/endpoint/music/lyrics-revise)     | POST | `/v1/music/lyrics/revise`          |
| [歌曲生成 V1](/api-reference/endpoint/music/song-create-v1) | POST | `/v1/music/song/create`            |
| [歌曲生成 V2](/api-reference/endpoint/music/song-create-v2) | POST | `/v2/music/song/create`            |
| [查询歌曲任务](/api-reference/endpoint/music/song-pending)    | GET  | `/v1/music/song/pending/{task_id}` |

### 音效生成

| 接口                                         | 方法   | 路径                              |
| ------------------------------------------ | ---- | ------------------------------- |
| [音效生成](/api-reference/endpoint/sfx/create) | POST | `/v1/sound-effects/generations` |

### 视频生成

| 接口                                               | 方法   | 路径                    |
| ------------------------------------------------ | ---- | --------------------- |
| [创建视频生成任务](/api-reference/endpoint/video/create) | POST | `/v1/video/create`    |
| [查询视频生成状态](/api-reference/endpoint/video/status) | GET  | `/v1/video/{task_id}` |

### 实时智能体

| 接口                                                     | 方法   | 路径                    |
| ------------------------------------------------------ | ---- | --------------------- |
| [获取 Agent 列表](/api-reference/endpoint/realtime/agents) | GET  | `/v1/realtime/agents` |
| [创建实时会话](/api-reference/endpoint/realtime/invoke)      | POST | `/v1/realtime/invoke` |
| [查询 Agent 状态](/api-reference/endpoint/realtime/status) | GET  | `/v1/realtime/status` |
| [停止实时会话](/api-reference/endpoint/realtime/leave)       | POST | `/v1/realtime/leave`  |

### 自定义智能体

| 接口                                                          | 方法     | 路径                     |
| ----------------------------------------------------------- | ------ | ---------------------- |
| [创建自定义 Agent](/api-reference/endpoint/custom-agent/create)  | POST   | `/v1/agent`            |
| [更新自定义 Agent](/api-reference/endpoint/custom-agent/update)  | PUT    | `/v1/agent/{agent_id}` |
| [获取自定义 Agent 列表](/api-reference/endpoint/custom-agent/list) | GET    | `/v1/agents`           |
| [删除自定义 Agent](/api-reference/endpoint/custom-agent/delete)  | DELETE | `/v1/agent/{agent_id}` |

## 通用约定

* **请求格式**：除文件上传外，均使用 `application/json` 作为请求体格式
* **响应格式**：所有响应均为 `application/json`，UTF-8 编码
* **幂等与重试**：对于耗时较长的生成类任务（图片异步、视频、音乐），创建接口会返回 `task_id`，请通过对应的状态查询接口轮询结果
* **错误码**：HTTP 状态码遵循标准语义；响应体中包含 `code` 与 `message` 字段描述错误详情

## 相关资源

<CardGroup>
  <Card title="快速接入" icon="rocket" href="/guides/account/quick-access">
    获取 API Key 并完成首个请求。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    浏览全部可调用模型与能力概览。
  </Card>

  <Card title="API 计费" icon="credit-card" href="/guides/account/billing">
    查看各项 API 的积分消耗规则。
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/faq/overview">
    接入过程中的常见问题解答。
  </Card>
</CardGroup>


# 创作台计费
Source: https://docs.senseaudio.cn/guides/account/billing

SenseAudio 平台计费与用量说明

SenseAudio 开放平台根据不同功能使用情况进行扣费。本文档详细说明各项服务的计费规则。

<Note>
  每个模型都列出「优惠前」与「优惠后」两档价格。若素材库未提供明确的优惠后价格，则视为优惠后价格等同于优惠前价格。
</Note>

## 计费方式

计费顺序

* 第一优先级：套餐积分
* 第二优先级：代金券（1元 = 5,000积分）
* 第三优先级：现金余额（1元 = 5,000积分）
  （额外用量：代金券+现金余额）

平台将优先使用积分，若积分余额不足，将触发额外用量（默认开启），优先使用代金券进行抵扣，当代金券余额不足时，使用现金余额进行支付。

（您可根据实际需求开启或关闭额外用量。关闭额外用量后，平台将不再使用您的代金券及现金余额进行扣费。）

## 语音合成

**语音工作室/文本转语音**

根据输入文本的字符数量计费。

**字符规则**

* 汉字字符：1 个汉字 = 2 个字符；
* 非汉字字符：英文字母、希腊字母、标点、特殊符号、空格、回车等 = 1 个字符；

**SenseAudio 自研模型**

| 模型名称                   | 字符类型  | 价格           |
| ---------------------- | ----- | ------------ |
| **SenseAudio-TTS-1.5** | 汉语字符  | 3.5 元 / 万字符  |
| **SenseAudio-TTS-1.5** | 非汉语字符 | 1.75 元 / 万字符 |
| **SenseNova-TTS-2.0**  | 汉语字符  | 3.5 元 / 万字符  |
| **SenseNova-TTS-2.0**  | 非汉语字符 | 1.75 元 / 万字符 |

## 音频生成

按生成音频时长计费。每生成 1 秒音频消耗 85 积分，约为 0.017 元 / 秒。

| 模型名称          | 优惠前         | 优惠后 |
| ------------- | ----------- | --- |
| SenseAudio-A1 | 0.017 元 / 秒 | —   |

## 视频生成

按视频时长和分辨率计费。

| 模型名称                    | 分辨率   | 原价        | 优惠后       |
| ----------------------- | ----- | --------- | --------- |
| **Doubao-Seedance-2.0** | 480P  | 1 元 / 秒   | 0.5 元 / 秒 |
| **Doubao-Seedance-2.0** | 720P  | 2 元 / 秒   | 1 元 / 秒   |
| **Doubao-Seedance-2.0** | 1080P | 6.2 元 / 秒 | 3.1 元 / 秒 |

## 图片生成

按生成图片的张数计费。

| 模型名称                         | 优惠前       | 优惠后        |
| ---------------------------- | --------- | ---------- |
| **SenseAudio-Image-2.0**     | 1 元 / 张   | 0.5 元 / 张  |
| **SenseAudio-Image-1.0**     | 0.2 元 / 张 | —          |
| **Doubao-Seedream-5.0-Lite** | 0.5 元 / 张 | 0.22 元 / 张 |
| **SenseNova-U1-Fast**        | 0.5 元 / 张 | —          |

## 音乐生成

以生成音乐的首数计费。

**SenseAudio 自研模型**

| 模型名称                     | 优惠前     | 优惠后       |
| ------------------------ | ------- | --------- |
| **SenseAudio-Music-1.0** | 1 元 / 首 | 0.5 元 / 首 |
| **SenseAudio-Music-2.0** | 1 元 / 首 | 0.5 元 / 首 |

## 音效生成

按生成音效的组数计费，创作台默认生成 4 条。

| 模型名称                            | 优惠前        | 优惠后 |
| ------------------------------- | ---------- | --- |
| **SenseAudio-Sound-Effect-1.0** | 0.08 元 / 组 | —   |

## 角色广场

按通话时长计费。

| 时长单位 | 优惠前        | 优惠后        |
| ---- | ---------- | ---------- |
| 每秒   | 0.01 元 / 秒 | 0.01 元 / 秒 |
| 每分钟  | 0.6 元 / 分钟 | 0.6 元 / 分钟 |

## 音色克隆

* 进行音色克隆需消耗生成次数。
* 音色克隆和文生音色共享同一组生成次数额度，次数额度由套餐等级决定。
* 每次保存成功会消耗 1 次生成额度。
* 每种订阅套餐会赠送对应数量的生成次数，具体规则详见 [Token Plan](/guides/account/token-plan)。
* 使用已保存的克隆音色合成语音，计费规则同「语音合成」。

## 文生音色

* 文生音色需消耗生成次数。
* 音色克隆和文生音色共享同一组生成次数额度，次数额度由套餐等级决定。
* 每次保存成功会消耗 1 次生成额度。
* 每种订阅套餐会赠送对应数量的生成次数，具体规则详见 [Token Plan](/guides/account/token-plan)。
* 使用已保存的文生音色合成语音，计费规则同「语音合成」。

## 语音识别

按音频时长计费（按秒计费，不足 1 秒按 1 秒计时）。

**SenseAudio 自研模型**

| 模型名称                             | 优惠前        | 优惠后        |
| -------------------------------- | ---------- | ---------- |
| **SenseAudio-ASR-Lite-1.5**      | 0.9 元 / 小时 | 0.9 元 / 小时 |
| **SenseAudio-ASR-1.5**           | 1.8 元 / 小时 | 1.8 元 / 小时 |
| **SenseAudio-ASR-Check-1.5**     | 3.6 元 / 小时 | 3.6 元 / 小时 |
| **SenseAudio-ASR-Pro-1.5**       | 3.6 元 / 小时 | 3.6 元 / 小时 |
| **SenseAudio-ASR-DeepThink-1.5** | 3.6 元 / 小时 | 3.6 元 / 小时 |

## 同声传译

同声传译按时长计费（按秒计费，不足 1 秒按 1 秒计时）。

| 模型名称                            | 优惠前     | 优惠后 |
| ------------------------------- | ------- | --- |
| **SenseNova-LiveTranslate-1.0** | 50 积分/秒 | —   |

## 人声分离

人声分离属于 **SenseAudio 系列（自研）**，按音频时长计费（按秒计费，不足 1 秒按 1 秒计时）。

| 模型名称                           | 优惠前        | 优惠后        |
| ------------------------------ | ---------- | ---------- |
| **SenseAudio-Voice-Isolation** | 0.04 元 / 秒 | 0.04 元 / 秒 |

如需了解接口用法，请见 [人声分离介绍](/guides/voice-isolation/overview) 与 [人声分离 API 参考](/api-reference/endpoint/voice-isolation/sync)。

## 端到端实时语音模型

按实时语音会话中的音频时长计费。

| 模型名称                        | 优惠前        | 优惠后 |
| --------------------------- | ---------- | --- |
| **SenseAudio-Realtime-1.0** | 0.6 元 / 分钟 | —   |

### 其他通用模型

| 模型名称                         | 优惠前        | 优惠后        |
| ---------------------------- | ---------- | ---------- |
| **Doubao-Seedream-5.0-Lite** | 0.22 元 / 张 | 0.22 元 / 张 |

## 相关资源

<CardGroup>
  <Card title="快速接入" icon="rocket" href="/guides/account/quick-access">
    获取 API Key 并完成首个请求。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看所有可调用模型与计费概览。
  </Card>

  <Card title="Token Plan" icon="book-open" href="/guides/account/token-plan">
    查看套餐等级与权益。
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference/introduction">
    浏览全部 API 端点与参数说明。
  </Card>
</CardGroup>


# 模型列表
Source: https://docs.senseaudio.cn/guides/account/model-list

可调用的模型名称、能力与计费概览

<Note>
  下表价格按「原价」与「优惠后」两档列出，**加粗数字**为当前生效的优惠价；若未列出优惠后价格，则等同于原价。完整计费规则详见 [API 计费](/guides/account/billing)。
</Note>

## 文本生成

> 计费单位：**元 / 百万 Tokens**

### SenseAudio 自研模型

| 模型名称                     | 模型 ID                           | 输入价格                 | 输出价格                  | 上下文长度 | 最大输入 | 最大输出 |
| ------------------------ | ------------------------------- | -------------------- | --------------------- | ----- | ---- | ---- |
| SenseAudio-S2            | `senseaudio-s2`                 | 原价 15<br />优惠后 **5** | 原价 90<br />优惠后 **30** | 1M    | —    | 128K |
| SenseAudio-S2-Flash      | `senseaudio-s2-flash`           | 原价 4<br />优惠后 **2**  | 原价 24<br />优惠后 **12** | 256K  | 254K | 64K  |
| SenseAudio-S2-Lite       | `senseaudio-s2-lite`            | 原价 2<br />优惠后 **1**  | 原价 12<br />优惠后 **6**  | 256K  | 254K | 64K  |
| SenseAudio-S1            | `senseaudio-s1`                 | 原价 15<br />优惠后 **5** | 原价 90<br />优惠后 **30** | 1M    | —    | 128K |
| SenseAudio-VL-1.0        | `senseaudio-vl-1.0-260319`      | 原价 15<br />优惠后 **5** | 原价 90<br />优惠后 **30** | 1M    | —    | 128K |
| SenseAudio-VL-Lite-1.0   | `senseaudio-vl-lite-1.0-260319` | 原价 2<br />优惠后 **1**  | 原价 12<br />优惠后 **6**  | 256K  | 254K | 64K  |
| SenseNova-6.8-Flash-Lite | `sensenova-6.8-flash-lite`      | 原价 15<br />优惠后 **5** | 原价 90<br />优惠后 **30** | —     | —    | —    |

### 其他通用模型

| 模型名称                                   | 模型 ID                        | 输入价格                    | 输出价格                     | 上下文长度 | 最大输入 | 最大输出 |
| -------------------------------------- | ---------------------------- | ----------------------- | ------------------------ | ----- | ---- | ---- |
| Qwen3.8-27B                            | `qwen3.8-27b`                | 3                       | 12                       | 1M    | 992k | 131K |
| Qwen3.6-35B-A3B                        | `qwen3.6-35b-a3b`            | 1.8                     | 10.8                     | 256K  | 254K | 64K  |
| DeepSeek-V4-Flash-0731                 | `deepseek-v4-flash-0731`     | 3                       | 9                        | 1M    | 616k | 384K |
| Kimi K2.6                              | `kimi-k2.6`                  | 6.5                     | 27                       | 256K  | —    | 256k |
| GLM-5.3-Flash                          | `glm-5.3-flash`              | 0.8                     | 2.8                      | 1M    | —    | 128k |
| GLM-5.2（输入 \< 32K）                     | `glm-5.2`                    | 6                       | 24                       | 1M    | —    | —    |
| GLM-5.2（输入 ≥ 32K）                      | `glm-5.2`                    | 8                       | 28                       | 1M    | —    | —    |
| MiniMax-M2.7                           | `minimax-m2.7`               | 原价 4.2<br />优惠后 **2.1** | 原价 16.8<br />优惠后 **8.4** | 200K  | —    | —    |
| Doubao-Seed-2.0-Pro（输入 ≤ 32K）          | `doubao-seed-2-0-pro-260215` | 3.2                     | 16                       | 256K  | 256K | 128K |
| Doubao-Seed-2.0-Pro（32K \< 输入 ≤ 128K）  | `doubao-seed-2-0-pro-260215` | 4.8                     | 24                       | 256K  | 256K | 128K |
| Doubao-Seed-2.0-Pro（128K \< 输入 ≤ 256K） | `doubao-seed-2-0-pro-260215` | 9.6                     | 48                       | 256K  | 256K | 128K |

<Note>
  **阶梯计费**：GLM-5.2 与 Doubao-Seed-2.0-Pro 按**单次请求的输入 Tokens 长度**适配对应价格档位，输入与输出价格同档计算；阶梯以单次请求实际输入长度为准，不跨请求累加。
</Note>

相关接口：[Chat Completions](/api-reference/endpoint/llm/chat)、[文本生成介绍](/guides/llm/overview)。

## 语音合成

> 计费单位：**元 / 万字符**。1 个汉字 = 2 个字符；英文字母、希腊字母、标点、特殊符号、空格、回车等 = 1 个字符。

| 模型名称               | 模型 ID                       | 价格          | 备注                 |
| ------------------ | --------------------------- | ----------- | ------------------ |
| SenseAudio-TTS-1.5 | `senseaudio-tts-1.5-260319` | 3.5 元 / 万字符 | 多情绪、多风格、多音字纠正、公式朗读 |
| SenseNova-TTS-2.0  | `sensenova-tts-2.0`         | 3.5 元 / 万字符 | 多情绪、多风格、公式朗读       |

相关接口：[语音合成 API](/api-reference/endpoint/tts/synthesize)。

## 语音识别

> 计费单位：**元 / 小时**，按音频时长计费。

| 模型名称                         | 模型 ID                                 | 价格         | 适用场景      |
| ---------------------------- | ------------------------------------- | ---------- | --------- |
| SenseAudio-ASR-Lite-1.5      | `senseaudio-asr-lite-1.5-260319`      | 0.9 元 / 小时 | 轻量、低成本识别  |
| SenseAudio-ASR-1.5           | `senseaudio-asr-1.5-260319`           | 1.8 元 / 小时 | 通用识别      |
| SenseAudio-ASR-Pro-1.5       | `senseaudio-asr-pro-1.5-260319`       | 3.6 元 / 小时 | 专业级高精度识别  |
| SenseAudio-ASR-DeepThink-1.5 | `senseaudio-asr-deepthink-1.5-260319` | 3.6 元 / 小时 | 深度推理增强识别  |
| SenseAudio-ASR-Check-1.5     | `senseaudio-asr-check-1.5-260319`     | 3.6 元 / 小时 | 复核 / 校对场景 |

## 同声传译

> 计费单位：**积分 / 秒**，按时长计费，不足 1 秒按 1 秒计时。

| 模型名称                        | 模型 ID                         | 价格        | 适用场景 |
| --------------------------- | ----------------------------- | --------- | ---- |
| SenseNova-LiveTranslate-1.0 | `sensenova-livetranslate-1.0` | 50 积分 / 秒 | 同声传译 |

相关接口：[同声传译 API](/api-reference/endpoint/simultaneous-interpretation/websocket)、[同声传译介绍](/guides/simultaneous-interpretation/overview)、[同声传译计费](/guides/account/billing)。

## 人声分离

> 计费单位：**元 / 秒**，按音频时长计费（按秒计费，不足 1 秒按 1 秒计时）。

| 模型名称                       | 模型 ID                                   | 价格         | 适用场景 |
| -------------------------- | --------------------------------------- | ---------- | ---- |
| SenseAudio-Voice-Isolation | `senseaudio-voice-isolation-1.0-260319` | 0.04 元 / 秒 | 人声分离 |
| SenseAudio-Voice-Isolation | `senseaudio-voice-isolation-1.5`        | 0.04 元 / 秒 | 人声分离 |

相关接口：[人声分离介绍](/guides/voice-isolation/overview)、[同步人声分离](/api-reference/endpoint/voice-isolation/sync)、[异步人声分离](/api-reference/endpoint/voice-isolation/async)。

## 音乐生成

> 计费单位：**元 / 首**

| 模型名称                 | 模型 ID                         | 原价      | 优惠后           |
| -------------------- | ----------------------------- | ------- | ------------- |
| SenseAudio-Music-1.0 | `senseaudio-music-1.0-260319` | 1 元 / 首 | **0.5 元 / 首** |
| SenseAudio-Music-2.0 | `senseaudio-music-2.0-260626` | 1 元 / 首 | **0.5 元 / 首** |

相关接口：[歌词生成](/api-reference/endpoint/music/lyrics-create)、[歌词改写](/api-reference/endpoint/music/lyrics-revise)、[歌曲生成 V1](/api-reference/endpoint/music/song-create-v1)、[歌曲生成 V2](/api-reference/endpoint/music/song-create-v2)。

## 音效生成

> 计费单位：**0.08 元 / 组**，创作台默认生成 4 条。

| 模型名称                        | 模型 ID                       | 原价         | 优惠后 |
| --------------------------- | --------------------------- | ---------- | --- |
| SenseAudio-Sound-Effect-1.0 | `senseaudio-sfx-1.0-260626` | 0.08 元 / 组 | —   |

相关接口：[音效生成](/api-reference/endpoint/sfx/create)。

## 音频生成

> 计费单位：**积分 / 秒**。按生成音频时长计费，每生成 1 秒音频消耗 85 积分；按 1 元 = 5,000 积分换算，约为 0.017 元 / 秒。

| 模型名称          | 模型 ID           | 原价          | 优惠后 |
| ------------- | --------------- | ----------- | --- |
| SenseAudio-A1 | `senseaudio-a1` | 0.017 元 / 秒 | —   |

相关指南：[音频生成介绍](/guides/audio/overview)。

## 视频生成

> 计费单位：**元 / 秒**，按生成视频时长计费，不同分辨率分级定价。

| 模型名称                | 模型 ID                        | 分辨率   | 原价        | 优惠后           |
| ------------------- | ---------------------------- | ----- | --------- | ------------- |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 480P  | 1 元 / 秒   | **0.5 元 / 秒** |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 720P  | 2 元 / 秒   | **1 元 / 秒**   |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 1080P | 6.2 元 / 秒 | **3.1 元 / 秒** |

相关接口：[创建视频任务](/api-reference/endpoint/video/create)。

## 图片生成

> 计费单位：**元 / 张**

| 模型名称                     | 模型 ID                         | 原价        | 优惠后            |
| ------------------------ | ----------------------------- | --------- | -------------- |
| SenseAudio-Image-2.0     | `senseaudio-image-2.0-260319` | 1 元 / 张   | **0.5 元 / 张**  |
| SenseAudio-Image-1.0     | `senseaudio-image-1.0-260319` | 0.2 元 / 张 | —              |
| Doubao-Seedream-5.0-Lite | `doubao-seedream-5-0-260128`  | 0.5 元 / 张 | **0.22 元 / 张** |
| SenseNova-U1-Fast        | `sensenova-u1-fast`           | 0.5 元 / 张 | —              |

相关接口：[异步图片生成](/api-reference/endpoint/image/async)、[同步图片生成](/api-reference/endpoint/image/sync)。

## 端到端语音模型

> 计费单位：**元 / 分钟**，按实时语音会话中的音频时长计费。

| 模型名称                    | 模型 ID                     | 原价         | 优惠后 |
| ----------------------- | ------------------------- | ---------- | --- |
| SenseAudio-Realtime-1.0 | `senseaudio-realtime-1.0` | 0.6 元 / 分钟 | —   |

相关接口：[端到端实时语音模型](/api-reference/endpoint/tts/end-to-end-wss)。

## 相关资源

<CardGroup>
  <Card title="快速接入" icon="rocket" href="/guides/account/quick-access">
    获取 API Key 并完成首个请求。
  </Card>

  <Card title="API 计费" icon="credit-card" href="/guides/account/billing">
    查看各项能力的计费规则。
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference/introduction">
    浏览全部 API 端点与参数说明。
  </Card>

  <Card title="音色列表" icon="user-music" href="/guides/voice/catalog">
    查看系统音色清单与权限规则。
  </Card>
</CardGroup>


# 模型列表与计费说明
Source: https://docs.senseaudio.cn/guides/account/model-list-billing

本文档汇总平台当前提供的全部模型，包含**模型名称**、**模型 ID**（API 调用参数）、**计费价格**及**能力规格**。

## 一、文本生成模型

<Info>
  价格单位：**元 / 百万 Tokens**（表中数字为元数）
</Info>

### 1.1 SenseAudio 系列

| **模型名称**                 | **模型 ID**                       | **输入价格**                  | **输出价格**                   | **上下文长度** | **最大输入** | **最大输出** |
| ------------------------ | ------------------------------- | ------------------------- | -------------------------- | --------- | -------- | -------- |
| SenseAudio-S2            | `senseaudio-s2`                 | 原价：15<br />**优惠后：** **5** | 原价：90<br />**优惠后：** **30** | 1M        | —        | 128K     |
| SenseAudio-S2-Flash      | `senseaudio-s2-flash`           | 原价：4<br />**优惠后：** **2**  | 原价：24<br />**优惠后：** **12** | 256K      | 254K     | 64K      |
| SenseAudio-S2-Lite       | `senseaudio-s2-lite`            | 原价：2<br />**优惠后：** **1**  | 原价：12<br />**优惠后：** **6**  | 256K      | 254K     | 64K      |
| SenseAudio-S1            | `senseaudio-s1`                 | 原价：15<br />**优惠后：** **5** | 原价：90<br />**优惠后：** **30** | 1M        | —        | 128K     |
| SenseAudio-VL-1.0        | `senseaudio-vl-1.0-260319`      | 原价：15<br />**优惠后：** **5** | 原价：90<br />**优惠后：** **30** | 1M        | —        | 128K     |
| SenseAudio-VL-Lite-1.0   | `senseaudio-vl-lite-1.0-260319` | 原价：2<br />**优惠后：** **1**  | 原价：12<br />**优惠后：** **6**  | 256K      | 254K     | 64K      |
| SenseNova-6.8-Flash-Lite | `sensenova-6.8-flash-lite`      | 原价 15<br />优惠后 **5**      | 原价 90<br />优惠后 **30**      | —         | —        | —        |

### 1.2 其他厂商模型

| **模型名称**                               | **模型 ID**                    | **输入价格**                     | **输出价格**                      | **上下文长度** | **最大输入** | **最大输出** |
| -------------------------------------- | ---------------------------- | ---------------------------- | ----------------------------- | --------- | -------- | -------- |
| Qwen3.8-27B                            | `qwen3.8-27b`                | 3                            | 12                            | 1M        | 992k     | 131K     |
| Qwen3.6-35B-A3B                        | `qwen3.6-35b-a3b`            | 1.8                          | 10.8                          | 256K      | 254K     | 64K      |
| DeepSeek-V4-Flash-0731                 | `deepseek-v4-flash-0731`     | 3                            | 9                             | 1M        | 616k     | 384K     |
| Kimi K2.6                              | `kimi-k2.6`                  | 6.5                          | 27                            | 256K      | —        | 256k     |
| GLM-5.3-Flash                          | `glm-5.3-flash`              | 0.8                          | 2.8                           | 1M        | —        | 128K     |
| GLM-5.2（输入 \< 32K）                     | `glm-5.2`                    | 6                            | 24                            | 1M        | —        | —        |
| GLM-5.2（输入 ≥ 32K）                      | `glm-5.2`                    | 8                            | 28                            | 1M        | —        | —        |
| MiniMax-M2.7                           | `minimax-m2.7`               | 原价：4.2<br />**优惠后：** **2.1** | 原价：16.8<br />**优惠后：** **8.4** | 200K      | —        | 128k     |
| Doubao-Seed-2.0-Pro（输入 ≤ 32K）          | `doubao-seed-2-0-pro-260215` | 3.2                          | 16                            | 256K      | 256K     | 128K     |
| Doubao-Seed-2.0-Pro（32K \< 输入 ≤ 128K）  | `doubao-seed-2-0-pro-260215` | 4.8                          | 24                            | 256K      | 256K     | 128K     |
| Doubao-Seed-2.0-Pro（128K \< 输入 ≤ 256K） | `doubao-seed-2-0-pro-260215` | 9.6                          | 48                            | 256K      | 256K     | 128K     |

## 二、语音合成（TTS）

<Info>
  价格单位：**元 / 万字符** 字符规则：1 个汉字 = 2 个字符；英文字母、希腊字母、标点、特殊符号、空格、回车等 = 1 个字符。
</Info>

| **模型名称**           | **模型 ID**                   | **价格**      | **备注** |
| ------------------ | --------------------------- | ----------- | ------ |
| SenseAudio-TTS-1.5 | `senseaudio-tts-1.5-260319` | 3.5 元 / 万字符 |        |
| SenseNova-TTS-2.0  | `sensenova-tts-2.0`         | 3.5 元 / 万字符 |        |

## 三、语音识别（ASR）

### 3.1 SenseAudio 系列

| **模型名称**                     | **模型 ID**                             | **价格**     | **适用场景**        |
| ---------------------------- | ------------------------------------- | ---------- | --------------- |
| SenseAudio-ASR-Lite-1.5      | `senseaudio-asr-lite-1.5-260319`      | 0.9 元 / 小时 | 通用 / 实时 / 低成本识别 |
| SenseAudio-ASR-1.5           | `senseaudio-asr-1.5-260319`           | 1.8 元 / 小时 | 高质量通用识别         |
| SenseAudio-ASR-Check-1.5     | `senseaudio-asr-check-1.5-260319`     | 3.6 元 / 小时 | 音频质检            |
| SenseAudio-ASR-Pro-1.5       | `senseaudio-asr-pro-1.5-260319`       | 3.6 元 / 小时 | 专业级识别           |
| SenseAudio-ASR-DeepThink-1.5 | `senseaudio-asr-deepthink-1.5-260319` | 3.6 元 / 小时 | 深度推理识别          |

### 3.2 同声传译

同声传译按时长计费（按秒计费，不足 1 秒按 1 秒计时）。

| **模型名称**                    | **模型 ID**                     | **价格**  | **适用场景** |
| --------------------------- | ----------------------------- | ------- | -------- |
| SenseNova-LiveTranslate-1.0 | `sensenova-livetranslate-1.0` | 50 积分/秒 | 同声传译     |

### 3.3 人声分离

人声分离能力属于 **SenseAudio 系列（自研）**，按音频时长计费。

| **模型名称**                   | **模型 ID**                               | **价格**     | **适用场景** |
| -------------------------- | --------------------------------------- | ---------- | -------- |
| SenseAudio-Voice-Isolation | `senseaudio-voice-isolation-1.0-260319` | 0.04 元 / 秒 | 人声分离     |
| SenseAudio-Voice-Isolation | `senseaudio-voice-isolation-1.5`        | 0.04 元 / 秒 | 人声分离     |

## 四、音乐生成

<Info>
  价格单位：**元 / 首**
</Info>

| **模型名称**             | **模型 ID**                     | **原价**  | **优惠后**       |
| -------------------- | ----------------------------- | ------- | ------------- |
| SenseAudio-Music-1.0 | `senseaudio-music-1.0-260319` | 1 元 / 首 | **0.5 元 / 首** |
| SenseAudio-Music-2.0 | `senseaudio-music-2.0-260626` | 1 元 / 首 | **0.5 元 / 首** |

## 五、音效生成

<Info>
  价格单位：**0.08 元 / 组**，创作台默认生成 4 条。
</Info>

| **模型名称**                    | **模型 ID**                   | **原价**     | **优惠后** |
| --------------------------- | --------------------------- | ---------- | ------- |
| SenseAudio-Sound-Effect-1.0 | `senseaudio-sfx-1.0-260626` | 0.08 元 / 组 | —       |

## 六、音频生成

<Info>
  按生成音频时长计费。每生成 1 秒音频消耗 85 积分,约为 0.017 元 / 秒。
</Info>

| **模型名称**      | **模型 ID**       | **原价**      | **优惠后** |
| ------------- | --------------- | ----------- | ------- |
| SenseAudio-A1 | `senseaudio-a1` | 0.017 元 / 秒 | —       |

## 七、视频生成

<Info>
  价格单位：**元 / 秒**，按生成视频时长计费，不同分辨率分级定价。
</Info>

| **模型名称**            | **模型 ID**                    | **分辨率** | **原价**    | **优惠后**       |
| ------------------- | ---------------------------- | ------- | --------- | ------------- |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 480P    | 1 元 / 秒   | **0.5 元 / 秒** |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 720P    | 2 元 / 秒   | **1 元 / 秒**   |
| Doubao-Seedance-2.0 | `doubao-seedance-2-0-260128` | 1080P   | 6.2 元 / 秒 | **3.1 元 / 秒** |

## 八、图片生成

<Info>
  价格单位：**元 / 张**
</Info>

| **模型名称**                 | **模型 ID**                     | **原价**    | **优惠后**        |
| ------------------------ | ----------------------------- | --------- | -------------- |
| SenseAudio-Image-2.0     | `senseaudio-image-2.0-260319` | 1 元 / 张   | **0.5 元 / 张**  |
| SenseAudio-Image-1.0     | `senseaudio-image-1.0-260319` | 0.2 元 / 张 | —              |
| Doubao-Seedream-5.0-Lite | `doubao-seedream-5-0-260128`  | 0.5 元 / 张 | **0.22 元 / 张** |
| SenseNova-U1-Fast        | `sensenova-u1-fast`           | 0.5 元 / 张 | —              |

## 九、端到端语音模型

<Info>
  价格单位：**元 / 分钟**，按实时语音会话中的音频时长计费。
</Info>

| **模型名称**                | **模型 ID**                 | **原价**     | **优惠后** |
| ----------------------- | ------------------------- | ---------- | ------- |
| SenseAudio-Realtime-1.0 | `senseaudio-realtime-1.0` | 0.6 元 / 分钟 | —       |

## 附录：计费说明

### 计费单位汇总

| **模态**    | **计费维度**       | **单位**        |
| --------- | -------------- | ------------- |
| 文本生成      | 输入 / 输出 Tokens | 元 / 百万 Tokens |
| 语音合成（TTS） | 输入字符数          | 元 / 万字符       |
| 语音识别（ASR） | 音频时长           | 元 / 小时        |
| 改写翻译（ASR） | 输出字符数          | 元 / 万字符       |
| 音乐生成      | 生成首数           | 元 / 首         |
| 音频生成      | 生成音频时长         | 积分 / 秒        |
| 视频生成      | 视频时长（按分辨率）     | 元 / 秒         |
| 图片生成      | 生成张数           | 元 / 张         |
| 端到端语音模型   | 音频时长           | 元 / 分钟        |

### 名词说明

* **模型 ID**：API 调用时传入的 `model` 参数值，请严格按照本文档大小写与连字符拼写。
* **上下文长度**：模型在单次请求中可处理的输入 + 输出 Tokens 总和上限。
* **最大输入长度**：单次请求中输入 Tokens 的上限。
* **最大输出长度**：单次请求中模型可生成的输出 Tokens 上限。
* **优惠价**：限时促销价格，活动期内自动按优惠价结算；活动结束后恢复原价。

### 阶梯计费规则

* **GLM-5.2** 与 **Doubao-Seed-2.0-Pro** 按**单次请求的输入 Tokens 长度**适配对应价格档位，输入与输出价格同档计算。
* 阶梯计费以单次请求实际输入长度为准，不跨请求累加。

### 调用示例

```bash theme={null}
curl https://api.senseaudio.cn/v1/chat/completions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "senseaudio-s2",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'
```

<Tip>
  将 `model` 字段替换为本文档中任一**模型 ID**即可调用对应模型。
</Tip>


# 快速接入指南
Source: https://docs.senseaudio.cn/guides/account/quick-access

5 分钟完成首个 SenseAudio 请求

本指南以语音合成能力为例，帮助您在 5 分钟内完成首个 API 调用，并直接得到可播放的 `mp3` 文件。

## 1. 获取密钥 (API Key)

<Steps>
  <Step title="进入 API 密钥">
    进入 [API 密钥](https://senseaudio.cn/api-platform/api-key) 页面。
  </Step>

  <Step title="新增并保存 API Key">
    点击 **"新增 API Key"**，复制并安全保存您的 API Key。
  </Step>
</Steps>

## 2. 发起请求

选择您熟悉的编程语言，复制以下示例即可直接运行。

> 以下示例统一输出 `output.mp3`。其中 `model` 需填写模型名称，`voice_setting.voice_id` 需填写可调用音色 ID。

<Tabs>
  <Tab title="CURL">
    ```bash theme={null}
    curl -X POST https://api.senseaudio.cn/v1/t2a_v2 \
      -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sensenova-tts-2.0",
        "text": "你好，这是来自 SenseAudio 的第一条语音。",
        "voice_setting": {
          "voice_id": "male_0004_a"
        },
        "audio_setting": {
          "format": "mp3",
          "sample_rate": 32000
        }
      }' -o response.json

    jq -r '.data.audio' response.json | xxd -r -p > output.mp3
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    # 1. 配置 API Key 和 URL
    SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY"
    url = "https://api.senseaudio.cn/v1/t2a_v2"

    # 2. 准备请求数据
    payload = {
        "model": "sensenova-tts-2.0",
        "text": "你好，这是来自 SenseAudio 的第一条语音。",
        "voice_setting": {
            "voice_id": "male_0004_a",
            "speed": 1.0,
            "vol": 1.0,
            "pitch": 0
        },
        "audio_setting": {
            "format": "mp3",
            "sample_rate": 32000
        }
    }

    headers = {
        "Authorization": f"Bearer {SENSEAUDIO_API_KEY}",
        "Content-Type": "application/json"
    }

    # 3. 发送请求
    response = requests.post(url, json=payload, headers=headers)
    result = response.json()

    if result.get("data") and result["data"].get("audio"):
        audio_bytes = bytes.fromhex(result["data"]["audio"])
        with open("output.mp3", "wb") as f:
            f.write(audio_bytes)
        print("语音已保存到 output.mp3")
    else:
        print(f"请求失败: {result.get('base_resp', {}).get('status_msg', 'unknown error')}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const axios = require('axios');
    const fs = require('fs');

    const SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY";
    const url = 'https://api.senseaudio.cn/v1/t2a_v2';

    const payload = {
      model: 'sensenova-tts-2.0',
      text: '你好，这是来自 SenseAudio 的第一条语音。',
      voice_setting: {
        voice_id: 'male_0004_a',
        speed: 1.0,
        vol: 1.0,
        pitch: 0
      },
      audio_setting: {
        format: 'mp3',
        sample_rate: 32000
      }
    };

    axios.post(url, payload, {
      headers: {
        'Authorization': `Bearer ${SENSEAUDIO_API_KEY}`,
        'Content-Type': 'application/json'
      }
    })
    .then(response => {
      const result = response.data;

      if (result.data?.audio) {
        const audioBuffer = Buffer.from(result.data.audio, 'hex');
        fs.writeFileSync('output.mp3', audioBuffer);
        console.log('语音已保存到 output.mp3');
      } else {
        console.error('请求失败:', result.base_resp?.status_msg || 'unknown error');
      }
    })
    .catch(error => {
      console.error('请求失败:', error.message);
    });
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "bytes"
        "encoding/hex"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
        "os"
    )

    type TTSRequest struct {
        Model         string        `json:"model"`
        Text          string        `json:"text"`
        VoiceSetting  VoiceSetting  `json:"voice_setting"`
        AudioSetting  AudioSetting  `json:"audio_setting"`
    }

    type VoiceSetting struct {
        VoiceID string  `json:"voice_id"`
        Speed   float64 `json:"speed"`
        Vol     float64 `json:"vol"`
        Pitch   int     `json:"pitch"`
    }

    type AudioSetting struct {
        Format     string `json:"format"`
        SampleRate int    `json:"sample_rate"`
    }

    func main() {
        SENSEAUDIO_API_KEY := "SENSEAUDIO_API_KEY"
        url := "https://api.senseaudio.cn/v1/t2a_v2"

        payload := TTSRequest{
            Model: "sensenova-tts-2.0",
            Text:  "你好，这是来自 SenseAudio 的第一条语音。",
            VoiceSetting: VoiceSetting{
                VoiceID: "male_0004_a",
                Speed:   1.0,
                Vol:     1.0,
                Pitch:   0,
            },
            AudioSetting: AudioSetting{
                Format:     "mp3",
                SampleRate: 32000,
            },
        }

        jsonData, _ := json.Marshal(payload)
        req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer "+SENSEAUDIO_API_KEY)
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            fmt.Println("请求失败:", err)
            return
        }
        defer resp.Body.Close()

        body, _ := io.ReadAll(resp.Body)
        var result map[string]any
        json.Unmarshal(body, &result)

        data, ok := result["data"].(map[string]any)
        if !ok || data["audio"] == nil {
            fmt.Println("请求失败")
            return
        }

        audioHex, _ := data["audio"].(string)
        audioBytes, err := hex.DecodeString(audioHex)
        if err != nil {
            fmt.Println("音频解码失败:", err)
            return
        }

        os.WriteFile("output.mp3", audioBytes, 0644)
        fmt.Println("语音已保存到 output.mp3")
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.io.*;
    import java.net.HttpURLConnection;
    import java.net.URL;
    import org.json.JSONObject;

    public class SenseAudioQuickStart {
        public static void main(String[] args) {
            try {
                String SENSEAUDIO_API_KEY = "SENSEAUDIO_API_KEY";
                String apiUrl = "https://api.senseaudio.cn/v1/t2a_v2";

                // 构建请求体
                JSONObject voiceSetting = new JSONObject();
                voiceSetting.put("voice_id", "male_0004_a");
                voiceSetting.put("speed", 1.0);
                voiceSetting.put("vol", 1.0);
                voiceSetting.put("pitch", 0);

                JSONObject audioSetting = new JSONObject();
                audioSetting.put("format", "mp3");
                audioSetting.put("sample_rate", 32000);

                JSONObject payload = new JSONObject();
                payload.put("model", "sensenova-tts-2.0");
                payload.put("text", "你好，这是来自 SenseAudio 的第一条语音。");
                payload.put("voice_setting", voiceSetting);
                payload.put("audio_setting", audioSetting);

                // 发送请求
                URL url = new URL(apiUrl);
                HttpURLConnection conn = (HttpURLConnection) url.openConnection();
                conn.setRequestMethod("POST");
                conn.setRequestProperty("Authorization", "Bearer " + SENSEAUDIO_API_KEY);
                conn.setRequestProperty("Content-Type", "application/json");
                conn.setDoOutput(true);

                try (OutputStream os = conn.getOutputStream()) {
                    byte[] input = payload.toString().getBytes("utf-8");
                    os.write(input, 0, input.length);
                }

                // 读取响应
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(conn.getInputStream(), "utf-8"))) {
                    StringBuilder response = new StringBuilder();
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }

                    JSONObject result = new JSONObject(response.toString());
                    JSONObject data = result.optJSONObject("data");

                    if (data != null && data.has("audio")) {
                        byte[] audioBytes = hexStringToByteArray(data.getString("audio"));
                        try (FileOutputStream fos = new FileOutputStream("output.mp3")) {
                            fos.write(audioBytes);
                        }
                        System.out.println("语音已保存到 output.mp3");
                    } else {
                        JSONObject baseResp = result.optJSONObject("base_resp");
                        System.out.println("请求失败: " +
                            (baseResp != null ? baseResp.optString("status_msg", "unknown error") : "unknown error"));
                    }
                }
            } catch (Exception e) {
                System.out.println("请求失败: " + e.getMessage());
            }
        }

        private static byte[] hexStringToByteArray(String hex) {
            int len = hex.length();
            byte[] data = new byte[len / 2];
            for (int i = 0; i < len; i += 2) {
                data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
                    + Character.digit(hex.charAt(i + 1), 16));
            }
            return data;
        }
    }
    ```
  </Tab>
</Tabs>

## 3. 命名与取值说明

* **`model`**：填写模型名称，例如 `sensenova-tts-2.0`，可在 **[模型列表](/guides/account/model-list)** 中查询。
* **`voice_setting.voice_id`**：填写可调用音色 ID，可在 **[音色列表](/guides/voice/catalog)** 中获取。
* **`output.mp3`**：示例中的输出文件名，可按业务需要自行修改。

## 相关资源

<CardGroup>
  <Card title="TTS API" icon="waveform-lines" href="/api-reference/endpoint/tts/synthesize">
    语音合成同步合成接口参数详解。
  </Card>

  <Card title="SSE 流式合成" icon="zap" href="/api-reference/endpoint/tts/synthesize-stream">
    Server-Sent Events 协议流式语音合成接口。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看全部可调用模型与计费概览。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    了解各项能力的积分消耗规则。
  </Card>
</CardGroup>


# Token Plan 套餐
Source: https://docs.senseaudio.cn/guides/account/token-plan

Token Plan 各套餐的价格、额度、权益及用量规则，帮助用户选择合适套餐。

## 套餐简介

Token Plan 是面向 AI 开发者、Agent 构建者与多模态创作者的统一订阅服务，助力高效调用各类旗舰模型。具备如下优势：

* **支持主流旗舰模型**：集合 SenseAudio-S2、SenseNova-6.8-Flash-Lite、Qwen3.8-27B、GLM-5.2、GLM-5.3-Flash、MiniMax-M2.7、Kimi-K2.6、Doubao 以及十余款前沿模型，覆盖文本、语音、图像、音乐、视频等多模态场景。
* **一份额度跨模型通用**：同一份 Token 余额可在不同模型、不同任务、不同模态间灵活使用，按任务、成本与延迟自由路由。
* **支持复杂 Agent Harness**：面向生产级 Agent 构建，支持多小时工具调用循环、持久化记忆与高并发推理吞吐。
* **统一接入多家模型能力**：对齐不同厂商的 SDK、tool calls、vision/audio、MCP 等接口细节，降低多供应商接入与迁移成本。
* **覆盖完整多模态生产链路**：支持语音理解、自然语音生成、图像创作、音乐生成、视频生产与文本推理，适配创作、开发与生产级 AI 应用场景。

## 套餐说明

SenseAudio 针对不同规模的开发者与企业用户提供分级 Token 套餐。您可以从以下维度快速对比不同档位：

* **月费与月积分**：帮助您评估预算和月度可用额度
* **周期额度**：帮助您评估每 5 小时、每周和每月的可用额度
* **并发请求与模型范围**：帮助您评估接入规模和可调用模型
* **各模态最大并发数**：帮助您评估语音、图片、视频和实时对话的吞吐能力

SenseAudio-S2、SenseAudio-S1、GLM-5.3-Flash、GLM-5.2、Qwen3.8-27B、同时支持 OpenAI、Anthropic 协议。

## 套餐权益与用量说明

下表按当前会员套餐体系展示。功能配额与价格按当前提供的套餐矩阵整理；如需更高额度、SLA 或专属资源，请联系商务团队。

#### 套餐汇总

单项能力的并发限制同时适用于创作台与 API。若接口返回对应权益值，则以接口返回值为准；未返回时，则按 Token 套餐预设档位执行。

| 限制项                 | Lite 版 | Plus 版      | Pro 版       | Max 版       | Ultra 版     |
| ------------------- | ------ | ----------- | ----------- | ----------- | ----------- |
| **月费**              | ¥36    | ¥99         | ¥199        | ¥699        | ¥1899       |
| **套餐积分**            | 10w 积分 | 35w 积分      | 224w 积分     | 1,120w 积分   | 4,480w 积分   |
| **5 小时积分**          | 100000 | 350000      | 64000       | 320000      | 1280000     |
| **每周全部模型积分**        | 100000 | 350000      | 448000      | 2240000     | 8960000     |
| **音色广场可用音色**        | 基础/vip | 基础/vip/svip | 基础/vip/svip | 基础/vip/svip | 基础/vip/svip |
| **文本转语音最大并发数**      | 2      | 5           | 5           | 10          | 10          |
| **人声提取最大并发数**       | 2      | 2           | 2           | 2           | 2           |
| **语音识别最大并发数**       | 2      | 5           | 5           | 10          | 10          |
| **文生音色最大并发数**       | 5      | 5           | 5           | 10          | 10          |
| **克隆音色最大并发数**       | 2      | 5           | 5           | 10          | 10          |
| **音色次数数量（文生、克隆音色）** | 6      | 10          | 16          | 30          | 50          |
| **自定义 Agent 最大并发数** | 2      | 2           | 3           | 3           | 3           |
| **多模态理解模型最大并发数**    | 2      | 5           | 10          | 10          | 10          |
| **视频生成最大并发数**       | 1      | 2           | 3           | 3           | 3           |
| ・每日次数上限             | 2      | 2           | 5           | 5           | 5           |
| ・每月次数上限             | 10     | 10          | 10          | 50          | 50          |
| **音乐生成最大并发数**       | 1      | 2           | 3           | 3           | 3           |
| ・每日次数上限             | 50     | 100         | 300         | 300         | 300         |
| ・每月次数上限             | 500    | 1000        | 3000        | 3000        | 3000        |
| **音效生成最大并发数**       | 3      | 6           | 9           | 9           | 9           |
| ・每日次数上限             | 150    | 300         | 900         | 900         | 900         |
| ・每月次数上限             | 1500   | 3000        | 9000        | 9000        | 9000        |
| **图片生成最大并发数**       | 1      | 2           | 3           | 3           | 3           |
| ・每日次数上限             | 50     | 100         | 300         | 300         | 300         |
| ・每月次数上限             | 500    | 1000        | 3000        | 3000        | 3000        |

说明：上表按官网「套餐限制总表」口径展示当前主要功能配额，不包含 Free 版。更高规格、定制资源与企业方案以工作台或商务方案为准。

### 套餐额度刷新规则

套餐额度在时间周期内耗尽后，需要等待下一个周期自动恢复额度，不会消耗其他资源包或账户余额。

* **每 5 小时限额**：根据首次请求发生时间，以 5 小时为周期定时刷新限额。
* **周限额**：每周一 00:00:00 重置周限额。
* **月限额**：每订阅月第 1 日 00:00:00 重置月限额。

### 套餐与音色权限

不同套餐可调用的系统音色等级不同，详见 [音色列表](/guides/voice/catalog)。

### 购买与升级

<Steps>
  <Step title="登录控制台">
    进入 SenseAudio 控制台的「会员订阅」页面。
  </Step>

  <Step title="选择套餐">
    根据业务规模与 Token 消耗预估选择合适的套餐等级。
  </Step>

  <Step title="完成支付">
    支持的支付方式：**支付宝**、**微信**。
  </Step>

  <Step title="套餐生效">
    支付成功后套餐立即生效，Token 额度与音色生成次数同步到账。
  </Step>
</Steps>

### 额度超出与续费

* **超额策略**：套餐额度用尽后将暂停调用。如已开启余额自动支付，超出部分将按量计费；如未开启或不支持余额支付，则自动降级至 Free 版。
* **到期策略**：套餐到期后将自动降级至 Free 版。克隆音色与文生音色的生成次数额度也将同步调整为 Free 版数量，请在到期前确认剩余额度与使用安排。

## 企业方案与定制

如需更高 QPS、更大 Token 额度、定制 SLA 或私有化部署，请联系商务团队：

* 邮件：[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)

## 相关资源

<CardGroup>
  <Card title="API 计费" icon="credit-card" href="/guides/account/billing">
    查看各项 API 的积分消耗规则。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    浏览全部可调用模型及其计费。
  </Card>

  <Card title="音色列表" icon="user-music" href="/guides/voice/catalog">
    查看系统音色清单与权限规则。
  </Card>

  <Card title="快速接入" icon="rocket" href="/guides/account/quick-access">
    获取 API Key 并完成首个请求。
  </Card>
</CardGroup>


# 端到端实时语音介绍
Source: https://docs.senseaudio.cn/guides/agent/overview



## 什么是端到端实时语音？

端到端实时语音通过一个 WebSocket 连接完成语音输入、语义理解、模型回复和语音输出的完整链路。开发者只需要按协议发送 `pcm_s16le` 音频帧，并处理服务端返回的 JSON 事件与二进制音频帧，即可实现自然的实时语音对话体验。

## 主要特性

* **实时语音交互**：支持客户端持续上传语音，服务端实时返回转写、文本与音频回复。
* **低延迟流式链路**：文本帧以 JSON 事件返回，音频帧以 PCM 二进制数据返回，便于边接收边处理。
* **多轮对话**：单个 WebSocket 连接内可连续完成多轮用户输入与模型回复。
* **回复打断**：客户端可发送 `cancel` 打断当前模型回复，适合语音助手和实时对话场景。
* **动态配置**：支持通过 `update` 在会话中更新音色或系统提示词等配置。
* **函数调用**：支持通过 `tools` 注册 Function Tool Schema，并通过 `tool.call` / `tool.result` 完成本地工具调用。

## 应用场景

### 语音助手

面向 App、桌面端或硬件设备，构建可持续对话的语音助手，实现问答、指令执行、信息查询等能力。

### 智能客服

用于售前咨询、售后答疑、业务办理和人工转接前置分流，通过语音交互降低用户输入成本。

### 教育陪伴

支持口语练习、知识问答、课程陪练等实时互动场景，结合模型回复和语音输出形成自然对话体验。

### 车载与 IoT 交互

适合车载系统、智能音箱、机器人等需要实时语音控制和多轮反馈的终端设备。

## 模型版本

| 模型名称      | 模型 ID                     | 说明                                                     |
| :-------- | :------------------------ | :----------------------------------------------------- |
| 端到端实时语音模型 | `senseaudio-realtime-1.0` | 基于 WebSocket 的实时语音对话模型，支持语音输入、用户转写、模型文本回复、模型语音回复与函数调用。 |

当前模型版本为 `senseaudio-realtime-1.0`。该模型支持实时语音转写、模型文本增量回复、模型语音回复、对话配置更新、打断以及函数调用等能力。

通过 `tools` 接入天气查询、订单查询、知识库检索、转人工等本地业务能力，让模型在对话中触发外部工具。

## API 能力概览

端到端实时语音 API 使用 WebSocket 协议接入，核心能力包括：

* **建立连接**：连接 `wss://api.senseaudio.cn/ws/v1/realtime/voice-dialog`，通过 `Authorization: Bearer SENSEAUDIO_API_KEY` 鉴权。
* **开始对话**：发送 `start` 初始化会话，指定 `model: senseaudio-realtime-1.0`、音色、系统提示词和输入音频设置。
* **上传音频**：按 `pcm_s16le`、`16000Hz`、单声道发送二进制音频帧，推荐每 `40ms` 发送一帧。
* **提交音频**：发送 `commit` 手动提交当前一轮音频输入。
* **打断回复**：发送 `cancel` 取消当前模型回复。
* **更新配置**：发送 `update` 更新音色或系统提示词。
* **函数调用**：通过 `tools` 注册工具，收到 `tool.call` 后执行本地逻辑，并用 `tool.result` 回传结果。
* **结束会话**：发送 `end` 主动结束当前 WebSocket 会话。

服务端会返回 `ready`、`speech.started`、`user.transcript.delta`、`user.transcript.done`、`assistant.text.delta`、`assistant.text.done`、`assistant.audio.start`、`assistant.audio.done`、`turn.done`、`tool.call`、`tool.cancelled`、`command.ack`、`error` 等事件。

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 页面创建您的 API Key，并在请求头中使用 `Authorization: Bearer SENSEAUDIO_API_KEY` 鉴权。
  </Step>

  <Step title="建立 WebSocket 连接">
    使用服务端程序连接 `wss://api.senseaudio.cn/ws/v1/realtime/voice-dialog`。浏览器原生 WebSocket 不能设置自定义 `Authorization` 请求头，浏览器场景建议通过受控后端代理接入。
  </Step>

  <Step title="发送 start 消息">
    连接建立后，第一条客户端文本消息必须是 `start`，并指定 `model` 为 `senseaudio-realtime-1.0`。
  </Step>

  <Step title="等待 ready 后发送音频">
    收到服务端 `ready` 后，按 `pcm_s16le`、`16000Hz`、单声道持续发送音频二进制帧。
  </Step>

  <Step title="处理服务端事件">
    监听用户转写、模型文本回复、模型音频帧和工具调用事件，根据业务需要播放音频、展示文本或执行本地工具。
  </Step>

  <Step title="结束会话">
    用户结束对话时发送 `end`，服务端会正常关闭 WebSocket 连接。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="端到端实时语音模型" icon="waveform-lines" href="/api-reference/endpoint/tts/end-to-end-wss">
    查看 WebSocket 接口、事件协议、参数说明和 Python 调用示例。
  </Card>

  <Card title="计费" icon="credit-card" href="/guides/account/billing">
    查看端到端实时语音模型及其他能力的计费规则。
  </Card>

  <Card title="自定义智能体" icon="robot" href="/api-reference/endpoint/custom-agent/create">
    创建和管理可绑定模型、音色与配置的自定义智能体。
  </Card>

  <Card title="模型列表与计费说明" icon="list" href="/guides/account/model-list-billing">
    查看模型 ID、价格和计费单位说明。
  </Card>
</CardGroup>

## 技术支持

如需技术支持或商务咨询，请发送邮件至 [senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)。

也可以先查看 [端到端实时语音模型 API 参考](/api-reference/endpoint/tts/end-to-end-wss)，确认接入地址、鉴权方式、音频格式、事件类型和完整调用示例。


# 音色克隆协议
Source: https://docs.senseaudio.cn/guides/agreement/clone

SenseAudio 音色克隆用户协议

**更新日期：2026 年 1 月 8 日**

**生效日期：2026 年 1 月 8 日**

您（指使用语音服务的用户，下称"您"）知悉且同意向上海禹幻科技有限公司及其关联方（以下简称"禹幻科技"或
"我们"）会通过您的终端设备收集、传输、使用、加工、存储您的声音数据和授权您使用其声音数据的人士的声音，以及您的麦克风权限，从而实现本服务的功能。

您应对使用本服务使用的声音数据的来源及内容负责，并确保数据来源及内容的合法性。您应保证您有权使用本服务对该等数据进行处理，且前述处理活动均符合相关法律法规的要求，不存在任何违法违规、侵权或违反与第三方合同约定的情形，亦不会将数据用于违法违规目的，因您的数据内容及您的数据处理行为违反法律法规、部门规章或国家政策而造成的全部结果及责任均由您自行承担。如您使用了数据中包含了个人信息的，您应保证已经获得了个人信息主体的同意，并有权将其个人信息传输给我们基于本协议之目的进行数据处理。

如您不同意授权，请不要点击"下一步"，同时您将无法继续使用与声音数据处理相关联的功能。通常情况下不会影响您使用我们的其他功能。

请您知悉，我们将在实现上述目的所需的期限内以及法律规定的留存期限内保留您的个人信息。关于声音及其他个人信息的具体收集、使用、保存规则以及您的权利，请参见[《SenseAudio隐私政策》](/guides/agreement/policy)。为保护您的合法权益，请您充分阅读并理解[《SenseAudio服务协议》](/guides/agreement/user)和[《SenseAudio隐私政策》](/guides/agreement/policy)。

您自愿勾选同意本授权书即视为您同意并确认本授权书的所有内容，本授权书自您同意之日起正式生效。


# 隐私政策
Source: https://docs.senseaudio.cn/guides/agreement/policy

SenseAudio 隐私政策

**更新日期：2025 年 12 月 11 日**

**生效日期：2025 年 12 月 11 日**

**欢迎您使用 SenseAudio 产品和服务！**

**SenseAudio 网页服务（以下简称"本服务"）是由上海禹幻科技有限公司（以下简称"禹幻科技"或"我们"）开发及运营的人工智能内容生成及与之相关的其他服务。**

**为方便用户（或称"您"）注册和使用本产品的服务，我们可能会收集和使用您的相关个人信息。我们深知个人信息对您的重要性，并会尽全力保护您的个人信息和隐私安全。**

**我们将通过《SenseAudio 隐私政策》（"本隐私政策"或"本政策"）向您告知我们的个人信息处理规则，并按照本政策收集和使用您的相关数据和信息。其中与您的权益可能存在重大关系的内容，我们将通过加粗方式予以标识，请您重点阅读。如果您对本政策有疑问的，请通过本政策列明的方式询问，我们将解释本政策内容。您点击确认本政策、使用或在我们更新本政策后继续使用本产品的服务，即意味着您已经同意本政策，同意我们按照本政策收集和使用您的相关数据和信息。**

**本隐私政策将帮助您了解以下内容：**

**一、本政策适用范围**

**二、我们如何收集和使用您的个人信息**

**三、征得授权同意的例外**

**四、对 Cookie 和同类技术的使用**

**五、我们如何存储您的个人信息**

**六、我们如何共享、转让、公开披露您的个人信息**

**七、我们如何保护您的个人信息**

**八、您的权利**

**九、我们如何处理未成年人的个人信息**

**十、本政策的变更和修订**

**十一、如何联系我们**

**十二、本政策的生效**

## 一、本政策适用范围

本政策适用于我们通过 SenseAudio 向您提供的服务。

需要特别说明的是，本政策不适用于其他第三方向您提供的服务，例如您通过 SenseAudio 链接到的第三方服务或网站。您理解这些服务由第三方独立向您提供，第三方将依照其政策或用户协议单独对您的个人信息处理承担责任。

## 二、我们如何收集和使用您的个人信息

我们会基于以下目的和用途、按照以下方式收集和使用您的个人信息：

### 2.1 账号注册、登录

当您注册、登录本产品时，需要提供真实、准确、完整、有效的注册信息和资料，以便创建账号。您可以通过手机号码创建账号，我们会使用您的手机号码向您发送验证码。手机号码是履行国家法律法规关于网络实名制要求的必要信息，您应当使用您本人的手机号码进行注册。如果您不提供手机号码用于注册、登录，或者您不创建账号，我们可能无法为您提供本产品的全部功能和服务。

注册、登录完成后，您可以设置和完善账号信息（头像、昵称、绑定第三方账号）。**您知悉并同意，您的头像、昵称将可能被用于在本产品公开展示。**

### 2.2 实名认证

当您使用 SenseAudio 部分功能时，需要您进行实名认证，核验您的身份。

若您选择个人实名服务，您需要进行人脸识别验证，我们需要收集您的姓名、身份证号、实名认证结果。

若您选择企业实名认证服务，可以根据您的自身需求选择"法人扫脸认证"和"对公账户打款认证"任何一种方式。

* 如您选择"对公账户打款认证"，我们需要收集您的企业名称、统一社会信用代码、法定代表人姓名、法定代表人身份证号、联系方式、企业对公账户银行卡号、开户行、开户支行、实名认证结果。
* 如您选择"法人扫脸认证"，您需要进行人脸识别验证，我们需要收集您的企业名称、统一社会信用代码、法定代表人姓名、法定代表人身份证号、实名认证结果。

在实名认证过程中，可能需要由提供认证服务的第三方服务机构核验您的真实身份信息。这些信息仅供完成实名认证目的，或其他法律法规要求的目的，未经您明示同意不会用做其他用途。您可以拒绝提供，但将无法使用必须实名认证才可以使用的功能和服务。通常情况下不会影响您使用我们的其他功能。

### 2.3 支付服务

2.3.1 您可以订购本产品的付费服务。您订购付费服务的过程中可能需要进行支付，在支付过程中，我们可能会收集您的第三方支付账号信息（支付宝账号或微信账号，以您实际使用的支付方式为准）、订单支付信息。

2.3.2 您可以就已完成订购的付费服务向我们申请开具发票。根据您申请的发票类型的不同，我们将收集和使用如下信息中的一项或多项：邮箱地址、发票抬头（个人姓名或单位名称）、单位税号、单位地址及电话、开户行名称及账号、专票证明、委托关系证明。如果您拒绝提供上述信息或者提供的信息有误的，我们将无法为您开具发票，您可以更正、补充或重新提交正确、必要的信息。

### 2.4 内容生成

2.4.1 我们基于 AI 技术，向您提供 AI 模型内容生成（包括音频、视频、语音识别、语音合成、人声分离等内容生成）服务。为了向您提供服务，我们会收集您主动上传的图片、视频、音频，以及您输入的文字、音频、配置参数等指令（"生成指令"，与"对话指令"统称"输入内容"）。我们会对上述信息进行分析，以便于为您生成符合您指令和要求的内容（"生成内容"，与"对话结果"统称"输出内容"）。您主动拍摄图片、视频，或输入语音，或上传文件时，为实现功能的需要，我们会根据您输入信息的类型和输入方式分别请求您授权相机、存储（相册、媒体和其他文件）、麦克风权限。如您拒绝授权，将无法拍摄图片、视频，无法输入语音或无法上传文件，但这不影响您使用 SenseAudio 的其他功能。

**特别地，在您使用内容生成功能的过程中：**

**（1）我们十分建议并请求您在使用我们的服务过程中，不要输入能够识别您或其他人身份的个人信息，因为这类个人信息不是我们必须收集的信息。**

**（2）如您的输入内容包含他人的个人信息的，请您务必在提供该等信息前获得他人的合法授权，避免造成对他人信息的不当使用或泄露。**

**（3）当您使用内容生成服务对声音类素材进行处理、制作时，我们可能会对您输入内容中的声音的特征点进行分析，以协助您使用服务，但我们不会将该等信息用于识别特定自然人。**

**（4）用户不得利用基于深度学习、虚拟现实、生成式人工智能等新技术新应用制作、上传、复制、传送、传播虚假新闻信息等法律法规禁止的信息内容，或将合成内容谎称为自然内容。您在发布或传播利用基于深度学习、虚拟现实、生成式人工智能等新技术新应用制作的非真实信息时，应当以显著方式予以标识，否则我们有权对相关内容和账户采取包括但不限于增加标识、限制、封禁等措施。**

### 2.5 用户反馈与服务

当您向我们进行咨询、申诉或提起投诉时，为了方便与您联系或帮助您解决问题，我们可能需要您提供手机号码或邮箱信息。如您拒绝提供上述信息，我们可能无法向您及时反馈相关处理结果。

### 2.6 保障服务安全

**为保障您使用我们的软件时系统的稳定性和安全性，防止您的个人信息被非法获取，更准确地预防欺诈和保护账号安全，我们需要收集您的设备信息（包括设备名称、设备品牌、设备型号及规格、设备厂商、MAC 地址、设备标识（IMEI/MEID/AndroidID/OpenUDID/IMSI/IDFA/OAID 及其他综合设备参数形成的设备标识符）、设备 MD5 值（基于设备 MAC 地址加密的 MD5 值）、传感器列表、设备启动时间、设备初始化时间，操作系统版本、操作系统设置的国家、语言、时区、分辨率、系统更新时间及其识别符，服务提供商网络 ID、网络位置信息（通过 IP 地址、运营商信息、基站信息、附近的 WIFI、连接的 WIFI 获取的大致地理位置信息，且仅收集至国家/省/市）、浏览器版本、登录信息（手机号码、短信验证码、第三方账号登陆同步的用户名、头像、邮箱等）来判断您的账号风险，并可能会记录一些我们认为有风险的链接（"URL"）；我们也会收集您的设备信息用于对我们的系统问题进行分析、统计流量并排查可能存在的风险，在您选择向我们发送异常信息时予以排查。** 如果您不提供上述信息，我们则无法在您使用我们的服务过程中对您的服务及账号安全进行保护。

### 2.7 改善服务

2.7.1 我们会收集您在使用本产品过程中的行为信息，包括您的点击、浏览、反馈、上传、下载、搜索、等操作行为信息，用以向您提供服务，以及改进我们的服务质量。

**2.7.2 在经安全加密技术处理、去标识化且无法重新识别特定个人的前提下，我们可能会将输入内容、输出内容、行为信息进行分析和用于模型训练，以不断调整优化模型效果和产品体验。**

2.7.3 我们可能会将去标识化处理后的信息单独或结合起来使用，进行数据分析以统计用户数量和来源、分析本产品的使用状况、发现并解决本产品故障、开展内部审计、数据分析和研究及第三方 SDK 统计服务，以不断改进本产品、为您提供更优质的服务。

### 2.8 消息通知

您知悉并同意，我们在运营中可能会通过您的终端设备向您发送与本产品或您所使用的服务有关的消息通知，您可以通过在终端设备中对"通知"权限进行设置来选择是否接受通知。我们也可能会通过您提供的手机号码，以短信、电话的方式向您发送通知，以及您可能感兴趣的服务、功能或活动等商业性信息；如您不愿接受这些信息，您可以通过短信中提供的退订方式进行退订，也可以通过本政策列明的联系方式与我们联系进行退订。

### 2.9 设备权限调用

我们目前仅通过网页提供服务，会使用浏览器的录音权限、IP 地址信息，不会直接调用您的手机设备权限。

### 2.10 第三方服务

为了实现特定的软件功能，更好的为您提供服务，我们在软件中接入第三方软件工具开发包（SDK）、应用程序接口（API），请您点击此处查看我们产品中接入的第三方目录[《接入第三方信息SDK列表》](/guides/agreement/tripartite-sdk)以了解可能获得您信息的第三方、相关服务提供方身份、其通过我们收集或获取的您的信息的范围以及使用目的。

我们会不时对该等合作伙伴或服务提供商进行技术检测和行为审计，并要求其遵循合作法律协议，以最大限度地确保其依法、依规、依约收集和使用数据。请您注意，尽管我们会通过合同和技术手段要求该等第三方严格保护您的个人信息，但该等第三方将依据其个人信息保护政策对您的个人信息独立承担保护责任。

## 三、征得授权同意的例外

**根据相关法律法规的规定，在以下情形中收集和使用您的个人信息无需征得您的授权同意：**

**1. 与我们履行法律法规规定的义务相关的；**

**2. 与国家安全、国防安全有关的；**

**3. 与公共安全、公共卫生、重大公共利益有关的；**

**4. 与犯罪侦查、起诉、审判和判决执行等有关的；**

**5. 出于维护个人信息主体或其他个人的生命、财产等重大合法权益但又很难得到您本人同意的；**

**6. 所收集的个人信息是您自行向社会公众公开的；**

**7. 从合法公开披露的信息中收集个人信息的，如合法的新闻报道、政府信息公开等渠道；**

**8. 用于维护所提供的产品或服务的安全稳定运行所必需的，例如发现、处置产品或服务的故障；**

**9. 学术研究机构基于公共利益开展统计或学术研究所必要，且对外提供学术研究或描述的结果时，对结果中所包含的个人信息进行去标识化处理的；**

**10. 法律、法规或国家标准规定的其他情形。**

**特别提示您，如信息经过处理后无法单独或结合其他信息识别特定自然人的，其不属于法律意义上的个人信息，根据法律规定，对其进行使用、处理、共享、转移、公开披露的，无需另行通知您或征得您的同意。**

## 四、对 Cookie 和同类技术的使用

Cookie 和设备信息标识等同类技术是互联网中的普遍使用的技术，是我们让浏览器存储在您设备（例如计算机或智能手机）上的一小段数据（文本文件），记录下有关您的登录状态信息或您的设备信息，以便您再次访问时无需重新登录。

与通用术语"cookies"有关的"类似技术"还包括本地对象（有时称为 flash cookies）、网页信标、像素标签、浏览器指纹技术或任何在用户设备上存储或访问信息的技术。这些信息通常不能让我们识别您的身份，但是可以在您访问网站（包括我们的网站）时提供更好的用户体验。

我们出于不同的目的在网站上使用各种 Cookie，包括：严格必要型 Cookie 和功能 Cookie。

如果您接受 Cookie，我们可能会使用 Cookie 和同类技术，以收集、标识和存储你访问、使用本产品时的信息。

您可以通过浏览器设置接受、拒绝或管理 Cookie。如果您拒绝 Cookie，您有可能无法享受最佳的服务体验，某些功能的可用性可能会受到影响。

## 五、我们如何存储您的个人信息

我们在中华人民共和国境内收集和产生的个人信息将存储在中华人民共和国境内。

我们只会在达成本政策所述目的所需的期限内保留您的个人信息，除非法律有强制的留存要求。我们判断个人信息的存储期限主要参考以下标准并以其中较长者为准：

1. 完成您同意使用的业务功能，包括售后服务；
2. 您同意的留存期间；
3. 是否存在有关保留期限的其他特别约定。

在超出保留期间后，我们会根据适用法律的要求删除您的个人信息，或对其进行匿名化处理。

如我们停止运营 SenseAudio 相关服务，我们将及时停止继续收集您个人信息的活动，并将以公告的形式进行停止运营通知。同时，对我们存储的个人信息进行删除或匿名化处理。

注：匿名化处理指通过对个人信息的技术处理，使得个人信息主体无法被识别或者关联，且处理后的信息不能被复原的过程。根据相关法律法规及国家标准，经匿名化处理的信息不属于个人信息。

## 六、我们如何共享、转让、公开披露您的个人信息

### 6.1 共享

6.1.1 我们不会与任何公司、组织和个人共享您的个人信息，除非存在以下一种或多种情形：

（1）事先获得您的同意或授权；

（2）您自行提出的；

（3）根据适用的法律法规、法律程序的要求或相关监管机关、行政机关、司法机关、或其他有权机关的要求所必须的情况下进行提供；

（4）为向您提供服务，与合作伙伴进行的必要共享。我们的合作伙伴主要包括以下类型：

A. 内容审核服务商：为保证用户在互联网信息平台上发布的内容是安全的，我们可能会向委托的第三方内容审核服务商共享您在本产品中输入、发布的信息内容。

B. 统计分析类合作伙伴：为帮助进行决策建议、提高信息内容有效触达率、进一步了解用户需求，我们可能会与委托我们和/或我们委托其进行统计分析类合作伙伴共享去标识化的设备信息或统计信息，这些信息难以或无法与你的真实身份相关联。

**C. 合作的第三方 SDK 服务商：当您使用本产品时，我们可能会接入由第三方提供的软件开发包（SDK）以实现相关功能，相关具体信息请查看第 2.10 条。（第三方账号登录功能、支付功能、通知功能等）。第三方 SDK 服务商可能会直接收集您的相关信息（以嵌入代码、插件等形式）。请您注意，这些第三方主体拥有不同于我们的隐私政策，请您在使用本产品和/或第三方 SDK 服务前先行查阅其隐私政策。您知悉并同意，我们会尽商业上的合理努力要求该第三方对您的个人信息采取保护措施，但我们无法保证该第三方一定会按照我们的要求采取保护措施，亦不对该第三方的行为及后果承担任何责任。**

（5）当您选择参加我们与我们的关联方或其他合作伙伴举办的营销活动时，可能需要您提供姓名、联系方式等信息。您拒绝提供这些信息可能将无法参加相关活动，但不会影响您使用本产品的其他功能。经过您的同意后，我们才会将这些信息与关联方或合作伙伴共享，以保障您在活动中获得体验一致的服务，或由合作伙伴及时向您兑现奖励。

（6）与我们的关联公司进行必要的共享：我们可能会与我们的关联公司共享您的个人信息。我们只会共享必要的个人信息，且这种共享受本政策所声明的目的的约束。关联公司如要改变个人信息的处理目的，将再次征得您的授权和同意。

（7）相关法律法规规定的其他情形。

### 6.2 转让

我们不会将您的个人信息转让或转移给任何公司、组织和个人，但以下情形除外：

（1）获得您的明确同意后，我们会向其他方转让或转移您的个人信息；

（2）根据适用的法律法规、法律程序的要求、强制性的行政或司法要求所必须的情况进行提供；

（3）符合与您签署的相关协议（包括在线签署的电子协议以及相应的平台规则）或其他的法律文件约定所提供；

（4）在涉及合并、收购或破产清算时，如涉及到个人信息转让或转移，我们将要求继受方按照同等标准继续履行个人信息保护义务，若继受方变更原先的处理目的、处理方式的，我们将要求继受方重新征得您的授权同意。

### 6.3 公开披露

公开披露是指向社会或不特定公众发布信息的行为。我们仅会在以下情形下，公开披露您的个人信息：

（1）获得您明确同意后；

（2）基于法律的披露：在法律、法律程序、诉讼或政府主管部门强制性要求的情况下，我们可能会公开披露您的个人信息。

（3）您主动在本产品公开披露、公开发布信息内容时，您的昵称将会被一同公开展示；

（4）因发布中奖、处罚名单相关的通知、公告而对您的账号信息（例如昵称）进行必要的展示；

（5）相关法律法规规定的其他情形。

## 七、我们如何保护您的个人信息

1. 【上海禹幻科技有限公司】及其关联方设置了专门的个人信息保护负责人，负责处理【上海禹幻科技有限公司】及其关联方相关产品和服务可能涉及到用户个人信息的各项事务，以及规划和制定公司的政策、审核各产品的用户使用协议、监督各产品的工作原理和信息处理机制等。

2. 我们进行了 ISO 27001 信息安全管理体系认证、ISO27701 隐私信息管理体系认证、关键产品的网络安全等级保护的定级测评。我们按照信息安全等级保护的要求制定了信息安全工作的总体方针和安全策略，建立了覆盖主机、数据、应用、管理等层面的安全管理制度，成立了信息安全管理委员会及信息安全执行委员会，设立了系统平台部为产品安全管理工作的职能部门，明确了安全管理机构内的各个部门和岗位的职责、分工和技能要求，制定了明确的人员录用和离职管理规范。

3. 我们会对可识别的个人敏感信息进行加密传输和加密存储，加密强度符合安全要求，以确保数据的保密性。我们的应用系统提供了身份鉴别、用户标识唯一性检查、基于角色的访问控制等功能，采用 HTTPS 安全协议进行通信，设置了最大并发会话连接数，能够对系统服务水平降低到预先规定的最小值进行监测和报警。我们在服务端部署访问控制机制，对可能接触到您个人信息的工作人员采取最小够用授权原则，并定期核查访问人员名单和访问记录。我们的服务器操作系统和数据库系统口令有复杂度要求，采用 SSH 安全协议进行远程管理，严格限制默认账号的访问权限，并修改了默认口令，审计记录全面并覆盖了所有用户。

4. 我们存储用户个人信息的服务器系统均为安全加固后的操作系统。我们会对服务器操作进行账号审计及监控。如果发现外部公告有安全问题的服务器操作系统，我们会在第一时间进行服务器安全升级，确保所有服务器系统及应用安全。

5. 我们为工作人员定期举办个人信息保护相关法律法规培训，以加强工作人员的用户个人隐私保护意识。

6. 我们制定了网络安全事件应急预案，并调配足够的资源保障确保应急预案的执行。我们每年对应急预案进行了培训和应急事件演练。如果我们的物理、技术或管理防护措施不幸遭到破坏，我们会及时启动应急预案，防止安全事件扩大，按照法律法规的要求上报国家主管机关，并及时采取推送、公告等合理、有效的方式向您告知安全事件的基本情况、可能的影响、已经采取的措施或将要采取的措施等。

## 八、您的权利

我们非常重视您的个人信息权利，根据相关法律法规规定，我们保障您对自己的个人信息行使以下权利：

### 8.1 查阅、复制、更正您的账号信息

您有权查阅、复制、修改您的账户信息。您可以通过账号管理查阅、复制、修改您的账号信息。您可以通过本政策列明的邮箱地址联系我们进行个人信息的查阅、复制与修改。

### 8.2 删除您的个人信息

您有权删除您的个人信息。您可以通过账号注销删除您的个人信息，或者通过本政策列明的方式，或者在线客服联系我们。您可以通过本政策列明的邮箱地址联系我们，进行个人信息的删除。

在以下情形中，您可以向我们提出删除个人信息的请求：

（1）如果我们处理个人信息的行为违反法律法规；

（2）如果我们收集、使用您的个人信息，却未征得您的同意；

（3）如果我们处理个人信息的行为违反了与您的约定；

（4）如果您不再使用我们的产品或服务，或您注销了 SenseAudio 语音账号；

（5）如果我们终止服务及运营。

收到您的删除请求后，我们会根据您及相关法律法规的要求进行后续处理并向您反馈结果。我们还将同时通知从我们获得您的个人信息的实体，要求其及时删除，除非法律法规另有规定，或这些实体获得您的独立授权。当您或我们协助您删除相关信息后，因为适用的法律和安全技术，我们可能无法立即从备份系统中删除相应的信息，我们将安全地存储您的个人信息并将其与任何进一步处理隔离，直到备份可以清除或实现匿名化处理。

### 8.3 改变或撤回您的授权

对于设备权限的授权，您可以在终端设备上改变或关闭。对于其他个人信息的授权同意，您可以通过本政策列明的方式联系我们改变您授权的范围或者撤回您的授权。请您充分了解并知悉，部分业务功能需要一些必要的个人信息才能得以完成，改变授权范围或者撤回授权可能影响您继续使用相关功能或服务，但不会影响撤回前基于您的授权同意已进行的个人信息处理活动。

### 8.4 注销账号

您可以通过 SenseAudio 网站的账号管理—注销功能自行操作注销。在您注销账号前，我们可能验证您的个人身份、安全状态、设备信息。您知悉并理解，注销账号是不可逆的行为，当注销账号后，我们将停止为您提供本产品服务，注销提交以后会有 7 天的冷静期，您随时可以撤销注销的操作，7 天冷静期结束后如果没有撤销操作，我们将删除您账号存续期间在本产品的一切数据信息或对其进行匿名化处理。具体信息可在注销环节查阅《SenseAudio 账号注销协议》。

### 8.5 响应您的请求

为了保障安全，我们可能需要您提供书面材料，或以其他方式证明您的身份，我们将在收到您反馈并验证您的身份后的十五个工作日内答复您的请求。

**对于您合理的请求，我们原则上不收取费用，但对多次重复、超出合理限度的请求，我们将视情况收取一定成本费用。**

**对于那些无端重复、需要过多技术手段、给他人合法权益带来风险或者非常不切实际的请求，我们可能会予以拒绝。**

**但是，您知晓并同意在以下情形中，按照法律法规要求，我们可能无法响应您的请求：**

**（1）与国家安全、国防安全有关的；**

**（2）与公共安全、公共卫生、重大公共利益有关的；**

**（3）与犯罪侦查、起诉和审判等有关的；**

**（4）有充分证据表明您存在主观恶意或滥用权利的；**

**（5）响应您的请求将导致您或其他个人、组织的合法权益受到严重损害的。**

## 九、我们如何处理未成年人的个人信息

**我们的产品和服务仅面向成人。不满 18 周岁的未成年人不得使用我们的产品或服务。如果我们发现自己收集了未成年人的个人信息，会设法尽快删除相关数据。**

## 十、本政策的变更和修订

**为给您提供更好的服务以及随着我们业务的发展，我们可能会适时更新和修订本隐私政策，更新后的本政策一经发布即生效。我们会通过 SenseAudio 发布更新版本并通过网站公告或以其他适当方式提醒您相关内容的更新，也请您访问本产品以便及时了解最新的隐私政策。如果您不同意更新后的本政策，您应当停止使用本产品，您继续使用本产品的，即视为您同意更新后的本政策。**

## 十一、如何联系我们

【上海禹幻科技有限公司】为 SenseAudio 的运营主体，注册地址及联系地址为上海市徐汇区虹梅路 1900 号 6 楼 6-54 单元。

如果您对我们的政策及对您个人信息的处理有任何疑问、意见、建议或投诉，请发送邮件至 [senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)，在一般情况下，我们会在 15 个工作日内对您的请求予以答复。

请理解，由于材料审核、业务核对、操作流程等原因，对用户请求的处理完成时间可能会长于上述时限。

如果您对我们的回复不满意，特别是我们的个人信息处理行为损害了用户的合法权益，还可以向我们所在地网信、电信、公安及工商等监管部门进行投诉或举报；或向我们所在地具有管辖权的法院提起诉讼。我们希望用户在向政府或法院投诉或起诉前，可以与我们进行友好协商，欢迎并感谢用户对我们的监督和建议。

## 十二、本政策的生效

本政策版本将于 2025 年 12 月 11 日正式生效。


# 用户协议
Source: https://docs.senseaudio.cn/guides/agreement/user

SenseAudio 用户协议

**发布日期：2026 年 3 月 4 日**

**更新日期：2026 年 3 月 4 日**

欢迎您访问 SenseAudio 网站并使用 SenseAudio 产品或服务（以下简称”本服务”或”SenseAudio”）。  本服务是上海禹幻科技有限公司（以下简称”我们”）运营的一款人工智能语音应用。

本《用户服务协议》（以下称”本协议”）是由我们与 SenseAudio 注册用户（下称”用户”或”您”）签订的具有合同效力的文件，适用于您打开、浏览、使用本服务时的全部活动。

## 【特别提示】

**（一）** 您应当阅读并遵守本协议、《SenseAudio 隐私政策》（以下称”隐私政策”）等相关协议、政策及规则。**<u>请您在注册成为 SenseAudio 用户前，务必审慎阅读、充分理解本协议及其他相关协议、政策和规则的各条款内容，特别是免除或者限制责任的条款、权利许可和信息使用的条款、法律适用和争议解决条款。该等内容将以粗体下划线标识，您应重点阅读。</u>**

**<u>请确认在您开始注册成为 SenseAudio 用户并使用本服务前，您已具备适用法律规定的与您行为相适应的民事行为能力。如果您因年龄、智力等因素而不具有完全民事行为能力，则您应该在法定监护人（以下简称”监护人”）的陪同下阅读并判断是否同意本协议，在监护人的指导下正确使用本服务，并特别注意未成年人使用条款。我们诚挚地建议监护人关注并引导未成年人合理使用本服务，共同营造积极、健康的网络氛围，帮助未成年人逐步养成良好的上网习惯，避免产生过度依赖或沉迷本服务。若您未取得监护人的同意，监护人可以通过本协议第十二条提供的联系方式通知我们处理相关账户，我们有权对相关账户的功能、使用进行限制，包括但不限于浏览、发布信息、互动交流等功能。如您不具备前述与您行为相适应的民事行为能力而使用我们的服务的，则您及您的监护人应依法承担因此导致的一切后果。</u>**

如果您是中国大陆地区以外的用户，您订立或履行本协议还需要同时遵守您所属和/或所处国家或地区的法律。

**（二）** 您按照注册页面提示填写信息、阅读并点击”同意”或”下一步”且完成全部注册程序，或您单击”注册””登录”等足以表明您注册使用本服务意愿的按钮以使用本服务，或者以其他任何明示或者默示方式表示接受本协议的，即表示您已充分阅读、理解并接受本协议的全部内容及相应的法律责任，并与我们达成一致，成为本服务的”用户”。

**（三）** 本协议内容包括以下条款及本服务已经发布的或将来可能发布的各类规则。所有规则为本协议不可分割的一部分，与本协议具有同等法律效力。**<u>我们有权根据国家法律法规变化、保护消费者权益需要不定时地制定、修改本协议或各类规则。如本协议及规则有任何变更，一切变更以我们在本服务内最新公布的内容为准。</u>** 经修订的协议、规则一经公布，立即自动生效，对新协议、规则生效之后注册的用户发生法律效力。对于协议、规则生效之前注册的用户，若用户在新规则生效后继续使用本服务，则表明用户已充分阅读并认可和同意遵守新的协议或规则。**<u>若您拒绝接受新的协议和规则，您有权放弃或终止继续使用本服务（包括但不限于停止使用用户名和密码登录 SenseAudio、访问或使用本服务等），但您应承担在本服务内已经开展的活动所应承担的任何法律责任，且应遵循您所有开展活动时有效的协议或规则内容。</u>**

**（四）** 如您对本协议有任何疑问，可以通过本协议第十二条提供的联系方式向我们的客服咨询。在您阅读本协议的过程中，**<u>如果您不同意本协议中任何条款约定，您应立即停止注册并退出账户登录，同时停止打开、浏览或使用本服务及相关任何服务。</u>**

**（五）** **本服务提供的所有内容均由人工智能模型答复，可能出现错误或遗漏，<u>本服务对其答复内容的真实性、准确性、完整性和功能性不作任何保证，并且其输出的内容均不代表本服务提供者的态度或观点。您须自行进行核实，特别是针对输出内容中包含的数字、时间以及各类事实性描述（如有）等内容。同时，本服务提供的内容，应仅供您参考，不构成任何建议、承诺或专业意见。若涉及可能对您或相关方可能会产生重大影响的情形，建议您咨询相关专业人士，本服务输出的内容不应成为您进一步行动的依据。我们不承担您因使用本服务给您或任何第三方产生的任何损害或责任。您应科学理性认识和依法使用生成式人工智能技术。我们保留随时修改、中断或终止该大模型服务的权利，并可能在不事先通知的情况下对模型进行更新或改进。</u>**

**（六） 您需特别注意，由于 SenseAudio 创作服务生成的所有内容都是由人工智能模型生成，虽已经过不断的自动及人工敏感数据过滤，但仍不排除其中部分信息具有瑕疵、不合理或引发不快的情形，您对使用 SenseAudio 进行 AI 创作所生成音频的内容负有审慎审核的义务，如生成音频涉嫌违法违规、敏感有害、违反公序良俗等情况，我们倡导您向我们的客服及时反馈，我们收到相关反馈后将作为平台方及时处理相关问题，<u>但您不得因此或利用此情况而开展任何包括但不限于以下行为的违法或不当的活动：（1）通过截图、下载、拍照、录像、屏幕捕捉等方式留存相关图片；或者（2）发送、传播或商业化使用相关图片；或者（3）本协议约定的其他禁止您开展的活动等。</u>否则，因您使用生成内容进行任何违法或不当的活动等被追责所产生的所有责任，由您自行承担。我们因此产生损失的，有权向您追责。**

本协议签订地为中华人民共和国上海市徐汇区。

***

## 一、服务内容及形式

### 1.1 服务内容

SenseAudio 系上海禹幻科技有限公司为用户提供的辅助创作工具，为用户提供语音合成、音色克隆、文生音色、语音识别等功能的服务。同时，<strong>特别提示您，我们提供的服务内容可能随着业务发展的需要进行实时调整，我们有权自行对服务进行调整（包括服务种类增加或减少、服务内容的调整、版本升级等）而无需承担任何责任。</strong>该等调整将在 SenseAudio 网站（域名为：[https://senseaudio.cn/](https://senseaudio.cn/) ）使用上公布，以便通知到您，欢迎您的浏览和使用。

### 1.2 服务形式

您可以通过访问 SenseAudio 网站使用本服务。我们许可您一项个人的、可撤销的、不可转让的、不可分许可的、非独占的、非排他的和非商业的合法使用本服务的权利，<strong><u>您仅可为访问或使用本服务的目的而使用本服务。</u></strong>除非您与我们另有特别约定，否则，未经我们的事先书面授权和许可，您不得对本服务进行商业性的复制、分发、销售或其他商业活动。本协议未明示授权的其他一切权利仍由我们保留，您在行使该等权利前须另行获得我们的书面许可，同时我们如未行使前述任何权利，并不构成对该权利的放弃。

### 1.3 本 SenseAudio 网站的模型和算法信息

本 SenseAudio 网站是依托于深度学习的 Transformer 架构和自回归语言建模技术，对您的输入进行深入的语义解析，输入至生成式扩散模型，生成一系列符合预期的文本、音频、视频内容。这个算法目的在于提高您在语音生成和视频内容生产方面的效率。
该算法主要运行机制为：算法对用户输入的语义进行理解，利用 Transformer 架构、自回归语言建模等本深度合成技术生成符合用户预期的文本、音频、视频内容。
算法备案编号：网信算备 310104482568801230095 号
公示信息链接：[https://beian.cac.gov.cn/#/searchResult](https://beian.cac.gov.cn/#/searchResult)

***

## 二、账户注册、使用与安全

### 2.1 账户注册

**2.1.1** 在本服务账户登录页面中，您需要根据页面指示，填写您的手机号码或电子邮箱进行账户注册，并按要求填写相关信息并确认同意本协议、隐私政策等相关协议、政策及规则。首次登录即视为完成本账户的注册。您注册成功后，我们将给予您一个供您使用的本服务用户帐号。
<strong><u>该用户帐号所有权及有关权益均归我们所有，您仅享有该账户的使用权，您应当正确、适当地使用和管理本账户，该账户在本服务的所有行为均视为您本人行为，您应当对以您用户帐号进行的所有活动和事件负法律责任。</u></strong>

**2.1.2** 注册成功后，您可以完善头像、昵称等资料，但是否完善该等资料均不会影响您继续使用和管理本账户。

### 2.2 账户使用与安全

**2.2.1** 在您使用账户时，您须承诺和保证：
对注册信息的真实性、合法性、有效性承担全部责任，及时更新注册信息，不得冒充他人，不得利用他人的名义使用本服务；
妥善保管账户及密码，若您账户或账户下行为出现纠纷时，由您承担全部责任。所述账户下行为包括但不限于，通过本服务进行的任何操作以及由此产生的任何结果；
因使用本服务、进行交易或获取有偿服务而产生的所有应纳税费，以及一切硬件、软件、服务及其他方面的费用，均由您自行承担。

**2.2.2** 为符合相关法律法规要求并保障您的账户安全，我们可能定期或不定期采用不同方式对您的身份进行验证，包括但不限于要求输入验证码、手机号验证等。<strong><u>如我们发现您以虚假信息骗取账户注册，我们有权不经通知单方采取限期改正、暂停使用、注销账户等措施。</u></strong>

**2.2.3** 一个账户只能由一个用户使用，不允许多个用户使用同一个账户。<strong><u>未经我们书面同意，您不得以任何形式赠与、借用、出租、转让、售卖或以其他方式许可他人使用该账户。如我们发现或有合理理由认为账户使用者并非您本人，我们有权在未通知您的情况下暂停或终止向该账户提供服务，并有权取消该账户权限，而无需向您承担任何责任。您通过个人账户进行的所有操作均视为您的个人行为。您应保证个人行为的合法合规性。我们不对您的个人行为造成的任何损失、损害或赔偿承担责任。</u></strong>

**2.2.4** 如您发现任何非法使用用户账户的情况，应立即通知我们。我们将给予最大限度的配合和处理。<strong><u>但对于您因账户或密码泄露造成的各种损失，我们不承担责任。</u></strong>

**2.2.5** 我们亦会在网站服务端采取合理的技术措施保障您的账户的安全。

### 2.3 账户的冻结、注销及申诉

**2.3.1** 您的账户（全部或部分权限或功能）在如下情况可能被冻结，我们将通过邮件、站内信、短信或电话等方式通知您：

（1）基于 SenseAudio 网站或服务运行和交易安全的需要，如您发生或可能发生破坏或试图破坏我们公平交易环境或正常交易秩序的行为；

（2）违反本协议、SenseAudio 网站的相关规则、规范（如隐私政策、交易规则、管理规范等）、服务说明以及其他服务协议/条款的；

（3）违反法律、法规、政策、法律文书规定的；

（4）您遭到他人投诉，且对方已经提供了相关证据，而您未按照我们的要求提供相反证据的；

（5）我们根据合理分析判断您的账户操作、权益等存在异常的；

（6）有权政府机关要求进行冻结的；

（7）我们发现您以虚假信息骗取账户注册的；

（8）我们合理判断，同一用户发生与如上行为性质相同或产生如上类似风险的其他情况的。

**2.3.2** 出现以下情形之一的，您的账户将被注销，注销成功后，该账户下所有服务、数据将被删除且无法恢复。您注销账户后，除满足《网络安全法》及适用法律对于数据留存的强制性要求以及为解决可能发生的任何争议而保留的历史使用记录外，我们将在相关行为的诉讼时效届满后，删除或匿名化您的个人信息和有关历史使用记录：

（1）您可以通过官方邮箱联系客服注销账户。登录以后在【账号管理】里点击注销按钮，进行注销流程的操作。当您主动提交账户注销申请时，需满足：

（a）在您的账户下，如还有未使用的积分（如有）、已经购买但尚未使用完的权益（以下统称：尚未使用的权益），请您先处理完毕上述尚未使用的权益后再提交注销申请。如果您在准备注销的账户下还有尚未使用的权益的情况下发起相应账户注销流程，将视为您主动放弃相应权益，相应尚未使用的权益在您发起注销流程后将作废或无法再使用。

（b）如您因使用本服务而在本服务中存储、使用等的各种数据或信息，请您在提交注销申请前完成相应数据、信息的迁移和备份或其他操作。因您未及时迁移或备份而申请注销所导致的数据流失、损毁，我们不承担相关责任且没有义务协助您找回。

（2）当出现如上第 2.3.1 条情形且情形严重的，或基于有权政府机关的要求，我们有权对您的相关账户进行注销，我们将通过邮件、短信、电话或其他适宜的方式通知您。

（3）当您连续 12 个月未通过账户登录过 SenseAudio 网站（含账户冻结期间），且您的账户下不存在任何尚未使用的权益，我们有权（但无义务）注销您的账户。

**2.3.3** 我们一经注销该账户，即表示您解除与我们的服务协议关系。这意味着：

（1）您无法再次以原账户登录SenseAudio网站；

（2）无法进行依赖于账号权限进行的操作；

（3）您无法找回该账户下的个人信息、交易记录、生成记录、历史信息等；

（4）账户注销并不代表您在该账户注销前的所有账户行为和相关责任得到豁免或减轻。

**<u>2.3.4 注销用户账户后，我们将：</u>**

**<u>（1）停止收集您的个人信息以及根据第2.3.2条删除或匿名化您的个人信息和历史使用记录；</u>**

**<u>（2）有权保留该用户的注册数据及以前的行为记录，但属于个人信息的除外；</u>**

**<u>（3）有义务在遵守国家法律法规的前提下，保障该账户下的所有数据在实现日常业务功能所涉及的系统中不可被检索、访问；</u>**

**<u>（4）如您在注销前在使用本服务过程中存在违法行为或违反合同的行为，我们仍可行使本协议所规定的权利；</u>**

**<u>（5）账户注销不影响我们在监管机关要求或其他合法场景下，依法确认该账户注销前的用户真实身份等相关义务的履行。</u>**

**2.3.5** 发生前述账户冻结或注销情况下，您应及时予以关注并可以按照程序进行申诉等后续操作：

（i）您通过申诉程序，向我们申请解除上述冻结或注销的，为了您的账户安全，您应配合如实提供身份证明及相关资料，以及我们要求的其他信息或文件，以便我们进行核实。您应充分理解您的申诉并不必然被允许，我们有权决定是否同意您的申诉请求。

（ii）您理解并同意，如果您拒绝如实提供身份证明及相关资料，或未能通过我们审核，我们有权长期冻结该等账户且长期限制账户部分或全部功能，直至前述情形被得以合理纠正，或基于第 2.3.2（3）条的约定注销该账户。

**2.3.6** 您理解并同意，您名下如存在多个账号，因您的违法、违规、违约行为导致其中一个或多个账号被冻结或注销的，我们有权根据具体情形及相关风险程度作合理判断，对您的其他全部或部分账号予以冻结或注销且无需向您承担任何责任，由此带来的因您使用本服务产生的全部数据、信息等被清空、丢失等的损失，您应自行承担。

***

## 三、服务使用规范

### 3.1 内容管理

**3.1.1** SenseAudio 网站上的或与其有关的设计、流程、程序、功能、信息和内容的有关知识产权或其他权益均归我们所有，但是您或其他用户使用 SenseAudio 上传或产生的数据或内容的知识产权、权益或控制权归您或其他用户所有。

**3.1.2** 您知悉、确认并保证，**<u>您不得并被禁止直接或间接地：</u>**

（1）删除、隐匿、改变、复制、使用 SenseAudio 上显示或其中包含的任何专利、版权、商标、所有权及其他权利声明；

（2）以任何方式干扰或企图干扰 SenseAudio 任何部分或功能的正常运行；

（3）避开、尝试避开或使用任何声称能够避开内容保护机制或者 SenseAudio 数据度量工具；

（4）**<u>以任何方式（包括但不限于书面格式或图形方式等）使用任何我们的标志或其他未获得授权的标志</u>**，包括但不限于以对此类标志的所有者的权利的玷污、削弱和损害的方式使用此类的标志，或者以违背本协议的方式为自己或向其他任何人设定或声明设定任何义务或授予任何权利或权限，或者用于商业用途以及其他未经授权的使用；本条所称”标志”，包括但不限于源自 SenseAudio 的任何注册或未注册的商品、服务标志、徽标(LOGO)、URL 或其他标志等；

（5）请求、收集、索取或以其他方式从任何用户那里获取对 SenseAudio 帐号、密码或其他身份验证凭据的访问权；

（6）其他非法获取或使用 SenseAudio 产品及相关服务的信息内容的行为。

**3.1.3** 您确认并同意，即使我们书面许可您对 SenseAudio 产品及相关服务的信息内容的分享、转发等行为，您也还应遵守以下规范：

（1）**<u>不得对 SenseAudio 产品及相关服务的源网页进行任何形式的任何改动</u>**，包括但不限于 SenseAudio 产品及相关服务的首页链接、广告系统链接等入口，也不得对 SenseAudio 产品及相关服务的源页面的展示进行任何形式的遮挡、插入、弹窗等妨碍；

（2）**<u>应当采取安全、有效、严密的措施，防止 SenseAudio 产品及相关服务的信息内容被第三方通过任何形式进行非法获取；</u>**

（3）**<u>不得把相关数据内容用于我们书面许可范围之外的目的</u>**，进行任何形式的销售和商业使用，或向第三方泄露、提供或允许第三方为任何方式的使用；

（4）**<u>您不得导出任何用户信息</u>**，如因任何原因以任何方式从任何途径获取到用户信息或其他 SenseAudio 产品/服务内容等，您必须在获取后的 24 小时内停止使用和删除它们；如果前述获取信息行为是您故意为之，您将对您的行为负相关法律责任，并应当赔偿我们的全部损失。

**3.1.4** 您确认并同意，未经我们书面许可，任何用户、第三方均<strong><u>不得自行或授权、允许、协助他人对 SenseAudio 产品及相关服务中信息内容进行如下行为：</u></strong>

（1）复制、读取、采用 SenseAudio 产品及相关服务的信息内容，用于包括但不限于宣传、增加阅读量、浏览量等商业用途；

（2）擅自编辑、整理、编排 SenseAudio 产品及相关服务的信息内容后在 SenseAudio 产品及相关服务的源页面以外的渠道进行展示；

（3）采用包括但不限于特殊标识、特殊代码等任何形式的识别方法，自行或协助第三人对 SenseAudio 产品及相关服务的信息内容产生流量、阅读量引导、转移、劫持等不利影响；

（4）不得以任何方式（包括但不限于盗链、冗余盗取、非法抓取、模拟下载、深度链接、假冒注册等）直接或间接盗取 SenseAudio 产品及相关服务的视频、图文等信息内容，或以任何方式（包括但不限于隐藏或者修改域名、我们特有标识、用户名等）删除或改变相关信息内容的权利管理电子信息；

（5）**<u>不得以任何形式使用 SenseAudio 网络服务侵犯我们的商业利益，包括并不限于发布非经我们许可的商业广告。</u>**

**3.1.5** <strong><u>您确认并承诺，使用本服务过程中应当遵守法律、法规、规章制度的全部要求</u></strong>，包括但不限于：

（1）您不得为任何非法目的而使用本网络服务系统；

（2）不得利用 SenseAudio 网络服务系统进行任何可能对互联网或移动网正常运转造成不利影响的行为；

（3）您不得利用 SenseAudio 的服务从事以下活动：

（a）未经允许，进入计算机信息网络或者使用计算机信息网络资源的；

（b）未经允许，对计算机信息网络功能进行删除、修改或者增加的；

（c）未经允许，对进入计算机信息网络中存储、处理或者传输的数据和应用程序进行删除、修改或者增加的；

（d）故意制作、传播计算机病毒等破坏性程序的；

（e）其他危害计算机信息网络安全的行为。

### 3.2 信息内容制作规范

**3.2.1** 本协议所述信息内容是指您使用本服务过程中所制作、复制、发布、传播的任何内容，包括但不限于 SenseAudio 帐号头像、名称等注册信息及认证资料，使用 SenseAudio 广场发布的内容或文字、语音、图片、视频、图文等发送、回复和相关链接页面，以及其他使用 SenseAudio 产品和/或服务所产生的内容，也称 SenseAudio 产品信息内容。

**3.2.2** 您理解并同意，SenseAudio 一直致力于为用户提供文明健康、规范有序的网络环境，<strong><u>您不得利用 SenseAudio 帐号或 SenseAudio 服务制作、复制、发布、传播干扰 SenseAudio 正常运营秩序，违反法律法规的规定以及侵犯其他用户或第三方知识产权或合法权益的内容，您不得为其他任何非法目的而使用 SenseAudio。</u></strong>

**3.2.3** 您理解并同意，您使用本服务时将遵守相关法律法规、我们的政策以及我们为此制定的其他规范和标准，<strong><u>不得进行任何违法或不正当的活动</u></strong>，包括但不限于：

（1）反对宪法所确定的基本原则的；

（2）危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的；

（3）损害国家荣誉和利益的；

（4）煽动民族仇恨、民族歧视、破坏民族团结的；

（5）破坏国家宗教政策，宣扬邪教和封建迷信的；

（6）散布谣言，扰乱社会秩序，破坏社会稳定的；

（7）散布淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的；

（8）侮辱或者诽谤他人，侵害他人合法权利的；

（9）违反中国法律、法规、规章、条例以及任何具有法律效力之规范的。

**3.2.4** <strong><u>您不得利用基于生成式人工智能等类似新技术制作、上传、复制、传播虚假新闻信息等法律法规禁止的信息内容。同时，对于您发布或传播利用基于生成式人工智能等类似新技术制作的非真实信息时，应当主动核查信息的真实性、准确性，以显著方式予以标识该信息系由人工智能生成，否则我们有权对相关内容和账户采取包括但不限于增加标识、限制、关闭账号、暂停或者终止向您提供本服务等处置措施。</u></strong>

**3.2.5** 我们已针对生成内容进行了显著标识，提示相关内容系人工智能模型概率生成，用户不得采用技术手段删除、篡改、隐匿上述标识。

**3.2.6** 为了促进互联网内容健康发展，您在 SenseAudio 上的全部行为应符合法律法规底线、社会主义制度底线、国家利益底线、公民合法权益底线、社会公共秩序底线、道德风尚底线、信息真实性底线。您必须为自己注册帐号下的一切行为负责，包括您所发表的任何内容以及由此产生的任何后果。<strong><u>您应对本服务中的内容自行加以判断，并承担因使用内容而引起的所有风险，包括因对内容的合法性、正确性、完整性或实用性的依赖而产生的风险。我们无法且不会对因前述风险而导致的任何损失或损害承担责任。</u></strong>

### 3.3 用户行为规范

**3.3.1** 任何用户发现 SenseAudio 中内容涉嫌侮辱或者诽谤他人、侵害他人合法权益的或违反本协议的，有权联系我们进行投诉。

**3.3.2** 为了能够给广大用户提供一个优质的创作平台，同时使 SenseAudio 能够良性、健康的发展，将对涉及反动、色情的头像、签名档和发布盗版和不良内容的用户，进行严厉处理。一经发现此类行为，将视情况给予暂时或永久禁止发言、封禁 ID 并清空所有发布内容的处罚。

**3.3.3** 如果我们发现或收到他人举报或投诉用户发布的内容侵权、违法或违反本协议约定的，<strong><u>我们有权在通过站内信等方式通知您并转送他人举报或投诉理由后，随时对相关内容进行删除、屏蔽，并视行为情节对违规账户处以包括但不限于警告、限制或禁止使用部分或全部功能、账户冻结直至注销的处理，并公告处理结果。</u></strong>

**3.3.4** 您理解并同意，<strong><u>我们有权依合理判断对违反有关法律法规或本协议规定的行为进行处罚，对违法违规的任何用户采取适当的法律行动</u></strong>，并依据法律法规保存有关信息向有关部门报告等，用户应独自承担由此而产生的一切法律责任。

**3.3.5** 您理解并同意，<strong><u>因您违反本协议或相关服务条款的规定，导致或产生第三方主张的任何索赔、要求或损失，您应当独立承担责任；我们因此遭受损失的，有权向您追偿。</u></strong>

**3.3.6** 您理解并同意，为了向您提供有效的服务，本服务会利用您的终端设备的处理器和带宽等资源。
<strong><u>本服务使用过程中可能产生数据流量的费用，您需自行向运营商了解相关资费信息，并自行承担相关费用。</u></strong>

**3.3.7** 您理解并同意，<strong><u>本服务的某些功能可能会让第三方知晓用户的信息，例如：发布个人动态、关注时，您的头像、昵称、个人动态内容等会被第三方知晓。</u></strong>

**3.3.8** 您在使用本服务某一特定服务时，该服务可能会另有单独的协议、相关业务规则等（以下统称为”单独协议”），您在使用该项服务前请阅读并同意相关的单独协议；您使用前述特定服务，即视为您接受相关单独协议。

**3.3.9** <strong><u>您在使用本服务时，须自行承担如下来自 SenseAudio 不可掌控的风险内容</u></strong>，包括但不限于：

（1）由于不可抗拒因素可能引起的个人信息丢失、泄漏等风险；

（2）您必须选择与所安装终端设备相匹配的服务版本，否则，<strong><u>由于服务与终端设备型号不相匹配所导致的任何问题或损害，均由您自行承担</u></strong>；

（3）您在使用本服务访问第三方网站时，<strong><u>因第三方网站及相关内容所可能导致的风险，由您自行承担</u></strong>；

（4）您发布的内容被他人转发、分享，因此等传播可能带来的风险和责任；

（5）由于无线网络信号不稳定、无线网络带宽小等原因，所引起的 SenseAudio 登录失败、资料同步不完整、页面打开速度慢等风险；

（6）您确认并知悉当前体验服务生成的<strong><u>所有内容都是由人工智能模型生成，我们对其生成内容的准确性、完整性和功能性不做任何保证</u></strong>，并且其生成的内容不代表我们的态度或观点。  我们的服务来自于法律法规允许的包括但不限于公开互联网等信息积累，并已经过不断的自动及人工敏感数据过滤，但仍不排除其中部分信息具有瑕疵、不合理或引发不快，如有发生请您谅解，并向我们的客服及时反馈，我们收到相关反馈后将作为平台方及时处理相关问题。

### 3.4 服务费用

**3.4.1** 我们在 SenseAudio 向您提供的部分服务可能需要消耗积分，具体以 SenseAudio 网站展示内容为准。

**3.4.2** SenseAudio 创作功能为积分消耗机制，您可以通过（包括但不限于）注册赠送、每日登录、完成任务、参与活动等方式免费获得积分，也可以通过订阅会员、购买套餐获得积分及解锁更多功能权益，该等积分不得转让、抵现或继承。  具体积分使用规则、计费方式、收费标准和支付方式以 SenseAudio 内提供和相关页面详情内容为准。

**3.4.3** 我们可能根据业务发展和实际需要对收费服务的积分规则、收费标准、方式进行修改和变更。前述修改、变更或开始收费前，我们将在相应服务页面进行通知或公告。<strong><u>如果您不同意上述修改、变更或付费内容，则应停止使用该服务。</u></strong>

***

## 四、用户个人信息保护

您的信任对我们非常重要，我们深知用户信息安全的重要性。保护用户个人信息是我们的一项基本原则，我们将按照法律规定，采取合理的措施保护用户的个人信息。隐私政策介绍了您在使用 SenseAudio 时，我们将如何收集和使用您的个人信息。您使用 SenseAudio 的服务，即表示您同意我们可以按照隐私政策收集和使用您的个人信息。<strong><u>请您在注册成为 SenseAudio 网站用户前，务必审慎阅读、充分理解《隐私政策》内容。</u></strong>

***

## 五、知识产权及相关权益

**5.1** <strong><u>我们保留对以下各项内容、信息完全的、不可分割的（包括但不限于）所有权、知识产权和/或其他合法权益：</u></strong>

（1）SenseAudio 及其所有元素，包括但不限于所有内容、数据、技术、软件、代码、用户界面、商标、logo 等商业标识以及与其相关的任何衍生作品；

（2）用户向我们提供的与该服务相关的任何信息及反馈。

**5.2** 未经我们同意或协议另有明确约定，<strong><u>上述资料均不得在任何媒体直接或间接地：（1）发布或者播放，或者（2）出于播放或发布目的而改写或再发行，或者（3）被用于其他任何商业目的。</u></strong>
<strong><u>我们不会因以下情况而产生任何赔偿责任，或以任何形式向用户或任何第三方负法律、经济责任：上述资料产生或在传送或递交全部或部分上述资料过程中产生的延误、不准确、错误和遗漏，或者由此产生的任何损害。</u></strong>

**5.3** SenseAudio 为提供网络服务而使用的任何软件（包括但不限于软件中所含的任何图像、照片、动画、录像、录音、音乐、文字和附加程序、随附的帮助材料）的一切权利均属于该软件的著作权人，未经该软件的著作权人许可，用户不得对该软件进行反向工程（reverse engineer）、反向编译（decompile）或反汇编（disassemble），或以其他方式发现其原始编码，以及实施任何涉嫌侵害著作权的行为。

**5.4** 用户在使用本服务中所产生的内容的知识产权归用户您本人所有，<strong><u>用户通过本服务发布的内容（以下统称为”公开发布内容”）经过人工审核通过，一经发布即向公众传播。</u></strong>

**5.5** 您理解并同意，<strong><u>您向任何第三人分享、转发、复制 SenseAudio 产品信息内容的行为，均应遵守我们为此制定的规范和标准</u></strong>，包括但不限于展示方式应为该信息或内容的原链接、确保附属于该信息或内容的功能可正常使用等。

**5.6** <strong><u>任何未经我们书面同意及权利人许可的获取行为，均是非法获取行为，均属违法侵权行为。</u></strong>您确认并同意，为及时、有效地保障您基于本服务的合法权益，<strong><u>您特别授权我们可以</u></strong>在发现您的合法权益（包括但不限于信息网络传播权、著作权等）可能受到侵害并进一步危害到我们的利益时，我们有权立即通知您，<strong><u>经您同意后或者特殊时刻为避免您或者我们的权益进一步损害时，以自己的名义或委托专业第三方机构向涉嫌侵权的第三人采取法律手段进行维权，</u></strong><strong>您特别授权我们采取的维权手段包括但不限于侵权监控、发函警告、行政举报、提起诉讼、申请仲裁、移送侦查机关处理、调解、和解等；</strong>您仅对上述事件中涉及到您本人的权利进行授权，同时，请您注意，您对我们的上述授权，并不意味着我们与您之间存在任何利益共享机制，也<strong><u>不意味着我们具有对外主张您权益的义务，我们亦有权选择交由您本人处理仅与您本人权益相关的事务。</u></strong>

**5.7** 您应保证<strong><u>提供至我们的各项信息、上传至 SenseAudio 网站上的全部数据、对 SenseAudio 网站的使用，以及使用本服务所涉及的素材或产生的相应成果不会侵犯任何第三方的合法权益（包括但不限于知识产权、肖像权等），也不应违反公共利益和公序良俗，否则导致的一切不利后果包括据此做出的后续行为产生的法律责任均由您自行承担，如有第三方就您所提供、上传或使用的信息、数据或就您的行为及工作成果向我们提起任何投诉、索赔、诉讼或其他类型的诉求，则您理解并确认，您应立即出面解决，并应赔偿我们及其关联公司因此遭受的全部直接、间接损失（包括但不限于经济、商誉、维权支出、赔偿支出、诉讼费、律师费等损失和支出）。</u></strong>

**5.8** 您理解并同意，为持续改善为您提供的各项服务，除非有相反证明，<strong><u>您使用 SenseAudio 服务上传、发布或传输内容即代表了您有权且同意在全世界范围内，永久性的、不可撤销的、免费的授予我方及其关联方的全部产品或服务对该内容的存储、使用、发布、复制、修改、改编、出版、翻译、据以创作衍生作品、传播、表演和展示等权利；将内容的全部或部分编入其他任何形式的作品、媒体、技术中的权利；对您的上传、发布的内容进行商业开发的权利；通过有线或无线网络向计算机终端、移动通讯终端（包括但不限于便携式通讯设备如手机和智能平板电脑等）、手持数字影音播放设备、电视接收设备（模拟信号接收设备、数字信号接收设备、数字电视、IPTV、电视机机顶盒、视频投影仪、车载电视、互联网电视/OTT 终端、智能电视等带互联网接入功能的播放设备等）等提供信息的下载、点播、数据传输、移动视频业务（包括但不限于 SMS、MMS、WAP、IVR、Streaming、手机视频等无线服务）及其相关宣传和推广等服务的权利；以及再授权给其他第三方以上述方式使用的权利，在法律允许的范围内使用该等内容，例如允许我们和/或关联方使用该等信息内容来优化模型、提升服务、品牌推广和宣传。</u></strong>上述授权为普通授权许可。

**5.9** 本服务所包含的内容的知识产权均受到法律保护，未经过我们、用户或相关权利人书面许可，任何人不得以任何形式进行使用或创造相关衍生作品。

***

## 六、保密

**6.1** 我们将采取严格措施对用户提供的个人资料和其他信息保密，并将严格按照法律法规，监管等要求保存、管理、使用用户提供的所有资料。同时，维护本服务的安全与正常使用是我们和您的共同责任，我们将采取适当的安全措施和技术手段维护 SenseAudio 网站。

**6.2** 您理解并同意，<strong><u>若非因我们人为原因，如因天灾、盗窃、抢劫、黑客攻击等造成信息泄露的，我们不承担法律责任。</u></strong>

**6.3<u>我们在下述情况下不再承担保密义务：</u>**

**<u>a) 因非我们的原因，您提供的信息、语音、视频及文字稿件被公开的；</u>**

**<u>b) 法律法规要求、行政司法机关要求、或其他有权机关要求披露的；</u>**

**<u>c) 事先获得您的授权；</u>**

**<u>d) 为查找、预防或处理欺诈、安全或技术方面的问题；</u>**

**<u>e) 为执行相关服务协议或本协议、维护社会公共利益；</u>**

**<u>f) 为保护我们的客户、我们或我们的关联公司、其他用户或雇员的人身财产安全或其他合法权益等合理且必要的用途。</u>**

上述保密义务不因本协议条款的变更、解除或终止而终止。

***

## 七、免责声明

**7.1** 鉴于网络服务的特殊性，用户同意 SenseAudio 随时变更、中断或终止部分或全部的网络服务。如变更、中断或终止的网络服务属于免费网络服务，我们无需通知用户，也无需对任何用户或任何第三方承担任何责任。

**7.2** 您理解，SenseAudio 需要定期或不定期地对提供网络服务的平台或相关的设备进行检修或者维护，如因此类情况而造成收费网络服务在合理时间内的中断，我们无需为此承担任何责任，但我们应尽可能事先进行通告。

**7.3** SenseAudio 可在任何时候为任何原因变更本服务或删除其部分功能。我们可在任何时候取消或终止对用户的服务。我们取消或终止服务的决定不需要理由或通知用户。一旦服务取消，用户使用本服务的权利立即终止。一旦本服务取消或终止，用户在本服务中储存的任何信息可能无法恢复。

**7.4** 我们不保证（包括但不限于）：

（1）本服务适合用户的使用要求；

（2）本服务不受干扰，及时、安全、可靠或不出现错误，用户经由本服务取得的任何产品、服务或其他材料符合用户的期望；

（3）**<u>您使用经由本服务取得的任何资料，其风险由您自行承担；因该等使用导致您的电脑系统损坏或资料流失，您应自己负完全责任。</u>**

**7.5** 基于以下原因而造成的利润、商业信誉、资料损失或其他有形或无形损失，我们不承担任何直接、间接的赔偿：

（1）对本服务的使用或无法使用；

（2）经由本服务购买或取得的任何产品、资料或服务；

（3）您的资料遭到未授权的使用或修改；及

（4）其他与本服务相关的事宜。

**7.6** **<u>由于您授权第三方（包括第三方应用）访问/使用其本服务所导致的纠纷或损失，应由您自行承担。</u>**

**7.7** 我们会根据您选择的服务类型向您提供相应的服务。您理解并同意，基于用户体验或 SenseAudio 运营安全、SenseAudio 规则要求及健康发展等综合因素，**<u>我们有权选择提供服务或开展合作的对象，有权决定功能开放、数据接口和相关数据披露的对象和范围，并有权视具体情况中止或终止向存有包括但不限于以下情形的用户提供本服务：</u>**（1）违反法律法规或本协议规定的；（2）影响使用者体验的；（3）存在安全隐患的；（4）违背 SenseAudio 运营原则或其他管理要求的。

**7.8** **本服务仅限于在中国大陆地区使用，如您擅自在中国大陆以外（特别是欧盟）地区使用，禹幻科技公司不承担因此而产生的任何责任。**

***

## 八、第三方软件或技术

**8.1** 本服务可能会使用第三方软件或技术（包括可能使用的开源代码和公共领域代码等，下同），这种使用已经获得合法授权。

**8.2** 本服务如果使用了第三方的软件或技术，我们将按照相关法规或约定，对相关的协议或其他文件，可能通过本协议附件、在本软件安装包特定文件夹中打包、或通过开源软件页面等形式进行展示，它们可能会以”软件使用许可协议”、”授权协议”、”开源代码许可证”或其他形式来表达。前述通过各种形式展现的相关协议、其他文件及网页，均是本协议不可分割的组成部分，与本协议具有同等的法律效力，您应当遵守这些要求。如果您没有遵守这些要求，该第三方或者国家机关可能会对您提起诉讼、罚款或采取其他制裁措施，并要求我们给予协助，您应当自行承担法律责任。

**8.3** 您充分理解到：在您使用本服务时，本服务正在使用的第三方授权软件或技术，仅仅是本服务当前”正在”使用的第三方授权的软件或技术，我们不保证本小程序将会永久地使用该等软件或技术，不保证将来不会使用该第三方的其他的软件或技术，亦不保证将来不会使用非该第三方的同类型或不同类型的软件或技术。

**8.4** 如因本服务使用的第三方软件或技术引发的任何纠纷，应由该第三方负责解决，我们不承担任何责任。我们不对第三方软件或技术提供客服支持，若您需要获取支持，请与第三方联系。

***

## 九、违约责任

用户违反本协议任何一款的保证，我们均有权就相关情节，对用户做出警告、屏蔽、冻结直至注销账户的处理；如 **<u>因用户违反上述保证而给 SenseAudio 产品服务、SenseAudio 产品服务用户或 SenseAudio 的任何合作伙伴造成损失，用户需承担一切法律责任并赔偿损失；如相关机构判令我们对此承担责任的，我们有权向您追偿。</u>**

### 9.1 违约情形

**9.1.1** 用户在访问/使用本服务时，如发生以下情形之一的，视为您违约：

（1）违反法律法规；

（2）违反本协议及本协议相关协议等一切用户服务条款及规则。

**9.1.2** 在使用 SenseAudio 的过程中，用户发现任何可能侵害自己或我们权利的事实时，应及时通知我们并提供相应的证明材料。**<u>因投诉不实给我们或第三方造成损失的，用户应承担法律责任。</u>**

**9.1.3** 在我们调查相关争议事实时，您有义务就相关事实向我们合理解释并举证证明。如您既不做出合理解释又不进行任何举证，也不采取任何有效止损行为（如需），我们将可能结合您该种消极应对态度认定您构成违约并采取相应救济措施。

### 9.2 违约、侵权处理措施

**9.2.1** 您在 SenseAudio 上发布的信息构成违约或侵权的，SenseAudio 可根据相应规则立即对相应信息进行删除、屏蔽处理。

**9.2.2** 您在 SenseAudio 上实施的行为 **（包括但不限于侵犯第三方知识产权等）或重复出现侵权行为时**，或虽未实施但对我们及用户产生影响的行为构成违约或侵权的，我们 **<u>可依据相应规则要求您限期纠正违规或违约、侵权行为、屏蔽或限制您使用我们的部分或全部功能、降低权限、对违法违规侵权内容进行屏蔽或删除、中止向您提供部分或全部服务、及其他合理必要处理措施。</u>** 如您的行为构成根本违约的，**<u>我们有权解除本协议及相关协议，终止向您提供服务。</u>**

**9.2.3** **<u>我们可将对您上述违约或侵权行为处理措施信息以及其他经国家行政或司法机关生效法律文书确认的违法信息在 SenseAudio 网站上予以公示。</u>**

### 9.3 赔偿责任

**9.3.1** 如因您利用 SenseAudio 提供的网络服务上传、制作、传送或通过其他方式传播侵犯了第三方的合法权益（包括但不限于专利权、商标权、著作权及著作权邻接权、肖像权、隐私权、名誉权等）而导致我们或与我们合作的其他单位面临任何投诉、举报、质询、索赔、诉讼，或者使我们或与我们合作的其他单位因此遭受任何名誉、声誉或者财产上的损失，您应积极地采取一切可能采取的措施，以保证我们或与我们合作的其他单位免受上述索赔、诉讼的影响。**<u>同时您对我们或与我们合作的其他单位因此遭受的直接及间接经济损失负有全部的损害赔偿责任；如相关机构判令我们对此承担责任的，我们有权向您追偿。</u>**

**9.3.2** 除本条另有约定外，如您的行为使我们及/或其关联我们、第三方向我们遭受损失（包括自身的直接经济损失、商誉损失及对外支付的赔偿金、和解款、律师费、诉讼费等间接经济损失），**<u>您应赔偿我们及/或其关联我们、第三方向我们的上述全部损失。</u>**

**9.3.3** 本协议所指 **<u>赔偿损失，包含直接经济损失与间接损失，包括但不限于我们因此而支付的赔偿金/补偿金、商誉损失、预期可得利益、差旅费、打印费、餐饮住宿费、通讯费、公证费、公告费、财产保全费、律师费、案件受理费、税费等。</u>**

**9.3.4** **您同意并认可，除非法律的强制性规定，即使在本协议未约定的情况下，您向我们追索的最高累计赔偿或补偿金额应以 5000 元人民币为限。**

***

## 十、未成年人使用条款

**10.1** 若您是未满 18 周岁的未成年人，您应在您的监护人监护、指导下并获得监护人同意的情况下，认真阅读并同意本协议后，方可使用 SenseAudio 产品及相关服务。为维护未成年人”清朗”网络环境，引导教育未成年人树立正确价值观，保护未成年人身心健康发展，我们对于侵害未成年人合法权益的行为秉持”零容忍”的态度，根据国家相关法律和行政法规，制定本规范。

**10.2** 我们重视对未成年人个人信息的保护，未成年用户在填写个人信息时，请加强个人保护意识并谨慎对待，并应在取得监护人的同意以及在监护人指导下正确使用 SenseAudio 产品及相关服务。

**10.3** **<u>未成年人用户及其监护人理解并确认，如您违反法律法规、本协议内容，则您及您的监护人应依照法律规定承担因此而可能导致的全部法律责任。</u>**

**10.4 未成年人用户特别提示**

（1）未成年人使用 SenseAudio 产品及相关服务应该在其监护人的监督指导下，在合理范围内正确学习使用网络，避免沉迷虚拟的网络空间，养成良好上网习惯。

（2）青少年用户必须遵守《全国青少年网络文明公约》：

（a）要善于网上学习，不浏览不良信息；

（b）要诚实友好交流，不侮辱欺诈他人；

（c）要增强自护意识，不随意约会网友；

（d）要维护网络安全，不破坏网络秩序；

（e）要有益身心健康，不沉溺虚拟时空。

（3）为更好地保护未成年人隐私权益，**<u>我们特别提醒您慎重发布包含未成年人素材的内容</u>**，一经发布，即 **<u>视为您已获得权利人同意在 SenseAudio 产品及相关服务展示未成年人的肖像、声音等信息，且允许我们依据本协议使用、处理该等与未成年人相关的内容。</u>**

**10.5 监护人特别提示**

（1）如您的被监护人使用 SenseAudio 产品及相关服务的，您作为监护人应指导并监督被监护人的注册和使用行为，**<u>如您的被监护人申请注册 SenseAudio 账户，我们将有权认为其已取得您的同意。</u>**

（2）**<u>您的被监护人在使用 SenseAudio 产品及相关服务时可能使用充值积分等功能。您作为监护人，请保管好您的支付设备、支付账户及支付密码等</u>**，以避免被监护人在未取得您同意的情况下通过您的 SenseAudio 账户使用充值等功能。若您的被监护人购买我们的产品或者服务，我们将有权认为其已经取得您的同意。

***

## 十一、法律适用与管辖

**11.1** 本协议之签订与执行（包括生效、履行、解释、修订与补充、终止与争议解决）均适用中华人民共和国大陆地区法律、法规及规章；如法律、法规及规章无相关规定的，参照国家标准及/或行业惯例。

**11.2** 本协议任一条款终止或被视同终止、无效或不可执行，该条款应当被视为本协议的可拆分条款，并不影响其余条款的有效性及可执行性。

**11.3** 除非我们以书面形式做出表示，否则在任何情况下我们做出的任何行为都不应被理解为放弃权利的表示。

**11.4** 凡因履行本协议所发生的争议，由您和我们友好协商解决，不能协商解决的，**<u>可向上海禹幻科技有限公司所在地（上海市徐汇区）人民法院提起诉讼。</u>**

***

## 十二、反馈与投诉

**12.1** 我们高度重视保护知识产权和人格权等合法权益，通过设置敏感词过滤和人工监测等手段，尽可能避免违规、侵权或令人不适的内容输出。但是现有技术不可能完全屏蔽所有违规、侵权或令人不适的内容。如果您认为我们在提供服务的过程中，或者他人在使用本服务的过程中，侵犯了您的合法权益，欢迎您随时通过 SenseAudio 网站邮箱 [senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com) 向我们进行反馈与投诉，并提供相应的合法权益证明资料和侵权内容凭证等，我们将对您的意见进行高度重视并根据现行有效的规定对违规内容采取删除、屏蔽等必要措施，同时对您表示十分感谢！

**12.2** 在收到您的投诉举报后，我们将尽快受理并展开调查。我们将于收到投诉举报后的 10 个工作日内提供反馈，并及时整改可能存在的相关问题。

***

## 十三、服务协议的修改和终止

**13.1** **<u>我们有权对本协议条款及相应的服务规则内容进行变更，并将通过网页公告、电子邮件、站内信、短信等方式予以公告或通知；若您在本协议条款内容变更后继续使用本服务的，表示您已充分阅读、理解并接受修改后的内容，也将遵循修改后的条款内容。</u>**

**13.2** 在您的账号注销或经双方协商一致终止网站服务的，本协议终止。

***

## 十四、其他

**14.1** **<u>本协议自用户同意勾选或网上签署并成功注册成为本服务用户之日起生效，除非我们终止本协议或者用户丧失本服务用户资格，否则本协议始终有效。本协议终止并不免除用户根据本协议或其他有关协议、规则所应承担的义务和责任。</u>**

**14.2** 如本协议中的任何条款无论因何种原因完全或部分无效或不具有执行力，本协议的其余条款仍应有效并且有约束力。

**14.3** **<u>本协议下的保密条款、知识产权条款、法律适用与管辖条款以及性质上理应存续的其他条款（如对注册信息的真实性保证等），不因本协议的终止而失效。</u>**


# 语音识别介绍
Source: https://docs.senseaudio.cn/guides/asr/overview

SenseASR 语音识别能力总览、模型对比与接口选型

SenseAudio 的语音识别（Automatic Speech Recognition, ASR）是专为多场景设计的全栈式语音识别解决方案。从极致的实时响应到深度的语义理解与音频质量检测，SenseASR 系列涵盖了从基础识别到智能内容生成的全链路需求，旨在帮助开发者快速构建高性能的语音应用。

## 核心特性

### 极致响应与超低延迟

深度优化音频处理链路，确保快速响应：

* **低延迟体验**：优化流式识别链路，实现"所见即所言"，首屏反馈延迟极低。
* **高性能并发支撑**：成熟的分布式架构，能够稳定承载大规模并发请求，保障业务高峰期的服务连续性。

### 语义智能识别

突破传统的逐字识别，融入深度的语义理解：

* **意图感知**：识别过程中同步理解语义，能够精准捕获说话人的核心意图。
* **语境逻辑优化**：结合上下文进行语义识别，有效提升在复杂表述或特定行业语境下的识别准确度。

### 智能内容整理与书面化

针对口语转文字的痛点，提供自动优化技术：

* **智能整理**：自动识别并剔除口语中的"呃、啊、那个"等冗余词与语气词；自动识别改口、重复，直接整合最终结论。
* **逻辑条理化**：支持自动分段、修正词汇偏差，将杂乱的口语转化为逻辑清晰、排版规范的书面化文档。

### 音频质量监测

支持在识别链路中对音频进行评估，确保数据处理的可靠性：

* **多维质量报告**：评估噪声分数，噪声种类等。
* **噪声分析**：对音频噪声进行专业分析，帮助开发者筛选或评估原始音频文件的质量。

## 应用场景

### 办公协作与数字化会议

在日常会议、讲座培训或多方谈话场景下，实现语音内容的同步记录与归档。支持标准话语的稳定识别，确保会议纪要的准确性与时效性。

* **核心价值**：提供高精度的通用识别能力，支持长音频文件的一键识别，助力企业知识资产的沉淀。

### 深度采编与内容生产

针对媒体访谈、演讲稿录入、自媒体创作等专业场景，提供基于大模型的文本精修服务。自动处理口语冗余，将原始素材直接转化为可阅读的专业文稿。

* **核心价值**：实现口语转书面表达，自动剔除语气词并进行逻辑分段，减少人工二次整理工作。

### 智能指令与设备控制

为智能家居、车载系统、穿戴设备提供高效的语音反馈能力。在接收到用户的短语音输入后，系统迅速返回识别结果，驱动下游指令执行。

* **核心价值**：实现低延迟的任务反馈，保障在车载交互或智能家居控制中的流畅体验。

### 教育培训与学术整理

构建智能教学助手，对课堂教学、在线讲座或语言学习音频进行文字化处理。支持多语种环境下的精准识别，辅助生成学习笔记与教学参考。

* **核心价值**：支持专业词汇的准确识别，帮助学生或研究人员快速提取核心知识点，实现学习路径的个性化管理。

## 模型对比

| 能力         | senseaudio-asr-lite-1.5-260319 | senseaudio-asr-1.5-260319 | senseaudio-asr-pro-1.5-260319 | senseaudio-asr-deepthink-1.5-260319 |
| :--------- | :----------------------------: | :-----------------------: | :---------------------------: | :---------------------------------: |
| **基础识别**   |                ✅               |             ✅             |               ✅               |                  ✅                  |
| **流式返回**   |                ❌               |             ❌             |               ❌               |                  ✅                  |
| **说话人分离**  |                ❌               |             ❌             |               ✅               |                  ❌                  |
| **字级时间戳**  |                ❌               |             ✅             |               ✅               |                  ❌                  |
| **句级时间戳**  |                ❌               |             ✅             |               ✅               |                  ❌                  |
| **翻译**     |                ❌               |             ❌             |               ✅               |                  ✅                  |
| **热词增强**   |                ✅               |             ❌             |               ❌               |                  ❌                  |
| **智能编辑收敛** |                ❌               |             ❌             |               ❌               |                  ✅                  |
| **多语言支持**  |                ✅               |             ✅             |               ✅               |                  ✅                  |

## 接口概览

SenseAudio 提供两种接口协议，满足不同场景的语音识别需求：

### HTTP 统一接口

基于标准 HTTP 协议的语音识别服务，适用于离线音频文件识别场景。

| 接口路径                                                                     | 接口类型 | 说明                                        | 支持模型                        |
| :----------------------------------------------------------------------- | :--- | :---------------------------------------- | :-------------------------- |
| [`/v1/audio/transcriptions`](/api-reference/endpoint/asr/transcriptions) | POST | 多模型语音识别统一接口，支持文件上传、流式返回、说话人分离、字级时间戳、翻译等功能 | Lite、Standard、Pro、DeepThink |

**核心特性：**

* 支持 4 种识别模型，灵活选择速度与精度
* 支持 wav、mp3、ogg、pcm、flac、aac、m4a 等多种音频格式
* 提供 JSON、Text、Verbose JSON、SSE 流式等多种响应格式
* 兼容 OpenAI Audio API 风格，易于迁移

### WebSocket 实时接口

基于 WebSocket 协议的全双工实时语音识别，适用于实时语音交互场景。

| 接口路径                                                                   | 接口类型      | 说明                             | 支持模型      |
| :--------------------------------------------------------------------- | :-------- | :----------------------------- | :-------- |
| [`/ws/v1/audio/transcriptions`](/api-reference/endpoint/asr/websocket) | WebSocket | 实时语音流识别，支持边录边转、VAD 自动断句、智能指令翻译 | DeepThink |

**核心特性：**

* 全双工通信，音频上传与文本下发同步进行，延迟极低
* 内置 VAD（语音活动检测），自动识别语音停顿并智能断句
* 支持智能指令转译
* 支持多种语言的实时识别

### 接口选择指南

根据业务场景选择合适的接口：

| 场景       | 推荐接口              | 理由                         |
| :------- | :---------------- | :------------------------- |
| 录音文件识别   | HTTP 统一接口         | 支持多种文件格式，功能丰富（说话人分离、情感分析等） |
| 实时语音对话   | WebSocket 实时接口    | 低延迟，边说边识别，适合交互场景           |
| 批量音频处理   | HTTP 统一接口         | 稳定可靠，支持并发请求                |
| 智能语音助手   | WebSocket 实时接口    | 实时反馈，支持智能指令解析              |
| 会议记录（离线） | HTTP 统一接口（Pro 模型） | 支持说话人分离、字级时间戳              |
| 会议记录（实时） | WebSocket 实时接口    | 实时生成会议纪要                   |

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 创建您的 API Key。
  </Step>

  <Step title="选择调用方式">
    离线文件场景使用 [语音识别转写](/api-reference/endpoint/asr/transcriptions)；实时对话场景使用 [WebSocket 实时识别](/api-reference/endpoint/asr/websocket)。
  </Step>

  <Step title="处理识别结果">
    根据业务需要读取文本、时间戳、说话人分离或翻译结果。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="语音识别转写" icon="file-audio" href="/api-reference/endpoint/asr/transcriptions">
    离线文件识别统一接口。
  </Card>

  <Card title="WebSocket 实时识别" icon="bolt" href="/api-reference/endpoint/asr/websocket">
    全双工实时语音识别协议详解。
  </Card>

  <Card title="音频质量检测" icon="wave-square" href="/api-reference/endpoint/asr/analysis">
    噪声评分与噪声类型分析。
  </Card>

  <Card title="语音识别历史" icon="clock-rotate-left" href="/api-reference/endpoint/asr/records">
    按会话或 API Key 查询识别记录。
  </Card>
</CardGroup>


# 音频生成介绍
Source: https://docs.senseaudio.cn/guides/audio/overview

多角色对白、背景音乐与环境音效一体化生成能力概览

SenseAudio 音频生成服务面向短视频、播客、有声内容与品牌营销等场景，提供基于自然语言描述的完整音频生成能力。你可以直接描述角色、台词、情绪、声音风格、背景音乐和环境音效，也可以添加参考音色，一次生成包含多角色人声与声音环境的完整音频。

## 什么是音频生成

音频生成将角色配音、情绪演绎、背景音乐与环境音效整合到一条创作链路中。你无需分别完成配音、音效制作和混音，只需描述期望的声音内容与效果，即可生成完整音频。

## 核心能力

* **描述即创作**：通过自然语言描述角色、台词、情绪、声音风格、节奏和场景，直接生成对应音频。
* **多角色多音轨一体生成**：支持在一次任务中生成多角色对白、背景音乐与环境音效，并完成整体声音编排。
* **灵活的参考音色**：可从音色广场选择平台音色、使用个人音色或上传本地参考音频，最多添加 3 个参考音色。
* **完整创作链路**：支持灵感模板、生成试听、音频下载与历史作品回听，覆盖从创意到成品的完整流程。

## 主要特性

* **自然语言控制声音表现**：可直接描述角色年龄、声线、语气、情绪、说话方式和节奏，也可描述笑声、叹气、停顿等副语言表现。
* **多角色连续演绎**：可在同一段音频中定义多个角色及对应台词，并分别设置角色声音与情绪。
* **人声、音乐与音效统一生成**：背景音乐、环境声、动作音效和角色台词可在同一提示词中描述，无需分别生成后再进行混音。
* **参考音色与文字描述结合**：有明确声音需求时可添加参考音色；没有合适音色时，也可以直接通过文字描述创建角色声音。

> 当前主要面向中文音频创作，暂不支持参考图片、多语种创作和时间戳级精确控制。

## 提示词写法建议

推荐按照 **角色列表 → 场景 → 音频内容** 的结构描述。先明确有哪些角色及其声音特征，再描述整体场景，最后按照实际发生顺序编排台词、背景音乐、环境音和具体音效，可以获得更加稳定、完整的生成效果。

* **角色列表**：写明角色名称，并补充年龄、性别、声音质感、情绪基调或角色类型。如已选择音色广场或个人克隆音色，可直接作为该角色的参考声音。
* **场景**：描述时间、地点、人物状态和整体氛围，帮助模型建立完整的声音环境。
* **角色台词**：使用 `{speaker：角色名}` 标记说话人，并在台词前用括号补充语气、情绪、音量、语速或动作状态。
* **声音元素**：使用 `[背景音乐]`、`[背景音效]`、`[音效]` 等标签描述不同类型的声音，并按照希望出现的先后顺序编排。

## 参数选择建议

| 场景              | 推荐方式        | 说明                                                   |
| --------------- | ----------- | ---------------------------------------------------- |
| 快速寻找合适的角色声音     | 音色广场        | 从平台已有音色中直接选择适合角色年龄、性格和内容风格的声音，适合短视频、剧情、广告等需要快速制作的场景。 |
| 固定本人、IP 或长期角色声音 | 克隆自己的声音     | 使用少量本人声音样本创建可重复调用的个人音色，适合播客、个人 IP、系列内容及固定角色长期生产。     |
| 已有外部声音参考        | 上传参考音频      | 上传本地音频作为声音参考，适合临时角色或已有声音素材；最多支持添加 3 个参考音色。           |
| 没有明确参考声音        | 文字描述音色      | 直接描述年龄、性别、声线、性格和说话方式，由模型根据文字要求生成角色声音。                |
| 多角色内容           | 为主要角色分别指定音色 | 建议优先为核心角色选择音色广场或个人音色，其余角色可通过文字描述创建，在效果和创作效率之间取得平衡。   |

## 计费说明

请参考 [计费规则](/guides/account/billing)。

## 典型应用场景

### 播客与有声内容

适用于播客、有声书、广播剧和故事类内容。你可以通过多角色声音与连续对白快速生成完整音频，提升长内容的生产效率。

### 广告与品牌营销

适用于广告口播、品牌短片、宣传视频和信息流素材。你可以快速尝试不同角色、语气、情绪和声音方案，缩短从创意到成品的制作周期。

### 短视频与剧情内容创作

适用于剧情短视频、知识视频、AI 漫剧和解说内容。你可以一次生成多角色对白、情绪表达、背景音乐与环境音效，减少配音、找音效和后期混音的制作成本。

## 开始使用

<Steps>
  <Step title="描述创作内容">
    输入期望生成的角色、台词、情绪、背景音乐和环境音效，也可以从灵感模板开始创作。
  </Step>

  <Step title="添加参考音色">
    如有明确的角色声音需求，可从音色广场、个人音色中选择声音，或上传本地参考音频。最多支持添加 3 个参考音色。
  </Step>

  <Step title="生成并试听">
    提交生成任务，完成后试听生成结果。
  </Step>

  <Step title="下载或再次创作">
    下载满意的音频结果，或调整提示词和参考音色重新生成。历史作品可随时回听。
  </Step>
</Steps>


# 常见问题
Source: https://docs.senseaudio.cn/guides/faq/overview

SenseAudio 开放平台开发者常见问题解答

欢迎访问 SenseAudio 常见问题解答。我们整理了开发者在使用过程中最常遇到的问题。如果您的问题未在此列出，请通过 官方客服 或 **[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)** 联系我们的技术支持团队。

***

## 账号与鉴权

### 如何获取 API Key？

您可以在 **[SenseAudio API 平台](https://senseaudio.cn/api-platform/home)** 的 API 密钥页面创建和管理您的 API Key。

**重要提示**：

* API Key 是您调用接口的重要凭证，拥有该密钥即可消耗您的账户额度
* 请妥善保管，切勿将其提交到公开的代码仓库（如 GitHub）
* 不要在前端浏览器代码中直接暴露 API Key
* 建议定期轮换密钥以提高安全性

### API 调用返回 401 Unauthorized 错误

当您遇到 401 错误时，请按以下步骤排查：

1. **检查请求头格式**：确认请求头中包含正确的 Authorization 字段

   ```
   Authorization: Bearer $SENSEAUDIO_API_KEY
   ```

2. **验证 API Key 有效性**：
   * 检查 API Key 是否已过期
   * 确认 API Key 未被删除或禁用
   * 确保没有多余的空格或特殊字符

3. **检查账户状态**：确认您的账户余额充足且状态正常

### API Key 的权限范围是什么？

每个 API Key 具有以下权限：

* 调用所有已开放的 API 接口
* 访问您账户下的所有资源（音色、历史记录等）
* 消耗您的账户配额

如需更细粒度的权限控制，请联系我们的企业支持团队。

***

## 资源与配额

### 如何查看我的配额使用情况？

您可以在以下位置查看配额信息：

* **控制台首页**：显示当前余额和使用统计
* **调用日志**：查看详细的 API 调用记录和消耗明细
* **账单中心**：查看历史账单和消费趋势

### 如何获得更高的并发或调用额度？

SenseAudio 为不同规模的企业提供灵活的资源方案：

**标准方案**：适合中小规模应用

* 默认 QPS 限制
* 按量计费

**企业方案**：适合大规模生产环境

* 更高的 QPS 配额
* 专属技术支持
* 定制化 SLA 保障

如需升级，请联系商务团队：**[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)**

### 支持私有化部署吗？

支持。我们为对数据隐私有严格要求或需要内网部署的客户提供完整的私有化部署方案。

**私有化部署优势**：

* 数据完全本地化，满足合规要求
* 可定制化功能和性能配置
* 提供完整的技术支持和培训
* 支持离线环境运行

详情请通过邮件联系我们获取方案和报价。

***

## 功能使用

### 语音合成支持哪些语言？

目前支持以下语言：

* **中文**（普通话）
* **英语**
* **多语言混合**（如中英混读）

更多语言支持正在开发中，敬请期待。

### 如何选择合适的音色？

选择音色时可以考虑以下因素：

1. **应用场景**：客服、有声读物、广告配音等不同场景适合不同音色
2. **目标受众**：根据用户群体的年龄、性别、地域选择
3. **情感表达**：选择能够准确传达内容情感的音色
4. **试听对比**：在 **[系统音色列表](/guides/voice/catalog)** 中试听多个音色

### 生成的音频可以商用吗？

可以。您通过 SenseAudio API 生成的音频内容拥有完整的商业使用权，可用于：

* 商业广告
* 有声读物
* 视频配音
* 客服系统
* 其他合法商业用途

请确保您使用的文本内容本身不侵犯他人版权。

***

## 定制服务

### 如何定制专属的品牌音色？

我们提供专业级音色定制服务。

**服务内容**：

* **深度定制**：由专业录音师指导录制，打造广播级品质的专属音色
* **全风格适配**：根据品牌调性定制特定的情感、语速和风格
* **多语言支持**：支持中、英、日、韩等多语言混合定制
* **独占授权**：定制音色仅供您使用

**适用场景**：

* 企业品牌形象音色
* 虚拟主播/虚拟偶像
* 高端有声读物
* 品牌广告配音

如有需求，请发送邮件至 **[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)**。

***

## 技术支持

### 遇到技术问题如何反馈？

为了帮助我们更快地定位和解决问题，请在反馈时提供以下信息：

**必需信息**：

* **Request ID**：每次 API 调用返回的唯一标识符
* **错误信息**：完整的错误代码和错误描述
* **调用时间**：问题发生的具体时间（精确到分钟）

**建议提供**：

* 问题复现步骤
* 相关代码片段（请移除敏感信息）
* 请求和响应的完整内容
* 使用的编程语言和 SDK 版本

**联系方式**：

* 邮件：**[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)**
* 工单系统：登录控制台提交工单（企业用户）

### API 响应速度慢怎么办？

如果您遇到 API 响应缓慢的问题，可以尝试以下优化方法：

1. **使用流式输出**：对于长文本，使用 `stream: true` 参数可以更快获得首包响应
2. **选择合适的音频格式**：MP3 文件体积更小，下载传输更快；WAV 无损未压缩，编码更快
3. **检查网络环境**：确保您的服务器与 API 服务之间网络畅通
4. **分批处理**：将大量请求分批发送，避免瞬时高并发

如问题持续存在，请联系技术支持团队。

### 支持哪些开发语言和框架？

SenseAudio API 是标准的 RESTful API，支持所有能发起 HTTP 请求的编程语言，包括但不限于：

* **Python**（推荐使用 requests 库）
* **JavaScript/Node.js**（推荐使用 axios）
* **Go**
* **Java**
* **Swift**
* **PHP**
* **C#/.NET**
* **Ruby**

我们在文档中提供了主流语言的示例代码，您可以直接参考使用。


# 图片生成介绍
Source: https://docs.senseaudio.cn/guides/image/overview

图片生成能力总览

SenseAudio 图片生成服务面向海报设计、营销素材、电商主图、角色概念图等场景，提供统一的图片生成 API。开发者可以通过自然语言提示词快速生成图片，也可以配合参考图进行风格约束，满足从快速草图到高分辨率成品图的不同需求。

## 什么是图片生成

图片生成能力允许您通过文本描述直接生成图片内容。平台当前同时提供同步与异步两种调用方式：

* **同步生成**：适合对实时返回要求较高的场景，接口直接返回图片 URL。
* **异步生成**：适合更稳定的任务式处理流程，先创建任务，再轮询获取结果。
* **双模型支持**：同一套接口支持不同生成模型，方便在画质、尺寸和效率之间灵活取舍。
* **参考图输入**：支持传入参考图 URL 或 Data URI，对构图与风格进行约束。

## 核心特性

### 文本直出图片

只需提供 `prompt` 即可完成文生图，适合批量素材生成、概念草图探索和视觉创意验证。

### 多尺寸输出

不同模型支持不同尺寸，既可以满足常规海报、封面图需求，也可以覆盖高分辨率营销素材场景。

### 同步与异步双模式

您可以根据业务形态选择合适的调用方式：同步模式适合即时展示，异步模式更适合任务队列与后台批处理。

## 模型支持

| 模型                              | 特点                                                       | 适用场景                  |
| :------------------------------ | :------------------------------------------------------- | :-------------------- |
| **senseaudio-image-2.0-260319** | 自研图片生成最新版本，支持多种宽高比与高分辨率输出                                | 高清营销主图、社媒大图、宽屏视觉素材    |
| **senseaudio-image-1.0-260319** | 常规图片生成模型，覆盖主流横版、竖版和方图尺寸                                  | 常规营销图、封面图、内容配图        |
| **doubao-seedream-5-0-260128**  | 支持更大尺寸输出，更适合高分辨率生成                                       | 宣传海报、电商物料、精细大图        |
| **sensenova-u1-fast**           | 基于 SenseNova U1 的加速版本，理解与生成一体，面向信息图生成优化，擅长高密度信息表达与丰富版式排版 | 信息图表、PPT 页面、高密度视觉内容生成 |

## API 能力概览

SenseAudio 图片生成提供以下核心接口：

### 1. 异步图片生成

调用后返回 `task_id`，适合生成任务需要排队、轮询或后台处理的场景。

* 文档：**[异步图片生成](/api-reference/endpoint/image/async)**
* 接口地址：`POST https://api.senseaudio.cn/v1/image/async`

### 2. 异步图片获取

根据 `task_id` 查询任务状态与最终结果，适合与异步生成接口配合使用。

* 文档：**[异步图片获取](/api-reference/endpoint/image/pending)**
* 接口地址：`GET https://api.senseaudio.cn/v1/image/pending`

### 3. 同步图片生成

调用成功后直接返回图片 URL，适合需要即时展示生成结果的页面交互场景。

* 文档：**[同步图片生成](/api-reference/endpoint/image/sync)**
* 接口地址：`POST https://api.senseaudio.cn/v1/image/sync`

## 接口选择建议

| 场景            | 推荐接口                                  | 说明                             |
| :------------ | :------------------------------------ | :----------------------------- |
| 前端即时出图        | 同步图片生成                                | 调用简单，直接返回结果                    |
| 后台批量生成        | 异步图片生成 + 异步图片获取                       | 便于任务管理和轮询                      |
| 高清宽屏与多比例输出    | 同步或异步 + `senseaudio-image-2.0-260319` | 支持横版、竖版与超宽尺寸的高分辨率输出            |
| 高分辨率物料生成      | 同步或异步 + `doubao-seedream-5-0-260128`  | 支持更大尺寸输出                       |
| 常规内容配图        | 同步或异步 + `senseaudio-image-1.0-260319` | 兼顾效率与通用性                       |
| 信息图与 PPT 页面生成 | 同步或异步 + `sensenova-u1-fast`           | 专供信息图生成，适合高密度信息表达、图文排版和结构化视觉内容 |

## 计费说明

请参考 **[计费规则](/guides/account/billing)**。

## 典型应用场景

### 电商与营销设计

用于商品主图、活动海报、广告素材、社媒封面等高频视觉内容生产。

### 内容创作与媒体配图

用于文章插图、短视频封面、播客封面、专题视觉图等内容制作场景。

### 游戏与角色概念设计

用于角色设定图、世界观草图、场景概念图和风格探索阶段的创作提效。

## 开始使用

<Steps>
  <Step title="进入 API 密钥">
    进入 [API 密钥](https://senseaudio.cn/api-platform/api-key) 页面。
  </Step>

  <Step title="新增并保存 API Key">
    点击 **"新增 API Key"**，复制并安全保存您的 API Key。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="同步图片生成" icon="image" href="/api-reference/endpoint/image/sync">
    即时返回图片 URL，适合前端展示。
  </Card>

  <Card title="异步图片生成" icon="layer-group" href="/api-reference/endpoint/image/async">
    返回 `task_id`，适合后台批量生产。
  </Card>

  <Card title="异步图片获取" icon="clock" href="/api-reference/endpoint/image/pending">
    根据 `task_id` 查询任务状态与结果。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    查看图片生成的积分消耗规则。
  </Card>
</CardGroup>


# 文本生成介绍
Source: https://docs.senseaudio.cn/guides/llm/overview

SenseAudio 多模态理解接口能力总览

欢迎使用 SenseAudio 多模态理解接口服务。本服务对外提供标准化、高性能的模型调用能力，支持多模态理解、函数调用（Function Calling）以及流式响应，方便开发者快速将 AI 能力集成到各种业务场景中。

## 文本生成模型

SenseAudio 平台接入了多款业界领先的文本生成大模型，从低成本极速档到深度推理旗舰，您可以根据业务的成本、响应速度与智能需求灵活选择。

### 核心能力

文本模型支持以下核心能力：

* **多轮对话与上下文理解**：能够记忆历史对话，进行连贯的深度沟通。
* **函数调用 (Function Calling)**：模型可根据您的提问，智能决定是否调用外部工具（如查询天气、执行代码、检索数据库），并返回结构化参数。
* **多模态支持**：部分先进模型支持图片输入，可进行图文混合推理（如 OCR 提取、图像描述、视觉问答）。
* **流式输出 (Streaming)**：支持通过 Server-Sent Events (SSE) 协议逐字返回生成结果，显著降低首字延迟。

### 可用接口

* **[对话 (Chat) API](/api-reference/endpoint/llm/chat)** —— 兼容 OpenAI Chat Completions 格式，已有 OpenAI 代码可直接切换
* **[模型响应 (Responses) API](/api-reference/endpoint/llm/responses)** —— 兼容 OpenAI Responses 格式，支持结构化输入输出与更精细的生成控制
* **[消息 (Messages) API](/api-reference/endpoint/llm/messages)** —— 兼容 Anthropic Messages 格式，已有 Claude 代码可直接切换

### 鉴权方式

所有 LLM 接口均通过统一的 HTTP Header 进行鉴权：

```http theme={null}
Authorization: Bearer <Your_API_Key>
```

## 相关资源

<CardGroup>
  <Card title="快速接入" icon="rocket" href="/guides/account/quick-access">
    获取 API Key 并完成首个请求。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看平台支持的模型及其能力、上下文长度与计费信息。
  </Card>
</CardGroup>


# 音乐生成介绍
Source: https://docs.senseaudio.cn/guides/music/overview

歌词与歌曲一体化生成能力概览

SenseAudio 音乐生成服务面向歌词创作、歌曲生成、BGM 制作与内容配乐等场景，提供统一的音乐生成 API。开发者既可以先生成歌词，再生成歌曲，也可以直接基于提示词或结构化歌词创建完整音乐作品。

## 什么是音乐生成

音乐生成能力将歌词创作与歌曲生成打通为一条完整链路，适合从灵感草稿到成品音频的自动化工作流。

**核心能力**：

* **歌词生成**：根据给定的提示词快速生成结构化歌词内容
* **歌曲生成**：根据歌词或提示词生成完整歌曲
* **风格控制**：支持设置风格、负面标签、纯音乐、人声性别等参数
* **异步任务处理**：歌曲生成采用任务制，适合耗时较长的生成场景

## 主要特性

* **歌词与歌曲一体化**：先用歌词生成接口产出灵感草稿，再将结果直接交给歌曲生成接口完成成品制作。
* **结构化歌词输入**：歌曲接口支持 `[verse]`、`[chorus]`、`[bridge]` 等结构标签，便于对歌曲段落进行显式控制。
* **提示词与纯音乐模式**：除了标准歌词模式外，还支持直接基于提示词生成完整音乐，以及纯音乐模式，适合配乐、氛围音乐与 demo 创作。
* **任务式结果获取**：歌曲创建接口返回 `task_id`，可通过轮询接口获取生成状态和最终音频地址，便于接入任务中心或后台流程。

## 模型版本

当前音乐生成相关模块统一使用以下模型：

* `senseaudio-music-1.0-260319`
* `senseaudio-music-2.0-260626`

## API 能力概览

SenseAudio 音乐生成提供以下核心 API 接口：

### 1. 创建歌词生成任务

根据提示词生成歌词内容，适合灵感扩写、歌词草稿生成和创作辅助。

* 文档：**[创建歌词生成任务](/api-reference/endpoint/music/lyrics-create)**
* 接口地址：`POST https://api.senseaudio.cn/v1/music/lyrics/create`

### 2. 创建歌曲生成任务

根据歌词或提示词生成歌曲，当前提供两个版本：

* **V1**：兼容历史参数，文档：**[歌曲生成 V1](/api-reference/endpoint/music/song-create-v1)**，接口地址：`POST https://api.senseaudio.cn/v1/music/song/create`
* **V2**：使用结构化参数，文档：**[歌曲生成 V2](/api-reference/endpoint/music/song-create-v2)**，接口地址：`POST https://api.senseaudio.cn/v2/music/song/create`

### 3. 查询歌曲生成状态

根据 `task_id` 查询歌曲生成进度，并在成功后获取音频、封面和歌词结果。

* 文档：**[查询歌曲生成状态](/api-reference/endpoint/music/song-pending)**
* 接口地址：`GET https://api.senseaudio.cn/v1/music/song/pending/{task_id}`

## 参数选择建议

| 场景        | 推荐接口                | 说明                     |
| :-------- | :------------------ | :--------------------- |
| 歌词创意辅助    | 创建歌词生成任务            | 适合灵感发散和歌词草稿生成          |
| 直接生成完整歌曲  | 创建歌曲生成任务            | 适合快速出 demo 或完整音乐       |
| 生成纯音乐/BGM | 创建歌曲生成任务            | 配合 `instrumental` 参数使用 |
| 后台任务管理    | 创建歌曲生成任务 + 查询歌曲生成状态 | 适合异步工作流和任务中心           |

## 计费说明

请参考 **[计费规则](/guides/account/billing)**。

## 典型应用场景

### 短视频与自媒体配乐

快速生成适合视频节奏和情绪的歌曲或背景音乐，降低内容制作门槛。

### 品牌营销与活动主题曲

为品牌活动、宣传片或产品发布会快速生成定制化音乐素材。

### 创作辅助与灵感验证

帮助音乐创作者、策划和编剧快速验证旋律走向、音乐氛围与歌词方向，提升前期创作效率。

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 创建您的 API Key。
  </Step>

  <Step title="生成歌词草稿">
    输入创作意图，调用 [创建歌词生成任务](/api-reference/endpoint/music/lyrics-create) 获取灵感草稿；可对歌词进行筛选或微调，确认最终文本。
  </Step>

  <Step title="创建歌曲任务">
    根据接入版本选择 [歌曲生成 V1](/api-reference/endpoint/music/song-create-v1) 或 [歌曲生成 V2](/api-reference/endpoint/music/song-create-v2) 提交歌曲生成任务，获取 `task_id`。
  </Step>

  <Step title="轮询并获取结果">
    通过 [查询歌曲生成状态](/api-reference/endpoint/music/song-pending) 轮询任务，获取最终歌曲、封面与歌词。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="歌词生成 API" icon="pen-line" href="/api-reference/endpoint/music/lyrics-create">
    根据提示词生成结构化歌词内容。
  </Card>

  <Card title="歌曲生成 V2" icon="music" href="/api-reference/endpoint/music/song-create-v2">
    基于结构化参数创建完整歌曲任务。
  </Card>

  <Card title="歌曲状态查询" icon="clock" href="/api-reference/endpoint/music/song-pending">
    根据 `task_id` 轮询歌曲生成结果。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    查看音乐生成的积分消耗规则。
  </Card>
</CardGroup>


# 音效生成介绍
Source: https://docs.senseaudio.cn/guides/sfx/overview

根据文本描述快速生成音效素材

SenseAudio 音效生成服务面向短视频、影视、动画、游戏、有声内容、广告和产品演示等场景，提供统一的文生音效 API。开发者只需传入清晰具体的声音描述，即可快速生成对应的音效素材，减少素材检索、现场录制和前期试音成本。

## 什么是音效生成

音效生成能力将自然语言中的声音描述转换为短音频素材，适合从声音创意到内容配音素材的自动化工作流。

**核心能力**：

* **文生音效**：根据文字描述生成事件声、动作声或环境声
* **时长控制**：支持固定时长，也支持由模型根据提示词自动决定时长
* **多结果生成**：支持一次生成多个候选结果，便于后续筛选和使用
* **格式选择**：支持按业务需求选择 `mp3` 或 `wav` 输出格式

## 主要特性

* **一句话生成**：用简单描述即可完成音效创作，不依赖专业录音设备或复杂编辑流程。
* **输入更直接**：优先使用具体声源名称或声音事件，而不是抽象形容词，便于获得稳定结果。
* **降低准备成本**：减少素材搜索、现场录制和反复试音等前期工作。
* **适配多种内容**：可用于视频、游戏、广告和产品演示等内容制作场景。

## 模型版本

当前音效生成相关模块统一使用以下模型：

* `senseaudio-sfx-1.0-260626`

## API 能力概览

SenseAudio 音效生成提供以下核心 API 接口：

### 1. 创建音效生成任务

根据文本描述同步生成 1-4 个音效变体，适合事件声、动作声、环境声和产品演示音效等素材生成场景。

* 文档：**[音效生成](/api-reference/endpoint/sfx/create)**
* 接口地址：`POST https://api.senseaudio.cn/v1/sound-effects/generations`

## 提示词写法建议

输入明确、具体的声音名称通常就能获得良好效果。

推荐：

* 使用具体声源名称或声音事件，如脚步声、关门声、玻璃碎裂声。
* 表述尽量简单、直接，一次描述一种主要声音。

避免只写抽象描述的声音。

| 想要的声音 | 推荐描述  | 不建议只写 |
| :---- | :---- | :---- |
| 黑板敲击  | 黑板敲击声 | 课堂转场  |
| 下雨    | 下雨声   | 氛围感   |
| 玻璃碎裂  | 玻璃碎裂声 | 高级音效  |

## 参数选择建议

| 场景        | 推荐参数     | 说明                        |
| :-------- | :------- | :------------------------ |
| 常规音效生成    | 创建音效生成任务 | 输入明确、具体的声音描述，生成相应音效       |
| 多候选结果生成   | 创建音效生成任务 | 默认一次生成 4 条候选结果，便于筛选       |
| 定长或自动时长生成 | 创建音效生成任务 | 可指定音效时长，也可由模型自动判断         |
| 指定音频格式    | 创建音效生成任务 | 根据业务需求选择 `mp3` 或 `wav` 格式 |

## 计费说明

请参考 **[计费规则](/guides/account/billing#音效生成)**。

## 典型应用场景

### 短视频与影视制作

为短视频、动画和短剧快速补充动作声、拟音和环境声，让画面反馈更加清晰。

### 游戏与互动体验

为界面反馈、角色动作、道具交互和环境事件探索声音方案。

### 广告与产品演示

为包装拆封、瓶盖开启、液体倾倒、旋钮转动和设备启动等画面补充声音。

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 创建您的 API Key。
  </Step>

  <Step title="描述目标声音">
    输入清晰具体的声音描述，例如“玻璃碎裂声”“雨打窗户声”或“按钮点击反馈音”。
  </Step>

  <Step title="创建音效任务">
    调用 [音效生成](/api-reference/endpoint/sfx/create) 接口，按需设置 `variants_count`、`duration_seconds`、`smart_duration` 和 `output_format`。
  </Step>

  <Step title="获取生成结果">
    请求完成后直接获取生成结果，并从候选音效中选择适合业务场景的版本。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="音效生成 API" icon="file-audio" href="/api-reference/endpoint/sfx/create">
    根据文本描述同步生成 1-4 个音效变体。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看音效生成模型和价格信息。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    查看音效生成的积分消耗规则。
  </Card>
</CardGroup>


# 同声传译介绍
Source: https://docs.senseaudio.cn/guides/simultaneous-interpretation/overview

实时语音识别、翻译与译文播报能力概览

SenseAudio 同声传译服务面向跨语言会议、实时交流、直播与国际活动等场景，提供实时语音识别、翻译与译文播报能力。服务支持源语言自动识别，并可在同传过程中同步查看原文与译文。

## 什么是同声传译

同声传译能力将语音识别、实时翻译与语音播报整合为一条完整链路。你可以在讲话过程中持续获取原文和译文，并按需实时播报翻译结果。

当前支持 **11 种语言**：中文、英语、日语、韩语、粤语、德语、法语、西班牙语、葡萄牙语、意大利语和俄语。

## 核心能力

* **实时识别与翻译**：持续接收语音并实时生成原文与译文。
* **源语言自动识别**：支持自动识别输入语言，减少开始前配置。
* **实时译文播报**：支持将译文实时转换为语音，并提供男声、女声两种预制音色。
* **同传结果留存**：结束后支持单条译文回听，并可下载原文与译文文本。

## 主要特性

* **原文与译文同步展示**：同传过程中实时查看识别原文与对应译文，便于理解和核对。
* **实时译文播报**：开启播报后，译文可同步转换为语音播放，并支持男声、女声两种预制音色。
* **语音降噪**：支持对输入语音进行降噪处理，适用于会议、活动现场等存在环境噪声的场景。
* **结果回听与下载**：同传结束后可逐条回听译文，并下载翻译前后的文本内容。
* **断网重连**：网络短暂中断后支持重新连接，降低网络波动对使用过程的影响。

## 模型版本

当前同声传译模块使用以下模型：`sensenova-livetranslate-1.0`。

## API 能力概览

SenseAudio 同声传译提供基于 WebSocket 的实时接口。建立 WebSocket 连接后，你可以持续发送实时音频，服务端会流式返回识别原文、译文以及可选的译文语音。

接口地址：`GET wss://api.senseaudio.cn/ws/v1/audio/simulat-interpreting`

## 参数选择建议

| 场景     | 推荐配置       | 说明             |
| :----- | :--------- | :------------- |
| 源语言不确定 | 自动识别源语言    | 减少开始同传前的配置     |
| 固定语言交流 | 指定源语言与目标语言 | 适合语言明确的会议或交流场景 |
| 环境较嘈杂  | 开启降噪       | 提升复杂环境下的语音输入质量 |
| 需要语音播报 | 开启译文播报     | 可选择男声或女声预制音色   |

## 典型应用场景

### 跨语言会议与商务沟通

实时生成原文与译文，并通过译文播报帮助不同语言的参与者同步理解会议内容。

### 国际活动与现场交流

适用于论坛、发布会、展会等场景，为现场讲话提供实时跨语言翻译。

### 直播与实时内容

为访谈、直播和在线内容实时生成双语文本及译文语音，提升跨语言内容触达效率。

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 创建你的 API Key。
  </Step>

  <Step title="配置同传语言">
    选择目标语言，源语言可指定或使用自动识别。
  </Step>

  <Step title="建立同传连接">
    通过 WebSocket 创建同声传译任务，并持续发送实时音频。
  </Step>

  <Step title="获取同传结果">
    实时接收原文、译文以及可选的译文语音，结束后可进一步保存或处理同传结果。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看同声传译模型与其他可调用模型。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    查看同声传译按时长计费规则。
  </Card>
</CardGroup>


# S系列 使用技巧
Source: https://docs.senseaudio.cn/guides/token-plan/best-practices

掌握 S系列 的高效 Prompt 与长任务执行模式

**S 系列** 是 SenseAudio 旗舰多模态模型组合，覆盖 **S2 / S2-Lite / S2-Flash** **S2系列**三档和**多模态系列**：本文以通用旗舰 **S2**（`senseaudio-s2`）为主介绍。以下是从实际使用中总结的最佳实践。

## 一、任务输入四要素：GCCV 框架

与 Agent 协作，把它当作一位刚入职的资深工程师——你要把**目标、上下文、约束、验收**都讲清，它才能独立推进长任务。推荐用 **GCCV** 框架组织每一次复杂任务的开场白：

| 要素                 | 要回答的问题                | 示例                                                  |
| ------------------ | --------------------- | --------------------------------------------------- |
| **Goal（目标）**       | 我想达成什么最终结果？           | "把 `/api/orders` 接口从同步改造为异步批处理"                     |
| **Context（上下文）**   | Agent 需要了解哪些背景、代码、数据？ | "订单量峰值 5000 QPS，现有实现是 Flask 同步处理；数据库见 `schema.sql`" |
| **Constraint（约束）** | 有哪些边界与禁区？             | "不得引入新的消息队列依赖；必须向后兼容现有客户端"                          |
| **Validation（验收）** | 怎么判断做完了？              | "`pytest tests/orders/` 全过；在压测脚本下 p99 \< 200ms"     |

<Tip>
  一开始就把 GCCV 讲完整，通常能减少 50% 以上的来回澄清轮次，也能更省 Token Plan 额度。
</Tip>

***

## 二、指令需明确清楚

S2 对清晰明确的指令响应更好。请显式说明期望的**输出格式、内容、风格**。

<AccordionGroup>
  <Accordion title="示例：创建一个可视化网站">
    **❌ 效果欠佳**

    ```
    创建一个可视化网站
    ```

    **🚀 效果更佳**

    ```
    创建一个企业级数据可视化网站，整合尽可能丰富的分析特性和交互功能，
    超越基础展示形式，包含筛选、联动、导出、暗色主题切换等。
    ```
  </Accordion>
</AccordionGroup>

***

## 三、补充指令意图以提升性能

向 S2 说明**为什么**。模型理解目的后能更精准地输出结果。

<AccordionGroup>
  <Accordion title="示例：不要使用文档符号">
    **❌ 效果欠佳**

    ```
    禁止使用文档符号
    ```

    **🚀 效果更佳**

    ```
    您的回复将由语音合成模型朗读，因此请以纯文本形式呈现，
    避免使用 Markdown 标题、列表、代码块等文档符号。
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  S2 会"举一反三"——说清楚前因后果，它就能顺着您的思路推理。
</Tip>

***

## 四、注重举例和细节

想让模型做成什么样，就给一个"样板"示例；担心它犯什么错，就**明确说出来别让它做**。

<AccordionGroup>
  <Accordion title="示例：写一段吸引人的产品介绍">
    **❌ 效果欠佳**

    ```
    写一段吸引人的产品介绍，主题是智能保温杯。
    ```

    **🚀 效果更佳**

    ```
    请参照这个例子来写产品介绍：

    【好的例子：这款台灯采用全光谱 LED 技术，能模拟清晨的自然光，
    温柔唤醒您的一天。它具备 6 级亮度调节，满足阅读、工作和休息的不同需求。】

    请避免下面这样空洞的描述：

    【不好的例子：这个台灯很好用，灯光很舒服，设计也很棒。】

    现在，请为"智能保温杯"写一段介绍。
    ```
  </Accordion>
</AccordionGroup>

***

## 五、善用多模态输入

S系列 原生支持图文混合输入。在调试 UI、Review 设计稿、OCR、图表理解时，直接把截图塞给它：

```python theme={null}
resp = client.chat.completions.create(
    model="senseaudio-vl-1.0-260319",
    messages=[
        {"role": "user", "content": [
            {"type": "text", "text": "分析下面这张运营数据截图，指出异常点和改进建议。"},
            {"type": "image_url", "image_url": {"url": "https://example.com/dashboard.png"}},
        ]},
    ],
)
```

***

## 六、长任务推理与状态跟踪

S2 具备稳健的状态追踪机制，**聚焦有限目标而非全量并行**，从而在长任务中保持思维连贯。

### 单窗口上下文感知

模型内置上下文感知。**但当**使用支持上下文压缩的工具（如 Claude Code）时，请控制 System Prompt 的 token 数量——临近上下文阈值时，模型可能出现任务提前终止。

### 多窗口工作流

<Steps>
  <Step title="分阶段处理">
    第一个窗口搭框架（编写、测试、创建脚本），第二个窗口遍历待办项。
  </Step>

  <Step title="结构化测试">
    让模型创建 `tests.py` / `tests.json` 跟踪测试结果，方便长期迭代。
  </Step>

  <Step title="初始化脚本">
    让模型写一个 `init.sh` 启动服务 / 运行测试，避免每开新窗口都重复交代。
  </Step>

  <Step title="压缩 vs 重启">
    单一任务延续用压缩；切换到新任务建议开全新窗口。
  </Step>

  <Step title="充分利用上下文">
    提示模型在继续前高效完成当前部分，避免中途 token 耗尽。
  </Step>
</Steps>

**推荐 System Prompt：**

```
这是一项非常冗长的任务。请充分利用完整的输出上下文来处理——
整体输入与输出 tokens 控制在 200k 以内，
充分利用上下文窗口长度，把任务彻底完成，避免耗尽 tokens。
```

***

## 七、模型档位组合

* **S2**（`senseaudio-s2`）：通用旗舰，平衡能力与成本，覆盖大多数日常编程与分析任务。
* **S2-Lite**（`senseaudio-s2-lite`）：高吞吐轻量版，响应更快，适合工具调用 / 代码补全 / 子 Agent 节点。
* **S2-Flash**（`senseaudio-s2-flash`）：极速低延迟通道，适合海量简单任务与大规模吞吐。

在 Agent 框架中把主模型设为 S2，子任务与小工具调用设为 S2-Lite / S2-Flash，是兼顾质量与成本的常用组合。

## 相关资源

<CardGroup>
  <Card title="接入 Claude Code" icon="wand-magic-sparkles" href="/guides/token-plan/claude-code" />

  <Card title="Hermes Agent" icon="robot" href="/guides/token-plan/hermes-agent" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Claude Code
Source: https://docs.senseaudio.cn/guides/token-plan/claude-code

在 Claude Code 中接入Token Plan 进行 AI 编程。

## 概述

[Claude Code](https://docs.claude.com/en/docs/claude-code) 是 Anthropic 官方推出的终端内 AI 编程助手，通过自然语言交互帮助开发者更快地编写、调试和管理代码。本文将指导你把 SenseAudio [Token Plan](https://senseaudio.cn/tokenplan) 接入 Claude Code，直接在熟悉的 CLI 中调用 Claude 模型。

<CardGroup>
  <Card title="终端原生体验" icon="terminal">
    无需切换窗口，直接在命令行中完成编码、调试与重构。
  </Card>

  <Card title="多模型灵活切换" icon="arrows-repeat">
    支持 Sonnet、Opus、Haiku 全系列，按场景选择最合适的模型。
  </Card>

  <Card title="项目上下文感知" icon="folder-tree">
    自动读取工作目录文件，理解项目结构后再给出建议。
  </Card>

  <Card title="安全受控执行" icon="shield-check">
    首次访问需手动信任文件夹，避免误操作本地代码。
  </Card>
</CardGroup>

## 前提条件

<Check>已订阅 SenseAudio [Token Plan](https://senseaudio.cn/tokenplan)</Check>
<Check>已安装 [Node.js 18 或更新版本](https://nodejs.org/en/download/)</Check>
<Check>Windows 用户需额外安装 [Git for Windows](https://git-scm.com/install/windows)</Check>

## 安装 Claude Code

<Steps>
  <Step title="一键安装">
    在终端中执行以下命令：

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="验证安装">
    执行以下命令查看版本信息，若正常输出版本号则表示安装成功：

    ```bash theme={null}
    claude --version
    ```
  </Step>
</Steps>

<Note>
  更多安装细节与进阶用法请参考 [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/setup)。
</Note>

## 配置 Token Plan

Claude Code 通过读取环境变量与本地配置文件接入 SenseAudio Token Plan，无需修改任何代码。

<Steps>
  <Step title="配置环境变量">
    从控制台 [API Key 管理](https://senseaudio.cn/api-platform/api-key) 获取你的 **Token Plan API Key**，然后根据操作系统选择对应配置方式。

    <Tabs>
      <Tab title="macOS / Linux">
        将以下内容追加到 `~/.zshrc`（zsh 用户）或 `~/.bashrc`（bash 用户）：

        ```bash theme={null}
        export ANTHROPIC_BASE_URL="https://api.senseaudio.cn"
        export ANTHROPIC_AUTH_TOKEN="<your-api-key>"
        export ANTHROPIC_API_KEY="<your-api-key>"
        ```

        保存后执行以下命令使配置生效（或重新打开终端）：

        ```bash theme={null}
        source ~/.zshrc   # zsh 用户
        source ~/.bashrc  # bash 用户
        ```
      </Tab>

      <Tab title="Windows">
        按 `Win + R`，输入 `sysdm.cpl` 回车，依次点击 **高级** → **环境变量**，在 **用户变量** 区域点击 **新建**，依次添加：

        | 变量名                    | 变量值                         |
        | ---------------------- | --------------------------- |
        | `ANTHROPIC_BASE_URL`   | `https://api.senseaudio.cn` |
        | `ANTHROPIC_AUTH_TOKEN` | `<your-api-key>`            |
        | `ANTHROPIC_API_KEY`    | `<your-api-key>`            |

        添加完成后，重新打开终端使配置生效。
      </Tab>
    </Tabs>
  </Step>

  <Step title="编辑或创建 Claude Code 的配置文件">
    * **macOS / Linux**：`~/.claude/settings.json`
    * **Windows**：`用户目录/.claude/settings.json`

    将下方配置中 `ANTHROPIC_AUTH_TOKEN` 的值替换为你的 SenseAudio API Key。
    环境变量 `ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_BASE_URL` 的优先级高于配置文件。

    ```json theme={null}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.senseaudio.cn",
        "ANTHROPIC_AUTH_TOKEN": "SENSEAUDIO_API_KEY",
        "API_TIMEOUT_MS": "3000000",
        "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
        "ANTHROPIC_MODEL": "senseaudio-s2",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "senseaudio-s2",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "senseaudio-s2",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "senseaudio-s2"
      }
    }
    ```
  </Step>

  <Step title="跳过 Onboarding">
    编辑或新建 `.claude.json` 文件，将 `hasCompletedOnboarding` 字段设置为 `true`，可跳过首次启动时的引导流程。

    * **macOS / Linux**：`~/.claude.json`
    * **Windows**：`C:\Users\<用户名>\.claude.json`

    ```json theme={null}
    {
        "hasCompletedOnboarding": true
    }
    ```
  </Step>
</Steps>

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

## 开始使用

配置完成后，进入项目目录并执行 `claude` 命令即可启动 Claude Code：

```bash theme={null}
cd my-project
claude
```

启动后选择 **信任此文件夹 (Trust This Folder)**，允许 Claude Code 访问该目录下的文件。

<Frame>
  <img alt="信任此文件夹" />
</Frame>

进入交互界面后，可通过以下命令管理会话：

* `/status` —— 查看当前模型与 API 地址，确认配置生效
* `/model` —— 切换模型（Opus / Sonnet / Haiku 三档均映射为 `senseaudio-s2`）
* 直接输入自然语言任务，例如 "帮我重构这个模块的错误处理逻辑"

## 相关资源

<CardGroup>
  <Card title="Hermes Agent" icon="robot" href="/guides/token-plan/hermes-agent">
    接入开源自主 AI 智能体
  </Card>

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    发挥 S2 模型最佳效果
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Cline
Source: https://docs.senseaudio.cn/guides/token-plan/cline

在 Cline 中使用 S2 模型进行 AI 编程

## 安装 Cline

<Steps>
  <Step title="打开扩展面板">
    在 VS Code 左侧活动栏点击 **扩展** 图标（或按下 `Cmd/Ctrl+Shift+X`）。
  </Step>

  <Step title="搜索并安装">
    在搜索框中输入 `Cline`，在结果中点击 **Install**。安装完成后建议重启一次 VS Code。
  </Step>
</Steps>

<Frame>
  <img alt="在 VS Code 扩展市场搜索并安装 Cline" />
</Frame>

完成安装后，左侧活动栏会出现 **Cline** 图标。

<Frame>
  <img alt="VS Code 左侧活动栏出现 Cline 图标" />
</Frame>

<Warning>
  若已安装旧版 Cline，请升级至 **3.79.0 或更高版本**，并重启 VS Code 以确保正常使用。
</Warning>

## 配置 SenseAudio API

<Steps>
  <Step title="打开配置">
    选择 **Bring my own API key**（自带 API 密钥），点击 **Continue**，进入参数配置界面。

    <Frame>
      <img alt="打开 Cline API 配置" />
    </Frame>
  </Step>

  <Step title="填写 Provider 信息">
    按下表填写 Provider 参数：

    <div>
      <div>配置项</div>
      <div>值</div>

      <div>API Provider</div>
      <div><code>OpenAI Compatible</code></div>

      <div>Base URL</div>


      <div>API Key</div>
      <div><code>您的 Token Plan API Key</code></div>

      <div>Model ID</div>
      <div><code>senseaudio-s2</code></div>
    </div>

    <Note>
      API Key 可在 [快速接入](/guides/token-plan/quickstart) 中获取。
    </Note>

    填写完成后，点击下方 **Continue** 保存。

    <Frame>
      <img alt="填写 Cline Provider 参数" />
    </Frame>
  </Step>

  <Step title="关闭保存后的弹窗">
    保存后弹出的提示窗口直接关闭即可。

    <Frame>
      <img alt="关闭保存后弹出的窗口" />
    </Frame>
  </Step>

  <Step title="开始使用">
    返回 Cline 主面板，即可用 S2 模型处理编码任务。

    <Frame>
      <img alt="Cline 主面板开始对话" />
    </Frame>
  </Step>
</Steps>

<Tip>
  **模型选择建议**：复杂重构或架构设计可切换到 `senseaudio-s2`（S2，深度推理）；日常通用任务使用 `senseaudio-s2-flash`（S2-Flash）；高频简单任务使用 `senseaudio-s2-lite`（S2-Lite）可获得更快的响应速度。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Roo Code" icon="rocket" href="/guides/token-plan/roo-code">
    开源的 VS Code AI 编程扩展
  </Card>

  <Card title="Kilo Code" icon="zap" href="/guides/token-plan/kilo-code">
    轻量级 VS Code AI 编程扩展
  </Card>

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    发挥 S2 模型最佳效果
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Codex CLI
Source: https://docs.senseaudio.cn/guides/token-plan/codex-cli

在 Codex CLI 中使用 S2 模型进行 AI 编程

## 安装 Codex CLI

如果你的设备尚未安装 Node.js，请先安装 Node.js 18 及以上版本，再执行以下命令安装 Codex CLI。

你可以访问官网安装，也可以通过命令安装：

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node
  ```

  ```bash Ubuntu / Debian theme={null}
  sudo apt update && sudo apt install -y nodejs npm
  ```

  ```powershell Windows (winget) theme={null}
  winget install OpenJS.NodeJS.LTS
  ```
</CodeGroup>

如果你更习惯图形界面安装，也可以访问：

<CodeGroup>
  ```bash macOS / Linux - 安装 Node.js theme={null}
  https://nodejs.org/
  ```

  ```powershell Windows - 安装 Node.js theme={null}
  https://nodejs.org/
  ```
</CodeGroup>

安装完成后，执行以下命令安装 Codex CLI：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  npm install -g @openai/codex@latest
  ```

  ```powershell Windows theme={null}
  npm install -g @openai/codex@latest
  ```
</CodeGroup>

<Note>
  更多安装细节与进阶用法请参考 [ codex 官方文档](https://developers.openai.com/codex)。
</Note>

## 配置 SenseAudio API

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

<Steps>
  <Step title="配置 API Key">
    根据你的系统编辑对应位置的 `auth.json`，填入你的 SenseAudio API Key：

    <CodeGroup>
      ```txt macOS / Linux theme={null}
      ~/.codex/auth.json
      ```

      ```txt Windows theme={null}
      %USERPROFILE%\\.codex\\auth.json
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "OPENAI_API_KEY": "<SENSEAUDIO_API_KEY>"
    }
    ```
  </Step>

  <Step title="编辑配置文件">
    根据你的系统编辑对应位置的 `config.toml`：

    <CodeGroup>
      ```txt macOS / Linux theme={null}
      ~/.codex/config.toml
      ```

      ```txt Windows theme={null}
      %USERPROFILE%\\.codex\\config.toml
      ```
    </CodeGroup>

    ```toml theme={null}
    model_provider = "senseaudio"
    model = "senseaudio-s2"
    model_reasoning_effort = "xhigh"
    disable_response_storage = true
    trust_level = "trusted"

    [model_providers.senseaudio]
    name = "senseaudio"
    base_url = "https://api.senseaudio.cn/v1"
    wire_api = "responses"
    requires_openai_auth = true
    ```
  </Step>

  <Step title="启动 Codex CLI">
    <CodeGroup>
      ```bash macOS / Linux theme={null}
      codex
      ```

      ```powershell Windows theme={null}
      codex
      ```
    </CodeGroup>
  </Step>
</Steps>

运行效果如下：

<img />

<Tip>
  Codex CLI 会从 `auth.json` 中读取 `OPENAI_API_KEY`，并按 `config.toml` 中的 `base_url` 和 `wire_api = "responses"` 转发到 SenseAudio 接口。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="Cursor" icon="mouse-pointer" href="/guides/token-plan/cursor" />

  <Card title="Grok CLI" icon="terminal" href="/guides/token-plan/grok-cli" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# 常见工作流
Source: https://docs.senseaudio.cn/guides/token-plan/common-workflows

面向真实开发场景的 Step-by-Step 任务模板，帮你把 Agent 用熟

以下工作流的思路适用于任何 Agent 工具（Claude Code / Cursor / Cline 等），均已在 **S2**（`senseaudio-s2`）上验证，请按您使用的工具对应调整具体操作。

***

## 工作流 1：快速理解陌生代码库

**适用场景**：刚加入新项目 / 接手遗留系统 / 评审第三方仓库。

<Steps>
  <Step title="让 Agent 画一张架构图（文字版）">
    ```
    请阅读当前仓库，产出一份 200 字以内的总览：核心模块、关键入口文件、主要依赖、
    可能的技术债。
    ```
  </Step>

  <Step title="锁定核心路径">
    ```
    基于上一步的总览，请列出「新功能开发时最常被改动的 5 个文件」，并解释原因。
    ```
  </Step>

  <Step title="沉淀到项目记忆">
    让 Agent 把上两步结论写入 `CLAUDE.md` / `AGENTS.md` / `SENSEAUDIO.md`，后续所有会话自动继承。
  </Step>

  <Step title="（可选）语音播报">
    调用 [`sensenova-tts-2.0`](/guides/tts/overview) 把总览朗读成音频，通勤路上也能复习。
  </Step>
</Steps>

***

## 工作流 2：Bug 定位与修复

<Steps>
  <Step title="给出 GCCV 开场白">
    明确报错信息（Goal：恢复 `/checkout` 接口可用）、相关文件（Context：`error.log` + `checkout/handler.py`）、禁改范围（Constraint：不改 DB schema）、验收标准（Validation：回归测试全过）。
  </Step>

  <Step title="让 Agent 先复现，再定位">
    ```
    先在本地复现该报错；复现成功后停下，告诉我最可能的根因，再让我决定是否修复。
    ```

    这一步强制 Agent 把**复现 → 假设 → 修复**三步拆开，避免盲目修改。
  </Step>

  <Step title="修复并跑测试">
    让 Agent 给出最小 diff，运行单测与回归用例，打印通过情况。
  </Step>

  <Step title="写回 CHANGELOG">
    完成后，让 Agent 把根因、修复要点、影响范围补充到 CHANGELOG。
  </Step>
</Steps>

***

## 工作流 3：从需求口述到代码落地（语音驱动开发）

这是 SenseAudio Token Plan 的独特玩法，其他同类 Coding Plan 不提供。

<Steps>
  <Step title="口述需求">
    打开支持 ASR 的前端（或你自己的小脚本），调用 [`senseaudio-asr-1.5-260319`](/guides/asr/overview) 把口述转写为文字。
  </Step>

  <Step title="LLM 整理为 GCCV">
    把转写结果扔给 S2：

    ```
    以下是一段口述需求，请整理成 Goal / Context / Constraint / Validation 四段式，
    如有不清楚的假设请先标出不要替我决定。
    ```
  </Step>

  <Step title="确认后交给 Agent 执行">
    把整理后的开场白粘贴进任意 Agent 工具，进入常规编码流程。
  </Step>
</Steps>

***

## 工作流 4：生成可对外展示的交付物

适用场景：PR 描述、周报、客户演示、内部分享。

<Steps>
  <Step title="代码讲解文稿">
    让 S2 基于 diff 产出 3 段讲解稿（技术视角 / 产品视角 / 风险视角）。
  </Step>

  <Step title="配图">
    把关键架构变化写成 prompt，调用 [`senseaudio-image-2.0-260319`](/guides/image/overview) 出一张示意图。
  </Step>

  <Step title="视频演示">
    用 [`doubao-seedance-2-0-260128`](/guides/video/overview) 基于一张截图 + 一段文案生成 15 秒演示片段。
  </Step>

  <Step title="配音">
    把讲解稿用 [`sensenova-tts-2.0`](/guides/tts/overview) 合成旁白音频。
  </Step>
</Steps>

<Tip>
  以上四步全部走 Token Plan 额度，无需额外账户，也无需跨平台接入。
</Tip>

***

## 工作流 5：长任务的断点续传

当任务跨越多个 Agent 会话时，推荐：

<Steps>
  <Step title="结构化 TODO 文件">
    让 Agent 维护 `PROGRESS.md`，按 `✅ / ⏳ / ⬜` 打点，每轮开始前先读它。
  </Step>

  <Step title="结束前写 handoff 备忘">
    ```
    在你停下前，请在 PROGRESS.md 追加一段 20 字以内的 handoff：
    下一轮应从哪一步开始、上下文要点、潜在坑。
    ```
  </Step>

  <Step title="新会话只读 handoff">
    新开会话时不必从头交代，直接 "阅读 PROGRESS.md 末段 handoff，继续推进"。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="Agent 工作原理" icon="microchip" href="/guides/token-plan/how-agent-works" />

  <Card title="S系列 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />
</CardGroup>


# Cursor
Source: https://docs.senseaudio.cn/guides/token-plan/cursor

在 Cursor 中使用 S2 模型进行 AI 编程

## 安装 Cursor

1. 前往 [Cursor 官网](https://cursor.com/) 下载并安装。
2. 打开 Cursor，右上角 **设置**，点击 **Sign in** 登录 Cursor 账户。

<img alt="Cursor Sign in" />

## 配置 SenseAudio API

<Warning>
  **配置前请清除以下 OpenAI 相关环境变量**，避免冲突：

  * `OPENAI_API_KEY`
  * `OPENAI_BASE_URL`
</Warning>

<Steps>
  <Step title="进入模型设置">
    点击左侧栏 **Models**，进入模型配置页面。
  </Step>

  <Step title="配置 API Key">
    展开 **API Keys**：

    * 勾选 **Override OpenAI Base URL**
    * 下方输入 SenseAudio 调用地址：`https://api.senseaudio.cn/v1`
    * **OpenAI API Key** 输入 Token Plan API Key
    * 点击 **OpenAI API Key** 栏右侧按钮

      <img alt="API Key 配置" />

    在弹窗中点击 **Enable OpenAI API Key** 完成验证。

    <img alt="Enable API Key" />
  </Step>

  <Step title="添加自定义模型">
    在 **Models** 面板点击 **View All Models** → **Add Custom Model**：

    <img alt="Add Custom Model" />

    输入模型名称 `senseaudio-s2`，点击 **Add**。

    <img alt="输入模型名" />
  </Step>

  <Step title="启用并使用">
    启用刚添加的模型，在聊天面板中选择 `senseaudio-s2` 即可开始使用。

    <img />
  </Step>
</Steps>

<Note>
  如模型没有返回任何内容，可尝试将 Cursor 的 **Network** 设置改为 **HTTP/1.0** 解决。

  <img />
</Note>

## 相关资源

<CardGroup>
  <Card title="Claude Code 接入" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Droid
Source: https://docs.senseaudio.cn/guides/token-plan/droid

在 Droid 中使用 S系列 模型进行 AI 编程

## 安装 Droid

**macOS / Linux：**

```bash theme={null}
curl -fsSL https://app.factory.ai/cli | sh
```

**Windows：**

```powershell theme={null}
irm https://app.factory.ai/cli/windows | iex
```

更多信息请参考 [Droid 文档](https://docs.factory.ai/cli/getting-started/quickstart)。

## 配置 SenseAudio API

<Steps>
  <Step title="更新 Droid 配置">
    编辑 `~/.factory/settings.json`：

    ```json theme={null}
    {
      "customModels": [
        {
          "model": "senseaudio-s2",// s系列模型
          "displayName": "SenseAudio",// 自定义的模型名称
          "baseUrl": "https://api.senseaudio.cn/v1",// base_url
          "apiKey": "<SENSEAUDIO_API_KEY>",//你的apiKey
          "maxOutputTokens": 64000,
          "provider": "openai"
        }
      ]
    }
    ```
  </Step>

  <Step title="启动 Droid">
    ```bash theme={null}
    cd /path/to/your/project
    droid
    ```
  </Step>

  <Step title="登录 Droid">
    选择 `Login` -> 回车

    <img />

    若未注册，请先注册（国内邮箱如 QQ 等可能无法注册）。注册完成则登录。

    <img />

    登录成功会显示下面 code，点击确认则会显示"设置完成"。若提示失败，则重新登录再到这个页面即可（code 过期）。

    <img />

    <img />

    点击 `LOGIN`

    <img />

    点击 `Continue without free credits`

    <img />

    在下方输入任意组织名，然后点击 `CONTINUE`

    <img />

    点击 `CONTINUE`

    <img />

    忽略下述页面内容，回到终端

    <img />
  </Step>

  <Step title="选择模型">
    设置当前session model：输入 `/model`，选择 **SenseAudio** 开始使用

    <img />

    设置全局默认 model：输入 `/settings`，选择 **SenseAudio** 开始使用

    <img />

    <img />
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="Codex CLI" icon="terminal" href="/guides/token-plan/codex-cli" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# 常见问题
Source: https://docs.senseaudio.cn/guides/token-plan/faq

Token Plan 订阅、用量、限额、切换与开票等常见问题

## 目录

* **一、套餐与模型**：支持模型、Pro / Max / Ultra 套餐区别、套餐升级
* **二、用量与限额**：用量查询、重置规则、达到限额后的处理
* **三、API Key 与接入**：API Key 的接入、多工具共用、生产环境适用性
* **四、计费与开票**：退款、开票规则、TPS 计算
* **五、反馈与支持**：问题反馈入口

***

## 一、套餐与模型

### Token Plan 支持哪些模型？如何切换？

Token Plan 覆盖 SenseAudio 自研与多家第三方主流模型，完整清单见 [模型列表](/guides/account/model-list)：

* **文本**：`senseaudio-s2`、`senseaudio-s2-flash`、`senseaudio-s2-lite`、`sensenova-6.8-flash-lite`, 以及DeepSeek、Qwen、Kimi、GLM、MiniMax、Doubao 等多家第三方模型
* **多模态**：`senseaudio-vl-1.0-260319`、`senseaudio-vl-lite-1.0-260319`等
* **语音合成**：`sensenova-tts-2.0`、`senseaudio-tts-1.5-260319`
* **语音识别**：`senseaudio-asr-1.5-260319` 等 5 款
* **人声提取**：`senseaudio-voice-isolation-1.5`、`senseaudio-voice-isolation-1.0-260319`
* **图像生成**：`senseaudio-image-2.0-260319`、`sensenova-u1-fast`、`senseaudio-image-1.0-260319`、`doubao-seedream-5-0-260128`
* **视频生成**：`doubao-seedance-2-0-260128`（支持 480P / 720P / 1080P 三档分辨率）
* **音乐生成**：`senseaudio-music-1.0-260319` 、`senseaudio-music-2.0-260626`
* **音效生成**：`senseaudio-sfx-1.0-260626`

请求时通过 `model` 字段切换：

```python theme={null}
client.chat.completions.create(
    model="senseaudio-vl-1.0-260319",  # 改为 senseaudio-vl-lite-1.0-260319 即切换
    messages=[...],
)
```

Token Plan 采用**共享积分池**——所有模型共用同一额度，并叠加 **5 小时 / 每周 / 月度** 三层滑动窗口与并发上限。详见 [Token Plan 概览](/guides/token-plan/overview#用量额度)。

***

### Pro / Max / Ultra 套餐有何区别？

Token Plan 提供三档订阅套餐，按月度积分、滑动窗口额度与并发数差异化定价：

* **Pro（¥199）**：入门档，适合个人开发者与日常编码、实验，全量旗舰模型随心切换；
* **Max（¥699，推荐）**：主力档，适合主力开发与 Agent 长时运行，**SLA 99.98% · 优先调度**；
* **Ultra（¥1,899）**：团队档，适合团队生产负载与高并发 Agent 集群，**企业级 SRE · 合规报告**。

详细额度对照与并发上限请见 [Token Plan 概览](/guides/token-plan/overview#用量额度)。

***

### 订阅套餐可以升级吗？

可以。Token Plan 支持订阅期内**随时升级**——可在 Pro → Max → Ultra 之间跃迁更高等级。升级时仅需支付差价，**新套餐立即生效**。

***

***

## 二、用量与限额

### 如何查看 Token Plan 用量？

访问 **Token Plan** 控制台页面查看当前剩余积分，以及 5 小时 / 每周 / 月度三层滑动窗口的消耗情况。

***

### 用量如何重置？

Token Plan 采用**共享积分池**叠加 **5 小时 / 每周 / 月度** 三层滑动窗口，所有模型共用同一额度：

* **5 小时滚动窗口**：系统持续计算"过去 5 小时"内的累计积分消耗，随时间推移最早的额度自动滚动释放。
* **每周与月度窗口**：同样按滑动方式滚动计算，达到上限时可开启 Extra Usage 或等待自动滚动释放。

任一窗口达上限后，可开启 **Extra Usage**，超出部分自动按量计费、从账户积分余额扣除。

***

### 达到限额怎么办？

5 小时 / 每周 / 月度任一滑动窗口达上限时，有以下三种处理方式：

1. **升级套餐**：立即升到更高等级（Pro → Max → Ultra），获得更大额度；
2. **开启 Extra Usage**：在 SenseAudio API 平台打开 Extra Usage 开关，超出部分自动按量计费、从账户积分余额扣除，无需更换 API Key；
3. **等待窗口恢复**：对应滑动窗口随时间持续滚动，额度会自动释放。

***

### 可以同时在多个工具中使用同一套餐吗？

可以。同一订阅支持在 Claude Code、Cursor、Trae、Zed 等所有工具中并行使用，**但额度是共享的**——所有工具都会消耗同一个共享积分池，并叠加 5 小时 / 每周 / 月度三层滑动窗口与并发上限。

***

***

## 四、计费与开票

### 订阅后可以退款吗？

订阅服务一经购买即视为确认，**不支持退款**。即使未使用完，费用也无法退回。请根据使用需求谨慎选择套餐和周期。

***

### 合并支付的订单如何开票？

* **支付宝 / 微信直接付款**：可开票
* **余额支付**：可开票
* **余额 + 三方支付组合**：可开票
* **代金券抵扣部分**：**不可开票**，仅按实际支付金额开具

如订单使用了代金券，开票金额为扣除代金券后的实际支付金额。

***

### TPS（Tokens Per Second）怎么计算？

TPS 表示模型每秒生成的 token 数量，计算公式：

$$
\mathrm{TPS} = \frac{N_{\text{out}}}{T_{\text{last}} - T_{\text{first}}}
$$

其中：

* **`N_out`**：输出 token 总数
* **`T_first`**：第一个 token 生成时间
* **`T_last`**：最后一个 token 生成时间

<Note>
  实际使用中 TPS 会因网络、集群负载波动，各模型页面标注的 TPS 为参考值。
</Note>

***

### Token Plan 有哪些使用限制？适合生产环境吗？

Token Plan 面向**个人开发者与小团队**的交互式使用场景：

* **速率限制（RPM / TPM）**：超出会短暂限流（通常 1 分钟恢复）；
* **共享积分池**：所有模型共用同一池积分，按 Token / 字符 / 秒 / 张 / 首 折算扣减；
* **三层滑动窗口**：5 小时 / 每周 / 月度任一窗口达上限即触发限流，可开启 Extra Usage 解除。

若您的业务为**生产级大规模调用**，建议使用按量计费 API Key，或联系商务团队商谈定制方案。

***

## 五、反馈与支持

### 问题反馈与联系方式

* 邮件支持：[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)

## 相关资源

<CardGroup>
  <Card title="Token Plan 概览" icon="book-open" href="/guides/token-plan/overview" />

  <Card title="快速接入" icon="rocket" href="/guides/token-plan/quickstart" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />
</CardGroup>


# Grok CLI
Source: https://docs.senseaudio.cn/guides/token-plan/grok-cli

在 Grok CLI 中使用 S2 模型进行 AI 编程

## 安装 Grok CLI

如果你的设备尚未安装 Node.js，请先安装 Node.js 18 及以上版本，再执行以下命令安装 Grok CLI。

你可以访问官网安装，也可以通过命令安装：

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node
  ```

  ```bash Ubuntu / Debian theme={null}
  sudo apt update && sudo apt install -y nodejs npm
  ```

  ```powershell Windows (winget) theme={null}
  winget install OpenJS.NodeJS.LTS
  ```
</CodeGroup>

如果你更习惯图形界面安装，也可以访问：

<CodeGroup>
  ```bash macOS / Linux - 安装 Node.js theme={null}
  https://nodejs.org/
  ```

  ```powershell Windows - 安装 Node.js theme={null}
  https://nodejs.org/
  ```
</CodeGroup>

安装完成后，执行以下命令安装 Grok CLI：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  npm install -g @vibe-kit/grok-cli
  ```

  ```powershell Windows theme={null}
  npm install -g @vibe-kit/grok-cli
  ```
</CodeGroup>

<Note>
  更多安装细节与进阶用法请参考 [ xAI 官方文档](https://grokcli.io/)。
</Note>

## 配置 SenseAudio API

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

<Steps>
  <Step title="设置环境变量">
    你可以先在当前终端中临时设置环境变量；如果希望长期生效，请写入对应系统的环境变量配置。

    <CodeGroup>
      ```bash macOS / Linux（临时生效） theme={null}
      export GROK_BASE_URL="https://api.senseaudio.cn/v1"
      export GROK_API_KEY="<SENSEAUDIO_API_KEY>"
      ```

      ```powershell Windows（PowerShell 临时生效） theme={null}
      $env:GROK_BASE_URL="https://api.senseaudio.cn/v1"
      $env:GROK_API_KEY="<SENSEAUDIO_API_KEY>"
      ```
    </CodeGroup>

    macOS / Linux 如需长期生效，可以将环境变量写入 Shell 配置文件：

    <CodeGroup>
      ```bash zsh theme={null}
      nano ~/.zshrc
      ```

      ```bash bash theme={null}
      nano ~/.bashrc
      ```
    </CodeGroup>

    在文件末尾加入以下内容，保存后重新打开终端，或执行 `source ~/.zshrc` / `source ~/.bashrc` 生效：

    ```bash theme={null}
    export GROK_BASE_URL="https://api.senseaudio.cn/v1"
    export GROK_API_KEY="<SENSEAUDIO_API_KEY>"
    ```

    如果需要在 Windows 桌面环境中长期生效，请按以下步骤配置：

    1. 打开 **开始菜单**，搜索 **环境变量**。
    2. 点击 **编辑系统环境变量**。
    3. 在弹出的窗口中点击 **环境变量**。
    4. 在 **用户变量** 中点击 **新建**，分别添加：
       * 变量名：`GROK_BASE_URL`，变量值：`https://api.senseaudio.cn/v1`
       * 变量名：`GROK_API_KEY`，变量值：你的 SenseAudio Token Plan API Key
    5. 保存后重新打开终端，再启动 Grok CLI。
  </Step>

  <Step title="启动 Grok CLI">
    <CodeGroup>
      ```bash macOS / Linux theme={null}
      grok --model senseaudio-s2
      ```

      ```powershell Windows theme={null}
      grok --model senseaudio-s2
      ```
    </CodeGroup>
  </Step>
</Steps>

运行效果如下：

<img />

<Tip>
  macOS / Linux 中通过 `export` 设置的变量只在当前终端会话内生效；如果希望长期生效，建议写入 `~/.zshrc` 或 `~/.bashrc`。Windows 中通过 PowerShell 设置的 `$env:` 变量也只在当前终端会话内生效。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Codex CLI" icon="terminal" href="/guides/token-plan/codex-cli" />

  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Hermes Agent
Source: https://docs.senseaudio.cn/guides/token-plan/hermes-agent

在 Hermes Agent 中接入 S2 模型进行自主 AI 编程。

<img alt="Hermes Agent" />

## 概述

[Hermes Agent](https://github.com/NousResearch/hermes-agent) 是由 [Nous Research](https://nousresearch.com) 开发的开源自主学习 AI 智能体，具备持久记忆、自改进能力与丰富的工具生态。本文将指导你把 SenseAudio 的 **S2 模型**（模型 ID：`senseaudio-s2`）接入 Hermes Agent。

<CardGroup>
  <Card title="跨会话持久记忆" icon="brain">
    编程模式与项目上下文自动沉淀，用得越多越懂你。
  </Card>

  <Card title="自改进学习" icon="wand-magic-sparkles">
    内置技能系统会从每次交互中持续优化。
  </Card>

  <Card title="40+ 集成工具" icon="toolbox">
    覆盖代码、搜索、文件与外部服务等常用能力。
  </Card>

  <Card title="多平台支持" icon="layer-group">
    CLI、Telegram、Discord、Slack、WhatsApp 全平台可用。
  </Card>
</CardGroup>

## 前提条件

<Check>已订阅 SenseAudio [Token Plan](https://senseaudio.cn/tokenplan)</Check>
<Check>一台可访问终端的电脑（macOS、Linux 或 Windows WSL2）</Check>

## 安装 Hermes Agent

<Steps>
  <Step title="一键安装">
    在终端中运行以下命令：

    ```bash theme={null}
    curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
    ```

    <Note>
      安装脚本会自动检测并安装 uv、Python、Node.js、ripgrep、ffmpeg 等依赖，无需提前手动配置。
    </Note>
  </Step>

  <Step title="验证安装">
    执行环境自检命令，确认依赖与配置就绪：

    ```bash theme={null}
    hermes doctor
    ```
  </Step>
</Steps>

<Note>
  更多安装细节与进阶用法请参考 [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs/)。
</Note>

## 配置 Token Plan

Hermes Agent 暂未内置 SenseAudio，需通过 `hermes setup` 手动配置自定义 Provider 与模型：

```bash theme={null}
hermes setup
```

<Steps>
  <Step title="选择 Provider">
    从 provider 列表中选择 **Custom endpoint**。

    <Frame>
      <img alt="选择 Custom endpoint" />
    </Frame>
  </Step>

  <Step title="填写 API Base URL">
    输入 SenseAudio 的 API 接入地址（中国大陆节点）：

    ```text theme={null}
    https://api.senseaudio.cn/v1
    ```
  </Step>

  <Step title="输入 API Key">
    粘贴从控制台 **账户管理 → Token Plan** 获取的 **Token Plan API Key**。

    <Frame>
      <img alt="输入 Token Plan API Key" />
    </Frame>
  </Step>

  <Step title="输入模型名称">
    手动输入模型 ID **`senseaudio-s2`**（即 S2）作为默认模型。
  </Step>
</Steps>

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

## 开始使用

配置完成后，在终端输入以下命令即可启动 Hermes Agent，开始与 **S2 模型** 对话：

```bash theme={null}
hermes
```

启动后，你可以直接用自然语言下达任务，例如：

* "帮我用 Python 写一个爬取网页标题的脚本"
* "检查当前项目的依赖有没有安全漏洞"
* "把 README.md 翻译成英文"

<Tip>
  **越用越聪明**：Hermes Agent 会自动记录你的编程习惯、项目背景和偏好设置，下次打开时无需重复说明——用得越久，给出的回答就越贴合你的需求。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code">
    在 Claude Code 中接入 S2 模型
  </Card>

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    发挥 S2 模型最佳效果
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Coding Agent 是如何工作的
Source: https://docs.senseaudio.cn/guides/token-plan/how-agent-works

Agent 不是一问一答的聊天框，而是一个在「思考—行动—观察」循环中自主推进任务的智能体。

如果您是第一次接触「AI Coding Agent」（如 Claude Code、Cursor Agent、Cline 等），这一页帮您建立最核心的心智模型——理解 Agent Loop、Model 与 Tool 的分工，以及 S系列模型 在其中的角色。

***

## Agentic Loop：Agent 的三段式循环

Agent 的每一轮工作都可以拆解为三步：

<Steps>
  <Step title="思考（Think）">
    根据当前上下文进行推理：读取工程目录、打开相关文件、调用 `grep` / `glob` 搜索关键字，理解现状并制定下一步计划。
  </Step>

  <Step title="执行（Act）">
    按照计划调用工具：编辑文件、运行命令、发起子任务、调用外部 API。
  </Step>

  <Step title="观察（Observe）">
    查看执行结果：跑测试、检查 diff、重新读取被改动的文件，判断是否达到目标；若未达成，回到第一步。
  </Step>
</Steps>

***

## Agent 的四类组件

| 组件                | 作用                  | 在 SenseAudio Token Plan 中的体现                                     |
| ----------------- | ------------------- | ---------------------------------------------------------------- |
| **Model（模型）**     | 负责推理与决策             | S系列模型                                                            |
| **Tool（工具）**      | Agent 可执行的基础能力      | 文件读写、Shell、Web、代码分析等内置工具                                         |
| **Extension（扩展）** | 加强 Agent 的跨工程/跨模态能力 | 由所使用的 Agent 工具决定，如 Claude Code 的 Skills / Hooks、Cursor 的 Rules 等 |
| **Memory（记忆）**    | 跨会话/跨项目地沉淀知识        | 静态配置：项目级配置文件（见下文）；动态记忆：取决于 Agent 工具自身的实现                         |

## 内置工具的五大类别

虽然每个编程工具的工具名不完全相同，但大致可归为：

* **文件操作**：读取、创建、编辑项目文件（如 `read_file`、`write_file`、`edit`）
* **检索**：按文件名或内容搜索代码库（如 `grep`、`glob`、`ls`）
* **命令执行**：在终端运行 Shell 命令（如 `bash`、`shell`）
* **网络**：抓取网页、调用外部 API（如 `fetch_url`、`web_search`）
* **代码分析**：语法树搜索、类型检查等深度代码理解（如 `ast_search`、LSP 集成）

***

## 项目级配置文件

主流 Agent 工具都支持通过项目级配置文件**将项目知识提供给模型**，Agent 启动时自动读取。不同工具的命名和格式各异（以官方文档为准）：

| 工具                   | 配置文件                         |
| -------------------- | ---------------------------- |
| Claude Code          | `CLAUDE.md`                  |
| Cursor               | `.cursor/rules`（目录，可含多个规则文件） |
| Cline                | `.clinerules`                |
| Codex CLI / OpenCode | `AGENTS.md`                  |

**推荐写入内容**：项目架构简介、关键命令（`pnpm dev`、`pytest` 等）、测试与验证方式、代码风格约束、不得修改的文件。

<Tip>
  一份高质量的项目级配置，能把 Agent 的每轮工作都变成「带着常识上班」——比再多的 Prompt 技巧都更省 Token Plan 额度。
</Tip>

***

## 与 SenseAudio 多模态的协同

SenseAudio Token Plan 的独特之处，在于您可以在同一个订阅下把「S2 推理 + 语音 / 图像 / 视频 / 音乐」直接接入 Agent 工作流：

* 用 **S2**（`senseaudio-s2`）完成规划、代码生成与图文混合理解，**S2-Lite**（`senseaudio-s2-lite`）承担高频轻量子调用；
* 用 [`sensenova-tts-2.0`](/guides/tts/overview) 在长任务进行中让 Agent **把 Code Review 结论念给您听**；
* 用 [`senseaudio-asr-1.5-260319`](/guides/asr/overview) **口述需求**，由 Agent 转写为 GCCV 开场白；
* 用 [`senseaudio-image-2.0-260319`](/guides/image/overview) 让 Agent 在生成前端组件时**顺手出一张设计稿**；
* 用 [`doubao-seedance-2-0-260128`](/guides/video/overview) 对外**输出项目演示视频**，替代文字 PR 描述。

这些能力在主流竞品的 Coding Plan 中通常不提供，是 SenseAudio 用户独享的生态优势。

## 相关资源

<CardGroup>
  <Card title="常见工作流" icon="diagram-project" href="/guides/token-plan/common-workflows" />

  <Card title="S系列 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />
</CardGroup>


# Kilo Code
Source: https://docs.senseaudio.cn/guides/token-plan/kilo-code

在 Kilo Code 中使用 S2 模型进行 AI 编程

## 安装 Kilo Code

<Steps>
  <Step title="打开扩展面板">
    在 VS Code 左侧活动栏点击 **扩展** 图标（或按下 `Cmd/Ctrl+Shift+X`）。
  </Step>

  <Step title="搜索并安装">
    在搜索框中输入 `Kilo Code`，在结果中点击 **Install**。安装完成后建议重启一次 VS Code。
  </Step>
</Steps>

<Frame>
  <img alt="在 VS Code 扩展市场搜索并安装 Kilo Code" />
</Frame>

## 配置 SenseAudio API

<Warning>
  **配置前请先清除以下 Anthropic 环境变量**，防止与其它扩展的配置互相覆盖：

  * `ANTHROPIC_AUTH_TOKEN`
  * `ANTHROPIC_BASE_URL`
</Warning>

<Steps>
  <Step title="进入 Kilo Code 设置">
    点击左侧导航栏的 Kilo Code 图标进入插件界面。
  </Step>

  <Step title="打开 Settings">
    点击右上角的 **Settings** 图标进入参数配置。

    <Frame>
      <img alt="打开 Kilo Code Settings" />
    </Frame>
  </Step>

  <Step title="选择自定义 Provider">
    在 Provider 列表中选择 **自定义**。

    <Frame>
      <img alt="选择自定义 Provider" />
    </Frame>
  </Step>

  <Step title="填写 Provider 信息">
    按下表填写模型服务配置：

    <div>
      <div>配置项</div>
      <div>值</div>

      <div>API Provider</div>
      <div><code>senseaudio</code></div>

      <div>Base URL</div>
      <div><code>[https://api.senseaudio.cn/v1](https://api.senseaudio.cn/v1)</code></div>

      <div>API Key</div>
      <div><code>您的 Token Plan API Key</code></div>

      <div>Model</div>
      <div><code>senseaudio-s2</code></div>
    </div>

    <Note>
      API Key 可在 [快速接入](/guides/token-plan/quickstart) 中获取。
    </Note>

    填写完成后，划到最下方点击 **提交** 保存设置。

    <Frame>
      <img alt="填写 Provider 信息" />
    </Frame>

    <Frame>
      <img alt="提交保存设置" />
    </Frame>
  </Step>

  <Step title="开始使用">
    将模型切换到 `senseaudio-s2`，即可在 Kilo Code 中使用 S2 模型处理编码任务。

    <Frame>
      <img alt="切换模型" />
    </Frame>

    <Frame>
      <img alt="Kilo Code 主面板开始对话" />
    </Frame>
  </Step>
</Steps>

<Tip>
  **模型选择建议**：复杂重构或架构设计可切换到 `senseaudio-s2`；日常高频编码使用 `senseaudio-s2-flash` 可获得更快的响应速度。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Cline" icon="code" href="/guides/token-plan/cline">
    另一款热门的 VS Code AI 编程扩展
  </Card>

  <Card title="Roo Code" icon="rocket" href="/guides/token-plan/roo-code">
    开源的 VS Code AI 编程扩展
  </Card>

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    发挥 S2 模型最佳效果
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# MonkeyCode
Source: https://docs.senseaudio.cn/guides/token-plan/monkeycode

在 MonkeyCode 企业开发平台中使用 S2 模型

## 关于 MonkeyCode

**MonkeyCode** 是一款企业级 AI 开发平台，其 Code Agent 支持 OpenAI Codex、Claude Code、OpenCode 等工具无缝切换。它不只是 AI 编程工具，还覆盖「需求 → 设计 → 开发 → Review」全流程，提供安全、隔离、可并行的开发环境。

## 配置 SenseAudio API

<Note>
  如需在 MonkeyCode 中使用 SenseAudio `S2` 模型，需要先绑定你的 **SenseAudio Token Plan**。MonkeyCode 平台可能提供公共模型额度，但公共额度不等同于 SenseAudio Token Plan；在专业开发场景中，建议使用自己的 API Key，以获得更稳定的高频、长时编码体验。
</Note>

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。下面配置中的 **API Key** 需要填写该专属 Key；套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

按照以下步骤在 MonkeyCode 中绑定 SenseAudio Token Plan，并在任务执行时调用 S2 模型。MonkeyCode 当前支持两种接口格式，任选其一即可。

<Steps>
  <Step title="登录 MonkeyCode">
    访问 [MonkeyCode 官网](https://monkeycode-ai.com/) 完成登录。
  </Step>

  <Step title="进入任务页面">
    登录后点击 **开始使用**，进入 MonkeyCode 智能开发平台任务页面。

    <img />
  </Step>

  <Step title="进入系统配置">
    点击页面右下角 **配置**，进入系统配置页面。

    <img />
  </Step>

  <Step title="绑定 AI 大模型">
    在 AI 大模型模块点击 **绑定**。

    <img />
  </Step>

  <Step title="填写 SenseAudio 配置">
    根据你的需要，选择以下任一种接口格式：

    ### 方式一（推荐）

    | 配置项           | 值                                |
    | ------------- | -------------------------------- |
    | **模型 API 地址** | `https://api.senseaudio.cn/v1`   |
    | **API Key**   | 您的 SenseAudio Token Plan API Key |
    | **接口格式类型**    | `openai-chat`                    |
    | **模型名称**      | `senseaudio-s2`                  |

    ### 方式二

    | 配置项           | 值                                |
    | ------------- | -------------------------------- |
    | **模型 API 地址** | `https://api.senseaudio.cn/v1`   |
    | **API Key**   | 您的 SenseAudio Token Plan API Key |
    | **接口格式类型**    | `OpenAI Responses`               |
    | **模型名称**      | `senseaudio-s2`                  |

    接口格式类型如下图所示，完成后点击 **保存**。

    <img />

    <img />
  </Step>

  <Step title="开始使用">
    返回 MonkeyCode 主界面，输入 Prompt 后点击 **执行**，即可调用已配置的 **S2**。

    <img />
  </Step>
</Steps>

<Tip>
  如果你不确定选择哪种方式，建议优先使用方式一。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="OpenCode" icon="folder-open" href="/guides/token-plan/opencode" />

  <Card title="Hermes Agent" icon="robot" href="/guides/token-plan/hermes-agent" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# OpenClaw
Source: https://docs.senseaudio.cn/guides/token-plan/openclaw

在 OpenClaw 中使用 S2 模型

[OpenClaw](https://github.com/openclaw/openclaw) 是一款开源的本地 AI 网关（Gateway）工具，支持多模型供应商切换、OAuth 登录、会话记忆、命令日志等能力。本页介绍如何在 [OpenClaw](https://docs.openclaw.ai/) 中接入 SenseAudio Token Plan，并使用 `S2` 模型。

更多安装与配置说明请参考 [OpenClaw 官方文档](https://docs.openclaw.ai/)。

## 前提条件

<Check>已订阅 SenseAudio [Token Plan](https://senseaudio.cn/tokenplan)</Check>
<Check>一台可访问终端的电脑（macOS、Linux 或 Windows WSL2）</Check>

## 步骤一：安装 OpenClaw

在终端中运行以下命令安装（老用户同样可用此命令更新）：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://openclaw.ai/install.sh | bash
  ```

  ```powershell Windows theme={null}
  iwr -useb https://openclaw.ai/install.ps1 | iex
  ```
</CodeGroup>

安装完成后，终端会自动进入初始化引导。请按界面出现的顺序依次选择下面的选项。

> 如果中途选错了，不用担心。先继续完成当前流程，结束后重新运行 `openclaw onboard` 即可再次进入初始化引导。`openclaw config` 用于修改指定配置项；如果你不熟悉这些选项，建议优先使用 `openclaw onboard`。

1. 出现欢迎界面后，选择 `Yes` 继续。

<img />

2. `Setup mode` 选择 `QuickStart`。

<img />

3. `Model/auth provider` 选择 `Skip for now`。这里先跳过内置模型供应商配置，后面会在 `openclaw.json` 中手动添加 SenseAudio 配置。

<img />

4. `Filter models by provider` 选择 `All providers`（默认选项），直接按回车确认即可。

<img />

5. `Default model` 选择 `Keep current`（默认选项），直接按回车确认即可。后面配置 SenseAudio 后，会把默认模型改成 `senseaudio/senseaudio-s2`。

<img />

6. `Select channel (QuickStart)` 选择 `Skip for now`，暂时不添加 Telegram、Discord、飞书等外部聊天渠道。如果你确实需要接入某个渠道，可以按界面选择对应渠道，并根据 [OpenClaw 官方文档](https://docs.openclaw.ai/) 补充该渠道需要的配置。

<img />

7. `Search provider` 选择 `Skip for now`，暂时不配置联网搜索服务。联网搜索通常需要额外的搜索服务 API Key；如果你需要开启，可以后续参考 [OpenClaw 官方文档](https://docs.openclaw.ai/) 按需配置。

<img />

8. `Configure skills now? (recommended)` 可以按需选择。如果你想使用某个 Skill，可以在这里选择对应能力；如果暂时不确定，可以先跳过，后续再通过 `openclaw config` 指定配置。

9. `Install missing skill dependencies` 建议新手先选择 `Skip for now`。如果你需要使用某个 Skill，后续可以运行 `openclaw config`，进入 `Skills (Install/enable workspace skills)`，再按需选择并安装对应 Skill。

<img />

10. 后续几个第三方 API Key 配置都可以先选择 `No`：
    * `Set GOOGLE_PLACES_API_KEY for goplaces?` 选择 `No`
    * `Set NOTION_API_KEY for notion?` 选择 `No`
    * `Set OPENAI_API_KEY for openai-whisper-api?` 选择 `No`
    * `Set ELEVENLABS_API_KEY for sag?` 选择 `No`

<img />

11. `Enable hooks?` 选择 `Skip for now`。Hooks 是自动化能力，新手可以先不启用。

12. 如果提示 `Gateway service already installed`，选择 `Restart`，让网关使用最新配置重新启动。

13. 如果出现 `How do you want to hatch your bot?`，新手建议选择 `Open the Web UI`，OpenClaw 会自动打开网页界面；如果你更习惯终端，也可以稍后运行 `openclaw tui` 使用终端界面。

<img />

如果初始化过程中出现依赖安装失败、网络下载失败、API Key 不知道怎么填等情况，可以先选择 `Skip for now` 或 `No` 完成初始化。只要后续完成 SenseAudio API 配置，就可以正常使用 S2 模型。

***

## 步骤二：配置 SenseAudio API

完成步骤一安装 OpenClaw 后，打开 OpenClaw 的配置文件 `openclaw.json`，在里面修改对应配置，把 SenseAudio API KEY 添加进去。根据你的系统，在终端中运行对应命令打开配置文件：

<CodeGroup>
  ```bash macOS theme={null}
  open ~/.openclaw/openclaw.json
  ```

  ```bash Linux theme={null}
  xdg-open ~/.openclaw/openclaw.json
  ```

  ```powershell Windows theme={null}
  notepad $env:USERPROFILE\.openclaw\openclaw.json
  ```
</CodeGroup>

> 需要在现有配置 `openclaw.json` 中修改或补充以下字段。请先在 [SenseAudio Token Plan](https://senseaudio.cn/tokenplan) 获取 API Key，并把示例中的 `<SENSEAUDIO_API_KEY>` 替换成你的真实 Key。

将 `agents.defaults` 的默认模型修改为 `senseaudio/senseaudio-s2`；如果没有 `agents` 或 `defaults` 字段，则新增对应配置：

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "senseaudio/senseaudio-s2"
      }
    }
  }
}
```

如果你的 `openclaw.json` 里已经有 `models` 字段，不要删除原有内容，只需要在 `providers` 里新增 `senseaudio` 这一段配置；如果不确定怎么合并，也可以参考下面的完整示例：

```json theme={null}
{
  "models": {
    "mode": "merge",
    "providers": {
      "senseaudio": {
        "baseUrl": "https://api.senseaudio.cn/v1",
        "api": "openai-responses",
        "apiKey": "<SENSEAUDIO_API_KEY>",
        "models": [
          {
            "id": "senseaudio-s2",
            "name": "senseaudio-s2",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1050000,
            "maxTokens": 128000,
            "compat": {
              "supportsStore": false,
              "supportsReasoningEffort": true
            }
          }
        ]
      }
    }
  }
}
```

配置完成后，执行以下命令重启 OpenClaw 网关，使配置生效：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw gateway restart
  ```

  ```powershell Windows theme={null}
  openclaw gateway restart
  ```
</CodeGroup>

***

## 步骤三：开始使用 S2 模型

配置完成后，可以选择以下任意一种方式开始使用。

### 方式一：在 Web UI 中使用

如果初始化最后出现 `How do you want to hatch your bot?`，可以选择 `Open the Web UI`。OpenClaw 会自动打开 Web UI，你可以直接在网页对话框中输入需求。

### 方式二：在终端 TUI 中使用

也可以在终端中输入以下命令进入 OpenClaw TUI。Windows 用户可以在 PowerShell 或 Windows Terminal 中执行同样的命令：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw tui
  ```

  ```powershell Windows theme={null}
  openclaw tui
  ```
</CodeGroup>

在 Web UI 或 TUI 的对话框中直接输入你的需求即可，例如：

```text theme={null}
 请使用 senseaudio-tts-1.5-260319 生成一段温柔女声朗读音频：欢迎使用 SenseAudio Token Plan。
```

能正常返回结果即配置成功。

运行效果如下：

<img />

***

## 常见问题

### 初始化时选错了怎么办

如果安装完成后的初始化步骤选错了，建议重新执行初始化引导：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw onboard
  ```

  ```powershell Windows theme={null}
  openclaw onboard
  ```
</CodeGroup>

### 安装后无法使用 `senseaudio-s2`

打开配置文件 `openclaw.json`，确认默认模型已配置为 `senseaudio/senseaudio-s2`，然后执行以下命令重启网关：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw gateway start
  ```

  ```powershell Windows theme={null}
  openclaw gateway start
  ```
</CodeGroup>

如果网关已经在运行，也可以执行：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw gateway restart
  ```

  ```powershell Windows theme={null}
  openclaw gateway restart
  ```
</CodeGroup>

### 如何检查 OpenClaw 状态

可使用以下命令检查配置与网关状态：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  openclaw doctor
  openclaw status
  ```

  ```powershell Windows theme={null}
  openclaw doctor
  openclaw status
  ```
</CodeGroup>

## 相关资源

<CardGroup>
  <Card title="SenseAudio CLI" icon="terminal" href="/guides/token-plan/senseaudio-cli" />

  <Card title="Hermes Agent" icon="sparkles" href="/guides/token-plan/hermes-agent" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# OpenCode
Source: https://docs.senseaudio.cn/guides/token-plan/opencode

在 OpenCode 中使用 S2 模型进行 AI 编程

## 安装 OpenCode

<CodeGroup>
  ```bash curl theme={null}
  curl -fsSL https://opencode.ai/install | bash
  ```

  ```bash npm theme={null}
  npm i -g opencode-ai
  ```
</CodeGroup>

更多信息请参考 [OpenCode 官网](https://opencode.ai/)。

## 配置 SenseAudio API

<Info>
  **还没有 API Key？** 请先订阅 [Token Plan](https://senseaudio.cn/tokenplan)，然后在控制台 **账户管理 → Token Plan** 创建专属 API Key。套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分将自动按量计费、从账户余额扣费。
</Info>

OpenCode 支持两种兼容 OpenAI 的 Provider 配置方式，任选其一即可。

<CodeGroup>
  ```txt macOS / Linux theme={null}
  ~/.config/opencode/opencode.json
  ```

  ```txt Windows theme={null}
  %USERPROFILE%\\AppData\\Roaming\\opencode\\opencode.json
  ```
</CodeGroup>

### 方式一（推荐）

<Steps>
  <Step title="编辑配置文件">
    复制以下内容写入对应系统的配置文件：

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "senseaudio": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "senseaudio",
          "options": {
            "baseURL": "https://api.senseaudio.cn/v1",
            "apiKey": "<SENSEAUDIO_API_KEY>"
          },
          "models": {
            "senseaudio-s2": {
              "name": "senseaudio-s2"
            }
          }
        }
      }
    }
    ```
  </Step>
</Steps>

### 方式二

<Steps>
  <Step title="编辑配置文件">
    复制以下内容写入对应系统的配置文件：

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "senseaudio": {
          "npm": "@ai-sdk/openai",
          "name": "senseaudio",
          "options": {
            "baseURL": "https://api.senseaudio.cn/v1",
            "apiKey": "<SENSEAUDIO_API_KEY>"
          },
          "models": {
            "senseaudio-s2": {
              "name": "senseaudio-s2"
            }
          }
        }
      }
    }
    ```
  </Step>
</Steps>

## 启动 OpenCode

<Steps>
  <Step title="进入项目目录并启动">
    ```bash theme={null}
    cd /path/to/your/project
    opencode
    ```
  </Step>

  <Step title="选择模型">
    输入 `/models`，选择 `senseaudio-s2` 开始使用。
  </Step>
</Steps>

运行效果如下：

<img />

<Tip>
  如果你不确定选择哪种方式，建议优先使用方式一。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Claude Code" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Token Plan 概览
Source: https://docs.senseaudio.cn/guides/token-plan/overview

一个订阅，解锁 SenseAudio 全模态模型与 AI 编程生态

Token Plan 是 SenseAudio 为个人开发者与小团队提供的 **订阅式** 使用方案：一个固定订阅费即可获得跨模态共享的积分池，并叠加 5 小时 / 每周 / 月度三层滑动窗口额度，可直接在 Claude Code、Cursor、Zed、Trae 等主流 AI 编程工具中接入。

## 为什么选择 SenseAudio Token Plan

SenseAudio 是商汤科技旗下的全模态 AI 开放平台，覆盖**文本、语音合成、语音识别、图像、视频、音乐**六大方向。相比同类编程套餐，Token Plan 的优势：

<CardGroup>
  <Card title="全模态一站式" icon="layer-group">
    一个订阅解锁文本生成、TTS、ASR、图像、视频、音乐全部模态，无需多平台账户。
  </Card>

  <Card title="旗舰模型加持" icon="wand-magic-sparkles">
    **SenseAudio-S2** 自研旗舰大语言模型，支持 1M 上下文与深度推理。
  </Card>

  <Card title="全速度梯度" icon="bolt">
    **S2-Flash / S2-Lite** 高吞吐低延迟通道，适合高并发 Agent 与海量简单任务。
  </Card>

  <Card title="协议零改造接入" icon="code">
    原生兼容 OpenAI / Anthropic API 协议，主流编程工具、Agent 框架与 CLI 工具均可直接接入。
  </Card>

  <Card title="固定订阅费" icon="dollar-sign">
    告别账单焦虑：订阅期内按共享积分池消耗，跨模态、跨厂商共用一池额度。
  </Card>

  <Card title="中文场景原生优化" icon="language">
    S2系列与 TTS / ASR 均以中文语音、文本、多模态场景为主训练，中文表达力与识别准确率领先。
  </Card>
</CardGroup>

## 支持的模型

详细价格、上下文长度与阶梯计费规则请见 [模型列表与计费说明](/guides/account/model-list)。调用时 `model` 参数请严格按下方 ID 拼写，区分大小写。

### SenseAudio 系列（自研）

| 模态   | 模型名称                        | 模型 ID                                                                      | 说明                                                       |
| ---- | --------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| 文本生成 | SenseAudio-S2               | `senseaudio-s2`                                                            | 自研旗舰大语言模型，1M 上下文，深度推理与复杂工具调用                             |
| 文本生成 | SenseAudio-S2-Flash         | `senseaudio-s2-flash`                                                      | 高吞吐快速版，256K 上下文，适合实时交互                                   |
| 文本生成 | SenseAudio-S2-Lite          | `senseaudio-s2-lite`                                                       | 轻量低成本版，256K 上下文，适合大规模吞吐                                  |
| 文本生成 | SenseAudio-S1               | `senseaudio-s1`                                                            | 自研旗舰大语言模型，1M 上下文，深度推理与复杂工具调用                             |
| 多模态  | SenseAudio-VL-1.0           | `senseaudio-vl-1.0-260319`                                                 | 多模态旗舰，1M 上下文，图文混合理解                                      |
| 多模态  | SenseAudio-VL-Lite-1.0      | `senseaudio-vl-lite-1.0-260319`                                            | 多模态轻量版，256K 上下文                                          |
| 多模态  | SenseNova-6.8-Flash-Lite    | `sensenova-6.8-flash-lite`                                                 | 轻量多模态模型，支持图文理解与高效任务处理                                    |
| 语音合成 | SenseNova-TTS-2.0           | `sensenova-tts-2.0`                                                        | 推荐版本，多情绪、多风格、支持克隆与文生音色                                   |
| 语音合成 | SenseAudio-TTS-1.5          | `senseaudio-tts-1.5-260319`                                                | 多情绪、多风格、多音字纠正、公式朗读                                       |
| 语音识别 | SenseAudio-ASR-1.5 系列       | `senseaudio-asr-1.5-260319` 等                                              | Lite / 1.5 / Pro / DeepThink / Check 五档                  |
| 音频处理 | SenseAudio Voice Isolation  | `senseaudio-voice-isolation-1.0-260319` / `senseaudio-voice-isolation-1.5` | 人声分离，支持同步与异步处理                                           |
| 音频处理 | SenseNova-LiveTranslate-1.0 | `sensenova-livetranslate-1.0`                                              | 同声传译，按音频时长计费                                             |
| 音频处理 | SenseAudio-A1               | `senseaudio-a1`                                                            | 音频生成，按生成音频时长计费                                           |
| 音乐生成 | SenseAudio-Music-1.0        | `senseaudio-music-1.0-260319`                                              | 歌词生成与完整歌曲合成                                              |
| 音乐生成 | SenseAudio-Music-2.0        | `senseaudio-music-2.0-260626`                                              | 新一代完整歌曲生成模型                                              |
| 音效生成 | SenseAudio-Sound-Effect-1.0 | `senseaudio-sfx-1.0-260626`                                                | 音效生成，0.08 元 / 组                                          |
| 图片生成 | SenseAudio-Image-2.0        | `senseaudio-image-2.0-260319`                                              | 自研图片生成最新版本                                               |
| 图片生成 | SenseAudio-Image-1.0        | `senseaudio-image-1.0-260319`                                              | 常规尺寸图片生成，同步与异步调用                                         |
| 图片生成 | SenseNova-U1-Fast           | `sensenova-u1-fast`                                                        | 基于 SenseNova U1 的加速版本，理解与生成一体，面向信息图生成优化，擅长高密度信息表达与丰富版式排版 |

### 其他厂商

| 模态   | 模型名称                     | 模型 ID                        | 说明                            |
| ---- | ------------------------ | ---------------------------- | ----------------------------- |
| 文本生成 | Qwen3.8-27B              | `qwen3.8-27b`                | 通义千问 3.8，1M 上下文               |
| 文本生成 | DeepSeek-V4-Flash-0731   | `deepseek-v4-flash-0731`     | DeepSeek V4 高吞吐版，1M 上下文       |
| 文本生成 | Qwen3.6-35B-A3B          | `qwen3.6-35b-a3b`            | 通义千问 3.6 MoE，高吞吐推理            |
| 文本生成 | Kimi K2.6                | `kimi-k2.6`                  | Moonshot Kimi，256K 上下文        |
| 文本生成 | GLM-5.3-Flash            | `glm-5.3-flash`              | 智谱 GLM-5.3-Flash ，1M 上下文      |
| 文本生成 | GLM-5.2                  | `glm-5.2`                    | 智谱 GLM-5.2，按输入长度阶梯计费          |
| 文本生成 | MiniMax-M2.7             | `minimax-m2.7`               | MiniMax M2.7，长文本场景            |
| 文本生成 | Doubao-Seed-2.0-Pro      | `doubao-seed-2-0-pro-260215` | 字节豆包，按输入长度阶梯计费                |
| 视频生成 | Doubao-Seedance-2.0      | `doubao-seedance-2-0-260128` | 480P / 720P / 1080P 三档分辨率视频生成 |
| 图片生成 | Doubao-Seedream-5.0-Lite | `doubao-seedream-5-0-260128` | 字节豆包图片生成                      |

## 用量额度

Token Plan 采用**共享积分池**，所有模型统一按积分计费（**1 元 = 5,000 积分**），并叠加 5 小时 / 每周 / 月度三层滑动窗口与并发上限。

### 档位与额度

| 档位            | 月费     |    月度积分 |    5 小时窗口 |      每周上限 | 并发请求 |
| :------------ | :----- | ------: | --------: | --------: | :--: |
| **Pro**（入门）   | ¥199   |   224 万 |    64,000 |   448,000 |  5 路 |
| **Max**（推荐）   | ¥699   | 1,120 万 |   320,000 | 2,240,000 | 10 路 |
| **Ultra**（团队） | ¥1,899 | 4,480 万 | 1,280,000 | 8,960,000 | 20 路 |

### 特色权益

* **Pro**：适合个人开发者与日常编码、实验，全量 14 款旗舰模型随心切换
* **Max**：适合主力开发与 Agent 长时运行，**SLA 99.98% · 优先调度**
* **Ultra**：适合团队生产负载与高并发 Agent 集群，**企业级 SRE · 合规报告**

<Info>
  **额度说明**

  * **所有模型共享同一积分池**，任一调用都从当前档位的积分中扣减。
  * **SenseAudio S2系列及接入的第三方 LLM（DeepSeek / Qwen / Kimi / GLM / MiniMax / Doubao 等）** 按每次请求消耗的 Token 折算积分扣减。
  * **Music** 按次按固定积分扣减；**Video** 按视频时长 × 分辨率档位扣减积分。
  * **TTS / STT / Image**：不限次数，按 **RPM（每分钟请求数）** 限流，仅扣积分。
  * 5 小时 / 每周 / 月度任一窗口达上限后，可开启 **Extra Usage**，超出部分自动按量计费、从账户积分余额扣除，无需更换 API Key。
</Info>

<Note>
  具体价格与等级权益请见 [SenseAudio 官网](https://senseaudio.cn/) 顶部导航的 **Token Plan** 页面。
</Note>

## 两步开通

只需两步即可开始使用：

1. **订阅套餐**：进入 [SenseAudio 官网](https://senseaudio.cn/)，点击顶部导航的 **Token Plan**，页面滚动到套餐区域后选择 **Pro / Max / Ultra** 完成支付。
2. **获取 API Key**：切换到 [SenseAudio API 平台](https://senseaudio.cn/api-platform/home)，在 **API 密钥** 中新增 API Key 即可用于所有调用。

详细路径、截图与首个请求示例请见 [快速接入](/guides/token-plan/quickstart)。

<Card title="快速接入指南" icon="rocket" href="/guides/token-plan/quickstart">
  5 分钟完成订阅、密钥获取与首次调用（含截图与多语言代码示例）。
</Card>

## 在主流工具中使用

获取 API Key 后，选择您常用的工具进行接入：

<CardGroup>
  <Card title="Claude Code" icon="wand-magic-sparkles" href="/guides/token-plan/claude-code" />

  <Card title="Cursor" icon="arrow-pointer" href="/guides/token-plan/cursor" />

  <Card title="Trae" icon="layer-group" href="/guides/token-plan/trae" />

  <Card title="Zed" icon="pen-nib" href="/guides/token-plan/zed" />

  <Card title="Codex CLI" icon="terminal" href="/guides/token-plan/codex-cli" />

  <Card title="Grok CLI" icon="terminal" href="/guides/token-plan/grok-cli" />

  <Card title="Droid" icon="robot" href="/guides/token-plan/droid" />

  <Card title="Cline" icon="code" href="/guides/token-plan/cline" />

  <Card title="Roo Code" icon="rocket" href="/guides/token-plan/roo-code" />

  <Card title="Kilo Code" icon="bolt" href="/guides/token-plan/kilo-code" />

  <Card title="OpenCode" icon="folder-open" href="/guides/token-plan/opencode" />

  <Card title="MonkeyCode" icon="briefcase" href="/guides/token-plan/monkeycode" />
</CardGroup>

## 达到额度上限后

5 小时 / 每周 / 月度任一滑动窗口额度用尽时：

1. **开启 Extra Usage**：在 SenseAudio API 平台打开 Extra Usage 开关，超出部分自动按量计费、从账户积分余额扣除，无需更换 API Key。
2. **等待窗口恢复**：对应窗口会随时间自动滚动释放最早消耗的额度。
3. **升级套餐**：随时升级到更高等级（Pro → Max → Ultra），立即生效。

## 相关资源

<CardGroup>
  <Card title="快速接入" icon="rocket" href="/guides/token-plan/quickstart">
    5 分钟完成 API Key 创建与首个请求。
  </Card>

  <Card title="模型使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    掌握 SenseAudio S2 系列的高效 Prompt 模式。
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# 快速接入
Source: https://docs.senseaudio.cn/guides/token-plan/quickstart

订阅 Token Plan、获取 API Key 并完成首个模型调用

本页引导您在 5 分钟内完成 Token Plan 的订阅、密钥获取，并通过 OpenAI 兼容接口完成首个调用。SenseAudio 自研提供 **S2 系列（旗舰 / Flash / Lite）**，默认示例以 **SenseAudio-S2**（`senseaudio-s2`）为例。

## 开始使用

<Steps>
  <Step title="订阅 Token Plan">
    进入 [SenseAudio 官网](https://senseaudio.cn/)，在顶部导航点击 **Token Plan**。

    <Frame>
      <img alt="SenseAudio 官网顶部导航 · Token Plan 入口" />
    </Frame>

    页面滚动到套餐区域，按需求选择 **Pro（¥199）/ Max（¥699）/ Ultra（¥1,899）** 任一档位，点击「开始」按钮完成支付。

    <Frame>
      <img alt="Token Plan 套餐卡片 · Pro / Max / Ultra" />
    </Frame>
  </Step>

  <Step title="获取 API Key">
    支付完成后，在官网顶部导航点击 **API 平台**，在下拉菜单的 **开发者** 区域选择 **API 密钥**，进入API密钥页面

    <Frame>
      <img alt="左上角工作区切换到 SenseAudio API" />
    </Frame>

    进入 API 密钥页面后，点击右上角的 **+ 创建新密钥**，复制生成的 Key 并妥善保存。该 Key 可直接用于 Token Plan 的模型调用。

    <Frame>
      <img alt="API 密钥 · 新增 API Key" />
    </Frame>

    <Warning>
      **重要提示**

      * 套餐额度用尽或达到限制后，可开启 **Extra Usage**，超出部分自动按量计费、从账户积分余额扣费。
      * API Key 仅展示一次，强烈建议立即设置为环境变量：

      ```bash theme={null}
      export SENSEAUDIO_API_KEY="sk-xxxxxx"
      ```

      * 请勿提交到公共仓库或泄露给他人。
    </Warning>
  </Step>

  <Step title="测试首个请求">
    SenseAudio Token Plan 提供 **OpenAI 兼容**接口，示例以 **SenseAudio-S2**（`senseaudio-s2`）为例，替换 `model` 字段即可切换到 **S2-Flash**（`senseaudio-s2-flash`）、**S2-Lite**（`senseaudio-s2-lite`）、**VL-1.0**（`senseaudio-vl-1.0-260319`）、**VL-Lite-1.0**（`senseaudio-vl-lite-1.0-260319`）或第三方模型（如 `glm-5.2` / `minimax-m2.7` / `qwen3.8-27b` / `deepseek-v4-flash-0731` 等）。

    <Tabs>
      <Tab title="OpenAI 兼容（推荐）">
        Base URL：`https://api.senseaudio.cn/v1`

        <CodeGroup>
          ```bash cURL theme={null}
          curl https://api.senseaudio.cn/v1/chat/completions \
            -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "model": "senseaudio-s2",
              "messages": [
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": "用一句话介绍你自己。"}
              ]
            }'
          ```

          ```python Python theme={null}
          # pip install openai
          from openai import OpenAI

          client = OpenAI(
              api_key="<SENSEAUDIO_API_KEY>",
              base_url="https://api.senseaudio.cn/v1",
          )

          resp = client.chat.completions.create(
              model="senseaudio-s2",
              messages=[
                  {"role": "system", "content": "You are a helpful assistant."},
                  {"role": "user", "content": "用一句话介绍你自己。"},
              ],
          )
          print(resp.choices[0].message.content)
          ```

          ```javascript Node.js theme={null}
          // npm install openai
          import OpenAI from "openai";

          const client = new OpenAI({
            apiKey: process.env.SENSEAUDIO_API_KEY,
            baseURL: "https://api.senseaudio.cn/v1",
          });

          const resp = await client.chat.completions.create({
            model: "senseaudio-s2",
            messages: [
              { role: "system", content: "You are a helpful assistant." },
              { role: "user", content: "用一句话介绍你自己。" },
            ],
          });

          console.log(resp.choices[0].message.content);
          ```

          ```go Go theme={null}
          // go get github.com/sashabaranov/go-openai
          package main

          import (
              "context"
              "fmt"
              "os"

              "github.com/sashabaranov/go-openai"
          )

          func main() {
              config := openai.DefaultConfig(os.Getenv("SENSEAUDIO_API_KEY"))
              config.BaseURL = "https://api.senseaudio.cn/v1"
              client := openai.NewClientWithConfig(config)

              resp, err := client.CreateChatCompletion(
                  context.Background(),
                  openai.ChatCompletionRequest{
                      Model: "senseaudio-s2",
                      Messages: []openai.ChatCompletionMessage{
                          {Role: openai.ChatMessageRoleSystem, Content: "You are a helpful assistant."},
                          {Role: openai.ChatMessageRoleUser, Content: "用一句话介绍你自己。"},
                      },
                  },
              )
              if err != nil {
                  fmt.Println("请求失败:", err)
                  return
              }
              fmt.Println(resp.Choices[0].Message.Content)
          }
          ```

          ```java Java theme={null}
          import java.net.URI;
          import java.net.http.HttpClient;
          import java.net.http.HttpRequest;
          import java.net.http.HttpResponse;

          public class QuickStart {
              public static void main(String[] args) throws Exception {
                  String apiKey = System.getenv("SENSEAUDIO_API_KEY");
                  String body = """
                      {
                        "model": "senseaudio-s2",
                        "messages": [
                          {"role": "system", "content": "You are a helpful assistant."},
                          {"role": "user", "content": "用一句话介绍你自己。"}
                        ]
                      }
                      """;

                  HttpRequest request = HttpRequest.newBuilder()
                      .uri(URI.create("https://api.senseaudio.cn/v1/chat/completions"))
                      .header("Authorization", "Bearer " + apiKey)
                      .header("Content-Type", "application/json")
                      .POST(HttpRequest.BodyPublishers.ofString(body))
                      .build();

                  HttpResponse<String> response = HttpClient.newHttpClient()
                      .send(request, HttpResponse.BodyHandlers.ofString());

                  System.out.println(response.body());
              }
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Responses 风格">
        Endpoint：`https://api.senseaudio.cn/v1/responses`

        <CodeGroup>
          ```bash cURL theme={null}
          curl https://api.senseaudio.cn/v1/responses \
            -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "model": "senseaudio-s2",
              "input": "用一句话介绍你自己。"
            }'
          ```

          ```python Python theme={null}
          # pip install openai
          from openai import OpenAI

          client = OpenAI(
              api_key="<SENSEAUDIO_API_KEY>",
              base_url="https://api.senseaudio.cn/v1",
          )

          resp = client.responses.create(
              model="senseaudio-s2",
              input="用一句话介绍你自己。",
          )
          print(resp.output_text)
          ```

          ```javascript Node.js theme={null}
          // npm install openai
          import OpenAI from "openai";

          const client = new OpenAI({
            apiKey: process.env.SENSEAUDIO_API_KEY,
            baseURL: "https://api.senseaudio.cn/v1",
          });

          const resp = await client.responses.create({
            model: "senseaudio-s2",
            input: "用一句话介绍你自己。",
          });

          console.log(resp.output_text);
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>

  <Step title="接入 AI 编程工具">
    挑选您常用的 AI 编程工具完成配置，即可在实际项目里体验 **SenseAudio Token Plan**。

    <Columns>
      <Card title="Claude Code" icon="wand-magic-sparkles" href="/guides/token-plan/claude-code" />

      <Card title="Cursor" icon="arrow-pointer" href="/guides/token-plan/cursor" />

      <Card title="Trae" icon="layer-group" href="/guides/token-plan/trae" />
    </Columns>

    <Columns>
      <Card title="Zed" icon="pen-nib" href="/guides/token-plan/zed" />

      <Card title="Codex CLI" icon="terminal" href="/guides/token-plan/codex-cli" />

      <Card title="Grok CLI" icon="terminal" href="/guides/token-plan/grok-cli" />
    </Columns>

    <Columns>
      <Card title="Droid" icon="robot" href="/guides/token-plan/droid" />

      <Card title="Cline" icon="code" href="/guides/token-plan/cline" />

      <Card title="Roo Code" icon="rocket" href="/guides/token-plan/roo-code" />
    </Columns>

    <Columns>
      <Card title="Kilo Code" icon="bolt" href="/guides/token-plan/kilo-code" />

      <Card title="OpenCode" icon="folder-open" href="/guides/token-plan/opencode" />

      <Card title="MonkeyCode" icon="briefcase" href="/guides/token-plan/monkeycode" />
    </Columns>
  </Step>
</Steps>

## 最佳实践

<Columns>
  <Card title="模型使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    SenseAudio S2 系列的高效 Prompt 模式、长任务推理与状态跟踪。
  </Card>

  <Card title="常见工作流" icon="diagram-project" href="/guides/token-plan/common-workflows">
    Step-by-step 任务模板，把 Agent 用熟。
  </Card>
</Columns>


# Roo Code
Source: https://docs.senseaudio.cn/guides/token-plan/roo-code

在 Roo Code 中使用 S2 模型进行 AI 编程

## 概述

[Roo Code](https://roocode.com/) 是一款运行在 VS Code 中的开源 AI 编程扩展，通过侧边栏对话、文件感知与工具调用，让开发者在 IDE 内完成生成、重构与调试。本文将指导你把 SenseAudio [Token Plan](https://senseaudio.cn/tokenplan) 接入 Roo Code，享受 S2 模型的编码能力。

<CardGroup>
  <Card title="IDE 深度集成" icon="code">
    直接嵌入 VS Code 侧边栏，无需离开编辑器。
  </Card>

  <Card title="OpenAI 兼容接入" icon="plug">
    通过 OpenAI Compatible 接入 SenseAudio Token Plan。
  </Card>

  <Card title="免账号即用" icon="user-slash">
    无需注册 Roo Code 账号，本地配置即可开始使用。
  </Card>

  <Card title="上下文感知" icon="folder-tree">
    自动读取项目文件，理解代码上下文后再输出。
  </Card>
</CardGroup>

## 前提条件

<CardGroup>
  <Card title="Token Plan" icon="credit-card" href="https://senseaudio.cn/tokenplan">
    已订阅 SenseAudio Token Plan
  </Card>

  <Card title="VS Code" icon="code" href="https://code.visualstudio.com/">
    已安装最新版 VS Code
  </Card>
</CardGroup>

## 安装 Roo Code

<Steps>
  <Step title="打开扩展面板">
    在 VS Code 左侧活动栏点击 **扩展** 图标（或按下 `Cmd/Ctrl+Shift+X`）。
  </Step>

  <Step title="搜索并安装">
    在搜索框中输入 `Roo Code`，在结果中点击 **Install**。安装完成后建议重启一次 VS Code。
  </Step>
</Steps>

<Frame>
  <img alt="在 VS Code 扩展市场搜索并安装 Roo Code" />
</Frame>

## 配置 SenseAudio API

<Steps>
  <Step title="打开 Roo Code 面板">
    安装完成后，左侧活动栏会出现 **袋鼠图标**，点击它展开 Roo Code 面板。

    <Frame>
      <img alt="在 VS Code 左侧活动栏点击袋鼠图标" />
    </Frame>
  </Step>

  <Step title="跳过账号登录">
    在欢迎页点击 **Or use without account**，直接进入本地使用模式，无需注册。
  </Step>

  <Step title="填写 Provider 信息">
    按下表填写模型服务配置：

    | 配置项          | 值                              |
    | ------------ | ------------------------------ |
    | API Provider | `OpenAI Compatible`            |
    | Base URL     | `https://api.senseaudio.cn/v1` |
    | API Key      | 您的 Token Plan API Key          |
    | Model        | `senseaudio-s2`                |

    <Note>
      API Key 可在 [快速接入](/guides/token-plan/quickstart) 中获取。
    </Note>

    填写完成后，点击下方 **完成** 按钮保存配置。

    <Frame>
      <img alt="填写 Roo Code Provider 参数" />
    </Frame>
  </Step>

  <Step title="开始对话">
    返回 Roo Code 主面板，即可用 S2 模型处理编码任务。

    <Frame>
      <img alt="Roo Code 主面板开始对话" />
    </Frame>
  </Step>
</Steps>

<Tip>
  **模型选择建议**：复杂重构或架构设计可切换到 `senseaudio-s2`；日常高频编码使用 `senseaudio-s2-flash` 可获得更快的响应速度。
</Tip>

## 相关资源

<CardGroup>
  <Card title="Cline" icon="code" href="/guides/token-plan/cline">
    另一款热门的 VS Code AI 编程扩展
  </Card>

  <Card title="Kilo Code" icon="zap" href="/guides/token-plan/kilo-code">
    轻量级 VS Code AI 编程扩展
  </Card>

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices">
    发挥 S2 模型最佳效果
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Trae
Source: https://docs.senseaudio.cn/guides/token-plan/trae

在 Trae 中使用 S2 模型进行 AI 编程

## 安装 Trae

<Steps>
  <Step title="下载并安装">
    访问 [Trae 官网](https://www.trae.cn/) 下载并安装。
  </Step>

  <Step title="完成初始设置">
    Trae 首次启动时按指引完成初始设置。
  </Step>

  <Step title="登录 Trae">
    使用已有账号登录。
  </Step>
</Steps>

## 使用自定义模型接入 SenseAudio

Trae 支持通过 **API Key** 接入自定义模型。

<Steps>
  <Step title="打开设置">
    在 AI 对话框右上角点击 **设置** 图标。
  </Step>

  <Step title="选择模型页签">
    <img />
  </Step>

  <Step title="添加模型">
    <img />
  </Step>

  <Step title="填写配置信息">
    | 配置项         | 值                                                                 |
    | ----------- | ----------------------------------------------------------------- |
    | **服务商**     | `openai`                                                          |
    | **模型**      | `自定义模型`                                                           |
    | **模型ID**    | `senseaudio-s2`                                                   |
    | **API秘钥**   | `您的 Token Plan API Key（详见 [快速接入](/guides/token-plan/quickstart)）` |
    | **自定义请求地址** | `https://api.senseaudio.cn/v1/chat/completions`                   |

    <img />
  </Step>

  <Step title="选择SenseAudio模型">
    <img />
  </Step>

  <Step title="使用模型">
    <img />
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="Claude Code 接入" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# Zed
Source: https://docs.senseaudio.cn/guides/token-plan/zed

在 Zed 中使用 S2 模型进行 AI 编程

## 安装 Zed

按照 [Zed 官方文档](https://zed.dev/docs/) 完成 Zed 安装配置。

## 配置 SenseAudio API

<Steps>
  <Step title="进入智能体面板">
    点击右下角 ✨ 图标进入智能体面板。

    <img />
  </Step>

  <Step title="进入配置页面">
    点击右上角三点按钮进入 configure。

    <img />
  </Step>

  <Step title="添加 LLM Provider">
    找到 **LLM Provider** 模块，点击 **+ Add Provider**，在下拉框中选择 **OpenAI**。

    <img />
  </Step>

  <Step title="填写配置信息">
    | 配置项               | 值                                                                 |
    | ----------------- | ----------------------------------------------------------------- |
    | **Provider Name** | `SenseAudio`（自定义）                                                 |
    | **API URL**       | `https://api.senseaudio.cn/v1`                                    |
    | **API Key**       | `您的 Token Plan API Key（详见 [快速接入](/guides/token-plan/quickstart)）` |
    | **Model Name**    | `senseaudio-s2`                                                   |

    <img />
  </Step>

  <Step title="保存配置">
    点击 **Save Provider**。LLM Provider 列表中出现 SenseAudio。

    <img />
  </Step>

  <Step title="选择模型并使用">
    返回智能体面板，点击右下角 **Select a Model**，选择刚配置的 `senseaudio-s2`。

    <img />
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="Claude Code 接入" icon="sparkles" href="/guides/token-plan/claude-code" />

  <Card title="S2 使用技巧" icon="lightbulb" href="/guides/token-plan/best-practices" />

  <Card title="常见问题" icon="circle-question" href="/guides/token-plan/faq">
    订阅、限额、切换、开票等问题解答。
  </Card>
</CardGroup>


# 语音合成介绍
Source: https://docs.senseaudio.cn/guides/tts/overview

SenseAudio 语音合成能力、音色生态与接入建议

SenseAudio 语音合成服务以 **70+ 官方精品音色** 为基础，配合 **音色克隆**、**文生音色** 与统一的 **音色管理** 接口，形成从音色生产到语音输出的一体化能力。所有系统音色或自定义音色最终都通过唯一的 `voice_id` 传入 [语音合成 API](/api-reference/endpoint/tts/synthesize) 使用，支持精细化控制与流式输出，适用于各类智能交互与内容生产场景。

## 语音合成核心特性

### 强大、富有情感的语音合成

基于深度学习技术，提供接近真人的语音合成体验：

* **情感丰富**：支持开心、悲伤、生气、撒娇等 10+ 种情感表达。
* **风格多样**：覆盖客服、广告、播客、有声书、新闻资讯等专业场景。
* **多音字控制**：支持自定义中文多音字的读音。（仅限 senseaudio-tts-1.5-260319）
* **公式朗读**：支持口语化朗读公式（需以 LaTeX 格式输入公式）。

### 模型版本说明

SenseAudio 提供多版本语音合成模型：

* **senseaudio-tts-1.5-260319**：支持自定义多音字读音。（支持克隆音色及文生音色的文本转语音功能）
* **sensenova-tts-2.0**：情绪表现力更强，读音准确率更高。（支持克隆音色及文生音色的文本转语音功能）

### 毫秒级流式响应

专为实时交互设计的高性能架构：

* **超低延迟**：首包延迟 \< 500ms，满足实时对话需求。
* **流式输出**：支持 Server-Sent Events (SSE) 与 WebSocket 双协议，边合成边播放。

### 高并发支撑

* **万卡集群**：轻松应对亿级调用，保障业务高峰期服务连续性。

### 精细化语音控制

提供丰富的参数调节，满足个性化需求：

| 参数        | 说明   | 范围            | 步进值  | 典型应用                |
| --------- | ---- | ------------- | ---- | ------------------- |
| **speed** | 语速调节 | \[0.5, 2.0]   | 0.01 | 0.8 (抒情) / 1.5 (快速) |
| **vol**   | 音量调节 | \[0.01, 10.0] | 0.01 | 环境适配 / 重点强调         |
| **pitch** | 声调调节 | \[-12, 12]    | 1    | 角色变声 / 情绪微调         |

## 音频规格

支持多种主流音频格式与采样率，适配不同终端设备：

* **格式**：**mp3** (推荐)、**wav**、**pcm**、**flac**
* **采样率**：**32000Hz**（推荐）；其他支持 **8000Hz**、**16000Hz**、**22050Hz**、**24000Hz**、**44100Hz**

## 音色能力矩阵

SenseAudio 在 TTS 之外，还提供一整套音色生态能力，帮助您获得开箱即用或高度定制的音色。

| 能力   | 场景                  | 入口                                 |
| :--- | :------------------ | :--------------------------------- |
| 系统音色 | 开箱即用的官方精品音色（70+）    | [音色列表](/guides/voice/catalog)      |
| 音色克隆 | 录制 3–30 秒参考音频复刻个人音色 | [自定义音色](/guides/voice/custom#音色克隆) |
| 文生音色 | 通过自然语言描述生成全新音色      | [自定义音色](/guides/voice/custom#文生音色) |

<Note>
  文生音色与音色克隆共用同一组生成次数额度，次数额度由套餐等级决定。
</Note>

## 接入流程

<Steps>
  <Step title="查询可用音色">
    通过 [查询可用音色](/api-reference/endpoint/voice/list) 接口获取当前账号可调用的 `voice_id` 列表。
  </Step>

  <Step title="选择或生成音色">
    在 [音色广场](https://senseaudio.cn/workspace/sound-library) 挑选系统音色，或通过克隆 / 文生流程生成自定义音色，确认 `voice_id`。
  </Step>

  <Step title="合成语音">
    在 [语音合成 API](/api-reference/endpoint/tts/synthesize) 中传入 `voice_id` 即可；需要边生成边播放时，改用 [流式语音合成 API](/api-reference/endpoint/tts/synthesize-stream) 或者 [WebSocket 语音合成 API](/api-reference/endpoint/tts/websocket)。
  </Step>
</Steps>

## 接入建议

* **首次接入**：建议先阅读 [快速接入指南](/guides/account/quick-access)，使用可直接生成 `output.mp3` 的示例快速完成首个请求。
* **同步合成**：适合标准语音合成场景，参考 [语音合成 API](/api-reference/endpoint/tts/synthesize)。
* **流式合成**：适合实时对话与边生成边播放场景，参考 [流式语音合成 API](/api-reference/endpoint/tts/synthesize-stream) 或者 [WebSocket 语音合成 API](/api-reference/endpoint/tts/websocket)。

## 相关资源

<CardGroup>
  <Card title="语音合成 HTTP" icon="waveform-lines" href="/api-reference/endpoint/tts/synthesize">
    同步语音合成接口参数详解。
  </Card>

  <Card title="语音合成 WebSocket" icon="zap" href="/api-reference/endpoint/tts/websocket">
    WebSocket 协议的完整说明与示例。
  </Card>

  <Card title="音色列表" icon="list" href="/guides/voice/catalog">
    系统音色清单与套餐可调用范围。
  </Card>

  <Card title="自定义音色" icon="user-music" href="/guides/voice/custom">
    音色克隆与文生音色的使用流程。
  </Card>
</CardGroup>


# 视频生成介绍
Source: https://docs.senseaudio.cn/guides/video/overview

视频生成能力总览

SenseAudio 视频生成服务面向短视频创作、营销素材制作、内容可视化和创意分镜生成等场景，提供统一的视频生成 API。开发者可以通过文本描述或图像参考快速创建视频任务，并通过状态查询接口获取生成进度与最终结果。

## 什么是视频生成

视频生成能力支持从文字或图片描述中自动生成短视频内容，适合用于创意预演、广告素材生成和内容工业化生产。

**核心能力**：

* **文生视频**：通过自然语言提示词直接生成视频
* **图生视频**：支持参考图、首帧图、首尾帧图约束视频生成
* **多模视频**：支持参考图、参考视频、参考音频用于视频生成
* **参数可控**：支持设置时长、分辨率、宽高比和模型专属参数
* **任务式生成**：通过任务创建 + 状态查询完成完整生成流程

## 模型版本

当前视频生成模块已明确支持以下模型：

| 模型             | 特点                           | 适用场景            |
| :------------- | :--------------------------- | :-------------- |
| `Seedance-2.0` | 支持文生视频、首尾帧生视频、参考图生视频、多模态生成视频 | 短视频创作、动画创作、商业素材 |

## API 能力概览

SenseAudio 视频生成提供以下核心 API 接口：

### 1. 创建视频生成任务

用于提交视频生成任务，支持文本生成视频、图生视频等模式。

* 文档：**[创建视频生成任务](/api-reference/endpoint/video/create)**
* 接口地址：`POST https://api.senseaudio.cn/v1/video/create`

### 2. 查询视频生成状态

用于根据任务 ID 查询当前进度、状态和最终生成结果。

* 文档：**[查询视频生成状态](/api-reference/endpoint/video/status)**
* 接口地址：`GET https://api.senseaudio.cn/v1/video/status`

## 参数建议

| 参数           | 建议                                        | 说明           |
| :----------- | :---------------------------------------- | :----------- |
| `content`    | 文本描述尽量包含主体、动作、场景和风格                       | 有助于提升结果稳定性   |
| `ratio`      | 根据投放渠道选择 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`  | 横屏、竖屏场景对应不同  |
| `resolution` | 对视频生成速度有要求使用 `720p`，对视频清晰度有更高要求使用 `1080p` | 兼顾生成速度与清晰度   |
| `duration`   | 先用较短时长测试，再放大                              | 更适合快速验证提示词效果 |

## 计费说明

请参考 **[计费规则](/guides/account/billing)**。

## 典型应用场景

### 短视频内容制作

用于生成营销短片、产品展示视频、账号运营视频等高频视觉内容。

### 广告创意预演

在正式拍摄或外包制作之前，先快速验证创意分镜、画面风格与节奏方向。

### 电商与品牌宣传

结合商品卖点、品牌风格和活动文案，快速生成适合推广投放的视频素材。

## 开始使用

<Steps>
  <Step title="获取 API Key">
    前往 [API 密钥](https://senseaudio.cn/api-platform/api-key) 创建您的 API Key。
  </Step>

  <Step title="组织提示词或准备参考图">
    按照主体、动作、场景、风格组织文本描述，或准备首帧、末帧、参考图素材。
  </Step>

  <Step title="创建视频任务">
    调用 [创建视频生成任务](/api-reference/endpoint/video/create) 提交生成请求，记录返回的 `task_id` 用于后续状态查询。
  </Step>

  <Step title="轮询并获取结果">
    调用 [查询视频生成状态](/api-reference/endpoint/video/status) 轮询当前状态，任务完成后获取视频 URL、缩略图与 GIF 预览。
  </Step>
</Steps>

## 相关资源

<CardGroup>
  <Card title="创建视频任务" icon="video" href="/api-reference/endpoint/video/create">
    提交文生视频或图生视频任务。
  </Card>

  <Card title="查询视频状态" icon="clock" href="/api-reference/endpoint/video/status">
    根据 `task_id` 获取生成进度与结果。
  </Card>

  <Card title="计费规则" icon="credit-card" href="/guides/account/billing">
    查看视频生成的积分消耗规则。
  </Card>
</CardGroup>


# 人声分离介绍
Source: https://docs.senseaudio.cn/guides/voice-isolation/overview

使用人声分离接口从音频中提取人声轨道

人声分离能力可从上传音频中分离人声轨道，适用于音频后期处理、素材清洗、语音内容分析前处理等场景。

## 接入方式

<CardGroup>
  <Card title="同步人声分离" icon="headphones" href="/api-reference/endpoint/voice-isolation/sync">
    上传音频并等待处理完成，接口直接返回分离结果 URL。
  </Card>

  <Card title="异步人声分离" icon="clock" href="/api-reference/endpoint/voice-isolation/async">
    上传音频并创建任务，适合不希望长时间保持 HTTP 连接的场景。
  </Card>

  <Card title="查询任务结果" icon="magnifying-glass" href="/api-reference/endpoint/voice-isolation/pending">
    使用 `task_id` 查询任务状态，并在完成后获取 `result_url`。
  </Card>
</CardGroup>

## 推荐流程

1. 对于短音频或需要直接拿到结果的场景，调用[同步人声分离](/api-reference/endpoint/voice-isolation/sync)。
2. 对于耗时较长或需要后台处理的场景，调用[异步人声分离](/api-reference/endpoint/voice-isolation/async)创建任务。
3. 异步任务创建成功后，使用[查询人声分离任务](/api-reference/endpoint/voice-isolation/pending)轮询任务状态。

## 模型

| 模型 ID                                   | 说明     |
| --------------------------------------- | ------ |
| `senseaudio-voice-isolation-1.0-260319` | 人声分离模型 |
| `senseaudio-voice-isolation-1.5`        | 人声分离模型 |

## 音频要求

* 上传字段固定为 `file`
* 支持的音频格式、时长与文件大小限制以服务端校验规则为准
* 当文件不符合模型要求或音频格式非法时，服务端将返回 `400`


# 音色列表
Source: https://docs.senseaudio.cn/guides/voice/catalog

系统音色清单、套餐可调用音色范围与定制服务

SenseAudio 提供 70+ 官方精品音色，覆盖社交、内容创作、客服、教育、营销等典型场景。本页面同时说明套餐等级与可调用音色的对应规则、额外权益与定制服务申请流程，帮助您根据业务需求选择合适的 `voice_id`。

## 音色库概览

### 基本信息

* **官方精品音色**：70+ 个
* **支持语言**：中文（普通话）
* **情绪类型**：平稳、开心、低落、撒娇、生气、深情、严肃、委屈、傲娇等
* **更新频率**：持续扩充

### 应用场景分类

**社交互动**\
适用于社交应用、语音聊天、虚拟伴侣等场景。代表音色：撒娇甜妹、深情男友、温柔月光、阳光甜弟等。

**内容创作**\
适用于播客、有声书、短视频配音等场景。代表音色：播客才女、电台女声、书香才女、儒雅道长等。

**客服助手**\
适用于智能客服、语音导航、AI 助手等场景。代表音色：温柔御姐、可靠大叔、专业女播等。

**教育培训**\
适用于在线教育、课程讲解、儿童故事等场景。代表音色：可爱萌娃、知心少女、可靠青叔等。

**营销推广**\
适用于广告配音、直播带货、产品介绍等场景。代表音色：亢奋主播、带货女神、专业女播等。

## 快速选择指南

### 按使用场景选择

| 场景            | 推荐音色 ID         | 音色名称 | 特点                                 |
| ------------- | --------------- | ---- | ---------------------------------- |
| **情感陪伴**      | `female_0023_a` | 羞涩甜妹 | 多情绪单纯少女，声音中透露着可爱的小心翼翼，充满了对事物的好奇和想象 |
| **短视频与内容解说**  | `female_0036_a` | 青春女声 | 多状态积极女声，开朗活泼、言之有物                  |
| **播客电台**      | `female_0038_a` | 亲切女孩 | 多状态亲切女声，好听又甜美                      |
| **有声读物与阅读辅助** | `male_0004_a`   | 儒雅道长 | 自带叙事感的温润大叔声线                       |
| **影视配音与角色扮演** | `female_0018_a` | 森系少女 | 多情绪可爱女声，会害羞，会开心，声音懵懂可爱让人有保护欲       |
| **广告宣传与直播带货** | `female_0030_c` | 高能姐姐 | 拥有开朗性格的成熟女声，具有超强的感染力               |
| **教育与培训**     | `male_0029_a`   | 利落青年 | 多状态硬朗青年，干脆利落不拖泥带水，听起来就让人觉得很安心      |
| **客服与呼叫中心**   | `female_0037_a` | 自然少女 | 模拟真实客服的女声，发音清晰具备真人感                |

### 最佳实践

1. **试听对比** - 先试听多个音色，选择最符合场景的。
2. **情绪搭配** - 根据文本内容选择合适的情绪版本。
3. **参数调优** - 通过 `speed`、`vol`、`pitch` 参数微调音色表现。
4. **保持一致** - 同一应用中保持音色风格一致。

**参数调节示例：**

```json theme={null}
// 让音色更加活泼
{
  "voice_id": "female_0004_a",  // 乐天女孩
  "speed": 1.1,
  "vol": 1.2,
  "pitch": 1
}

// 让音色更加沉稳
{
  "voice_id": "male_0003_a",  // 暴躁大叔
  "speed": 0.95,
  "vol": 1.0,
  "pitch": -1
}
```

## 系统音色清单

您可以使用 `voice_id` 列中的值进行 API 调用。

| **序号** | **语言**  | **音色 ID (Voice ID)**                                                                                                                                               | **音色名称 (Voice Name)** |
| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| 1      | 中文(普通话) | `male_0029_a` (内容剖析)<br />`male_0029_b` (开场介绍)<br />`male_0029_c` (广告中插)<br />`male_0029_d` (轻松铺陈)<br />`male_0029_e` (细心提问)<br />`male_0029_f` (主题升华)             | 利落青年                  |
| 2      | 中文(普通话) | `female_0038_a` (平稳通用)<br />`female_0038_b` (温柔讲解)<br />`female_0038_c` (致歉安慰)<br />`female_0038_d` (严肃告知)<br />`female_0038_e` (清晰播报)<br />`female_0038_f` (耐心关怀) | 亲切女孩                  |
| 3      | 中文(普通话) | `female_0037_a` (劝导)<br />`female_0037_b` (委屈)<br />`female_0037_c` (温柔)<br />`female_0037_d` (严肃)<br />`female_0037_e` (平稳)                                       | 自然少女                  |
| 4      | 中文(普通话) | `female_0036_a` (内容剖析)<br />`female_0036_b` (开场介绍)<br />`female_0036_c` (广告中插)<br />`female_0036_d` (轻松铺陈)<br />`female_0036_e` (细心提问)<br />`female_0036_f` (主题升华) | 青春女声                  |
| 5      | 中文(普通话) | `female_0016_a` (开心)<br />`female_0016_b` (低落)<br />`female_0016_c` (傲娇)                                                                                           | 俏皮女孩                  |
| 6      | 中文(普通话) | `male_0025_a` (平稳)<br />`male_0025_b` (严肃)<br />`male_0025_c` (深情)                                                                                                 | 温柔霸总                  |
| 7      | 中文(普通话) | `female_0015_a` (低落)<br />`female_0015_b` (生气)                                                                                                                     | 哭泣少女                  |
| 8      | 中文(普通话) | `female_0011_a` (妩媚)                                                                                                                                               | 美艳女人                  |
| 9      | 中文(普通话) | `male_0017_a` (平稳)                                                                                                                                                 | 温柔青年                  |
| 10     | 中文(普通话) | `female_0030_b` (平稳)                                                                                                                                               | 沉稳帅姐                  |
| 11     | 中文(普通话) | `male_0014_a` (开心)<br />`male_0014_b` (平稳)<br />`male_0014_c` (低落)                                                                                                 | 风流浪子                  |
| 12     | 中文(普通话) | `male_0021_a` (平稳)<br />`male_0021_b` (低落)<br />`male_0021_c` (开心)<br />`male_0021_d` (生气)<br />`male_0021_e` (深情)                                                 | 柔弱公子                  |
| 13     | 中文(普通话) | `female_0012_a` (撒娇)                                                                                                                                               | 刁蛮小姐                  |
| 14     | 中文(普通话) | `male_0008_a` (平稳)                                                                                                                                                 | 霸道男神                  |
| 15     | 中文(普通话) | `male_0022_a` (平稳)                                                                                                                                                 | 阳光少年                  |
| 16     | 中文(普通话) | `female_0030_e` (深情)                                                                                                                                               | 贴心女人                  |
| 17     | 中文(普通话) | `male_0004_a` (平稳)                                                                                                                                                 | 儒雅道长                  |
| 18     | 中文(普通话) | `female_0018_a` (害羞)<br />`female_0018_b` (开心)                                                                                                                     | 森系少女                  |
| 19     | 中文(普通话) | `female_0004_a` (开心)                                                                                                                                               | 乐天女孩                  |
| 20     | 中文(普通话) | `male_0006_a` (平稳)                                                                                                                                                 | 纨绔青年                  |
| 21     | 中文(普通话) | `female_0001_a` (平稳)                                                                                                                                               | 战场指挥                  |
| 22     | 中文(普通话) | `male_0009_a` (平稳)                                                                                                                                                 | 潇洒青叔                  |
| 23     | 中文(普通话) | `female_0030_f` (妩媚)                                                                                                                                               | 心机少女                  |
| 24     | 中文(普通话) | `female_0019_a` (平稳)                                                                                                                                               | 冷艳御姐                  |
| 25     | 中文(普通话) | `male_0005_a` (平稳)                                                                                                                                                 | 惬意老翁                  |
| 26     | 中文(普通话) | `female_0023_a` (平稳)<br />`female_0023_b` (开心)<br />`female_0023_c` (傲娇)                                                                                           | 羞涩甜妹                  |
| 27     | 中文(普通话) | `female_0030_a` (平稳)                                                                                                                                               | 凌厉御姐                  |
| 28     | 中文(普通话) | `female_0003_a` (傲娇)                                                                                                                                               | 傲娇少女                  |
| 29     | 中文(普通话) | `male_0003_a` (生气)                                                                                                                                                 | 暴躁大叔                  |
| 30     | 中文(普通话) | `child_0001_a` (开心)<br />`child_0001_b` (平稳)                                                                                                                       | 可爱萌娃                  |
| 31     | 中文(普通话) | `female_0017_a` (傲娇)<br />`female_0017_b` (平稳)<br />`female_0017_c` (低落)                                                                                           | 冷酷少女                  |
| 32     | 中文(普通话) | `male_0001_a` (平稳)                                                                                                                                                 | 酷痞青年                  |
| 33     | 中文(普通话) | `male_0007_a` (病娇)                                                                                                                                                 | 病娇青年                  |
| 34     | 中文(普通话) | `female_0030_c` (平稳)                                                                                                                                               | 高能姐姐                  |
| 35     | 中文(普通话) | `female_0009_a` (撒娇)                                                                                                                                               | 羞涩少女                  |
| 36     | 中文(普通话) | `male_0020_a` (撒娇)                                                                                                                                                 | 阳光甜弟                  |
| 37     | 中文(普通话) | `male_0018_a` (深情)                                                                                                                                                 | 沙哑青年                  |
| 38     | 中文(普通话) | `male_0011_a` (平稳)                                                                                                                                                 | 冷面霸总                  |
| 39     | 中文(普通话) | `male_0015_a` (严肃)                                                                                                                                                 | 英武老者                  |

## 套餐权限

我们的 API 音色服务围绕 "**基础权益 + 灵活挑选 + 专属定制**" 三大维度构建：您可以使用套餐中包含的 API 基础音色；联系客服购买额外权益，解锁套餐外的 API 音色；或者根据需求定制专属音色。

### 音色等级定义

* **普通音色**：基础通用型音色，满足日常简单语音合成需求，无复杂情感或场景适配优化。
* **VIP 音色**：精品增强型音色，含情感化、行业基础适配音，支持中高端场景使用。
* **SVIP 音色**：旗舰尊享型音色，含专业播音级、特色角色音、行业深度定制音，适配高要求的商业场景。
* **独家定制音色**：通过定制服务生成的专属音色，仅为定制用户独家使用，完全匹配场景诉求（定制版为全流程采集训练，如有需要可联系客服）。

### 订阅套餐内提供 API 调用的音色

（不包含限免活动期间限时使用的音色以及自定义音色）

| 套餐类型                        | 可使用音色等级     | 音色名称 | 音色 ID (voice\_id)                                                                                                                         |
| :-------------------------- | :---------- | :--- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **Free 版（实名认证后默认）**         | **普通音色**    | 可爱萌娃 | `child_0001_a` (开心)、`child_0001_b` (平稳)                                                                                                   |
|                             |             | 儒雅道长 | `male_0004_a` (平稳)                                                                                                                        |
|                             |             | 沙哑青年 | `male_0018_a` (深情)                                                                                                                        |
| **Plus 版**                  | **VIP 音色**  | 亢奋主播 | `male_0027_a` (热情介绍)、`male_0027_b` (卖点解读)、`male_0027_c` (促销逼单)                                                                            |
|                             |             | 撒娇青年 | `male_0023_a` (平稳)                                                                                                                        |
| **Pro 版 / Max 版 / Ultra 版** | **SVIP 音色** | 孔武青年 | `male_0019_a` (平稳)                                                                                                                        |
|                             |             | 嗲嗲台妹 | `female_0033_a` (平稳)、`female_0033_b` (开心)、`female_0033_c` (撒娇)、`female_0033_d` (低落)、`female_0033_e` (委屈)、`female_0033_f` (生气)             |
|                             |             | 乐观少年 | `male_0026_a` (平稳)、`male_0026_b` (开心)、`male_0026_c` (深情)                                                                                  |
|                             |             | 温柔御姐 | `female_0006_a` (深情)                                                                                                                      |
|                             |             | 可靠青叔 | `male_0028_a` (内容剖析)、`male_0028_b` (开场介绍)、`male_0028_c` (广告中插)、`male_0028_d` (轻松铺陈)、`male_0028_e` (细心提问)、`male_0028_f` (主题升华)             |
|                             |             | 魅力姐姐 | `female_0027_a` (平稳)、`female_0027_b` (撒娇)、`female_0027_c` (病娇)、`female_0027_d` (低落)、`female_0027_e` (妩媚)、`female_0027_f` (傲娇)             |
|                             |             | 气质学姐 | `female_0008_a` (生气)、`female_0008_b` (开心)、`female_0008_c` (平稳)                                                                            |
|                             |             | 知心少女 | `female_0035_a` (内容剖析)、`female_0035_b` (开场介绍)、`female_0035_c` (广告中插)、`female_0035_d` (轻松铺陈)、`female_0035_e` (细心提问)、`female_0035_f` (主题升华) |

<PackageVoice />

<PackageClone />

## 挑选音色服务

1. **核心定义**：用户可根据自身需求，联系客服，从官方音色库中挑选想要的音色，根据音色单独定价。
2. **费用说明**：音色挑选均需联系客服洽谈价格，价格根据挑选音色数量、等级、时长等因素综合核定。
3. **生效时效**：价格确认并完成合作流程后，24 小时内完成权限配置，支持即时 API 调取。
4. **申请流程**：联系官方客服，明确音色名称、用途、使用场景及所需数量 → 商务团队核算价格并提供方案 → 双方确认后签订补充协议 → 开通音色权限。

## 独家定制服务

您可以联系官方客服，提出音色定制需求，了解详细的报价信息及音色采集、交付流程。

## 服务咨询与申请入口

* **音色挑选申请**：联系官方客服（在线客服 / 客服电话），洽谈价格及合作细节。
* **独家定制服务咨询**：
  * 联系官方客服（在线客服 / 客服电话）
  * 商务合作邮箱：[senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)

## 相关资源

<CardGroup>
  <Card title="语音合成 API" icon="waveform-lines" href="/api-reference/endpoint/tts/synthesize">
    将 `voice_id` 传入合成接口生成语音。
  </Card>

  <Card title="查询可用音色" icon="list" href="/api-reference/endpoint/voice/list">
    查询当前账号可调用的音色列表。
  </Card>

  <Card title="自定义音色" icon="user-music" href="/guides/voice/custom">
    音色克隆与文生音色使用流程。
  </Card>

  <Card title="语音合成介绍" icon="book-open" href="/guides/tts/overview">
    语音合成能力与接入建议。
  </Card>
</CardGroup>


# 自定义音色
Source: https://docs.senseaudio.cn/guides/voice/custom

音色克隆与文生音色：生成专属 voice_id

除了系统音色外，SenseAudio 提供两种自定义音色生成方式：通过 **参考音频复刻** 的音色克隆，以及通过 **自然语言描述生成** 的文生音色。两者共享同一组生成次数额度，次数额度由套餐等级决定。生成完成后，均可使用对应的 `voice_id` 在 [语音合成 API](/api-reference/endpoint/tts/synthesize-stream) 或 [语音合成 WebSocket API](/api-reference/endpoint/tts/websocket) 中调用。

<Note>
  文生音色与音色克隆共用同一组生成次数额度。每次保存成功会消耗一次额度；是否可直接通过 API 调用，请以文档页展示的 [音色列表](/guides/voice/catalog) 为准。
</Note>

## 音色克隆

音色克隆大模型是基于**全新自研语音大模型算法**打造的高效化、专业级音色定制方案。用户仅需录制几秒音频，即可快速拥有高保真的专属 AI 定制音色。

### 产品优势

* **技术领先**：采用全新自研大模型技术，提供行业领先的复刻精度与情感表现力。
* **超低成本**：仅需录制 **3-30 秒** 音频即可快速复刻，录制门槛极低。
* **高度还原**：1:1 还原真人音色特点、说话风格、口音和声学细节。
* **极速复刻**：数秒完成模型训练与音色生成，即刻拥有高品质 AI 定制音色。

### 使用流程

<Steps>
  <Step title="确认剩余次数">
    剩余生成次数是进行音色克隆的必要条件。每次保存成功会消耗一次额度，生成后的音色在套餐有效期内可用于平台合成或 API 调用。
  </Step>

  <Step title="在平台录制并克隆">
    * **环境要求**：在安静、无回声环境下录制，确保人声纯净。
    * **素材规格**：时长 **3-30 秒**、体积 **50MB** 以内、格式 **MP3/WAV/AAC**。
    * **操作步骤**：
      1. **添加音频**：选择“录制音频”或“上传音频”。
      2. **音色克隆**：保存成功后系统消耗一次生成额度，数秒完成音色克隆。
      3. **管理音色**：在音色列表查看已生成的音色并使用。
  </Step>

  <Step title="通过 API 调用">
    克隆音色 API 暂不支持直接通过接口发起录制请求；请先在平台完成音色复刻，获取 `voice_id` 后，再传入 [语音合成 API](/api-reference/endpoint/tts/synthesize)。
  </Step>
</Steps>

## 文生音色

文生音色功能是基于自研的音色合成模型打造的个性化、无版权风险的 AI 音色解决方案。用户仅需通过自然语言描述，即可定制逼真、自然、符合需求的 AI 音色。

### 适用场景

文生音色能力面向个性化配音、角色语音定制、品牌音色设计等场景，支持通过文本描述快速生成新的专属音色。相比传统录音采集或复杂训练流程，文生音色更适合用于快速创作和批量探索不同声线方案。

### 使用流程

<Steps>
  <Step title="确认剩余次数">
    剩余生成次数是进行音色生成的必要条件。每次保存成功会消耗一次额度，生成后的音色在套餐有效期内可用于平台合成或 API 调用。
  </Step>

  <Step title="在平台完成生成">
    文生音色相关流程以平台侧生成与管理为主，暂不支持通过接口直接生成音色。
  </Step>

  <Step title="通过 API 调用">
    生成完成后，获取唯一 `voice_id` 并传入 [语音合成 API](/api-reference/endpoint/tts/synthesize)。是否可直接通过 API 调用，请以 [音色列表](/guides/voice/catalog) 为准。
  </Step>
</Steps>

## 套餐权益与扩容支持

音色克隆与文生音色共用同一组生成次数额度，次数额度由您的套餐等级决定，并随套餐有效期动态调整。免费生成次数用完后，您也可以按需购买生成次数，价格为 **9.9 元 / 次**。

| **套餐类型**    | **生成次数** | **适用场景**         | **扩容路径**  |
| ----------- | -------- | ---------------- | --------- |
| **Free 版**  | **2 个**  | 基础功能测试与效果预览      | 升级套餐或购买次数 |
| **Lite 版**  | **6 个**  | 个人轻度体验，尝试不同声线    | 升级套餐或购买次数 |
| **Plus 版**  | **10 个** | 满足日常多场景、多角色的配音需求 | 升级套餐或购买次数 |
| **Pro 版**   | **16 个** | 适合高频创作者，建立稳定声线库  | 升级套餐或购买次数 |
| **Max 版**   | **30 个** | 商业化规模应用，支持多场景集成  | 升级套餐或购买次数 |
| **Ultra 版** | **50 个** | 大规模商业化应用与专属需求    | 联系客服定制    |

## 次数不足处理方案

当生成次数不足时，您可以通过以下方式继续使用：

* **查看剩余额度**：您可以在平台查看当前套餐下的剩余生成次数，确认是否还能继续使用文生音色或克隆音色功能。
* **购买次数**：套餐内次数用完后，可按 **9.9 元 / 次** 购买额外次数。若账户内有可用代金券或余额，系统将直接抵扣；若代金券和余额均不足，需先充值后再继续使用。
* **升级套餐**：如需更高的基础额度，可点击“**升级套餐**”获取更多套餐内生成次数。

## 相关资源

<CardGroup>
  <Card title="音色列表" icon="user-music" href="/guides/voice/catalog">
    查看系统音色清单与套餐可调用范围。
  </Card>

  <Card title="查询可用音色" icon="list" href="/api-reference/endpoint/voice/list">
    确认当前账号可调用的 `voice_id`。
  </Card>
</CardGroup>


# SenseAudio 平台介绍
Source: https://docs.senseaudio.cn/index

**SenseAudio** 开放平台面向语音、音乐、图片、视频等多模态内容生产场景，提供可快速接入业务系统的 API 与平台能力。

平台适用于智能问答、代码助手、Agent 编排、智能助手、教育陪伴、播客、有声书、影视配音、内容创作、营销素材生产、语音交互等场景，帮助开发者以更低接入成本构建稳定、可扩展的 AI 内容生产能力。

## 核心能力

<CardGroup>
  <Card title="文本生成" icon="sparkles" href="/guides/llm/overview">
    S2 / S2-Lite / S2-Flash 旗舰多模态模型，支持深度推理、视觉问答、函数调用与流式输出。
  </Card>

  <Card title="语音合成" icon="waveform-lines" href="/guides/tts/overview">
    富有情感的 AI 语音、低延迟流式输出、精细参数控制。
  </Card>

  <Card title="音频生成" icon="file-audio" href="/guides/audio/overview">
    一次生成多角色对白、背景音乐与环境音效，完成完整声音编排。
  </Card>

  <Card title="语音识别" icon="microphone" href="/guides/asr/overview">
    文件转写与实时录音，支持结构化理解与说话人区分。
  </Card>

  <Card title="同声传译" icon="language" href="/guides/simultaneous-interpretation/overview">
    实时语音识别、翻译与译文播报，适合跨语言会议与直播场景。
  </Card>

  <Card title="人声分离" icon="headphones" href="/guides/voice-isolation/overview">
    从音频中分离人声，支持同步处理与异步任务查询。
  </Card>

  <Card title="自定义音色" icon="user-music" href="/guides/voice/custom">
    音色克隆与文生音色，统一通过 voice\_id 调用。
  </Card>

  <Card title="音乐生成" icon="music" href="/guides/music/overview">
    基于提示词生成歌词，并进一步生成完整歌曲。
  </Card>

  <Card title="图片生成" icon="image" href="/guides/image/overview">
    同步与异步调用，支持常规尺寸与高分辨率图片生成。
  </Card>

  <Card title="视频生成" icon="film" href="/guides/video/overview">
    支持文生视频与参考图生视频，1080P 高清画面输出。
  </Card>

  <Card title="端到端实时语音" icon="robot" href="/guides/agent/overview">
    端到端实时语音对话能力，支持低延迟语音交互。
  </Card>
</CardGroup>

## 快速接入

<CardGroup>
  <Card title="快速接入指南" icon="rocket" href="/guides/account/quick-access">
    5 分钟完成首个请求。
  </Card>

  <Card title="模型列表" icon="list" href="/guides/account/model-list">
    查看全部可调用模型与计费信息。
  </Card>

  <Card title="API 参考" icon="terminal" href="/api-reference/introduction">
    浏览全部 API 端点与参数说明。
  </Card>

  <Card title="常见问题" icon="circle-question" href="/guides/faq/overview">
    查看高频问题与处理建议。
  </Card>
</CardGroup>

## 关键命名说明

* **`model`**：模型名称，例如 `sensenova-tts-2.0`。
* **`voice_id`**：音色标识，用于在 TTS 请求中指定系统、克隆或文生音色。
* **`file_id`**：上传文件后的唯一标识，常用于音色克隆、语音识别。
* **`task_id` / `id`**：异步任务标识，用于图片、音乐、视频等异步任务状态查询。

## 联系我们

如需技术支持或商务咨询，请发送邮件至 [senseaudio.support@sensetime.com](mailto:senseaudio.support@sensetime.com)。