# Beatra Skill + MCP — 语音转文字

> 将语音音频转写为文字，支持说话人区分、时间戳、非语言事件标记及 JSON/SRT/VTT 字幕。
> 面向 AI 智能体的独立工作流指南。
> 对应网页：https://docs.beatra.cn/zh/docs/capabilities/speech/speech-to-text

- 主要接入方式：通用 Beatra Skill，经已授权的 MCP 调用。
- 安装或重新连接：https://beatra.ai/install.md
- MCP 端点：`https://mcp.beatra.cn/mcp`
- 计费操作：`beatra.audio.transcribe`
- 动态模型信息：只在需要模型约束、控制项或价格时，调用 `beatra.models.list` 并传 `capability: "speech_to_text"`。
- 交互方式：生成一个不透明的 `client_request_id`，把最终参数只提交一次，再用 `beatra.tasks.get` 轮询返回的 `task_id`，直到任务结束。
- 本地媒体：调用 `beatra.assets.upload`，严格按返回的 HTTPS PUT 上传，再使用 PUT 响应里的 artifact ID。

REST/OpenAPI 是备用的协议路径，智能体以 Skill 为主要接入方式。

---

将语音音频转写为文字，返回逐句时间戳、可选的说话人区分（diarization）、非语言声音事件标记，以及可直接使用的 JSON、SRT、VTT 字幕文件。

## Agent 主路径

通过 Universal Skill 使用 MCP 工具 `beatra.audio.transcribe`。该工具计费，返回异步任务。

1. 用 `beatra.assets.upload` 上传本地音频并取用返回的 `artifact_id`（或直接传 `https_url`）。
2. 需要对比语种覆盖范围、非语言声音事件标记或价格时，用 `capability: "speech_to_text"` 调用 `beatra.models.list`；否则省略 `model` 或传 `"auto"`（默认选用 `doubao-seed-asr-2.0`；当请求传入 `tag_audio_events: true` 或 `num_speakers` 时自动路由到 `elevenlabs-scribe-v3`）。
3. 创建一个不透明的 `client_request_id`，把最终参数只提交一次。
4. 用 `beatra.tasks.get` 轮询任务直到终态，并从该单任务响应读取完整转写稿。

## 工具参数

```json
{
  "audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "model": "auto",
  "language": "auto",
  "diarize": true,
  "subtitles": true,
  "client_request_id": "stt-opaque-1"
}
```

- `audio`（必填；MCP 与 REST 均兼容 `source` 输入别名）：artifact 引用（`{"type": "artifact", "artifact_id": "..."}`）或 HTTPS URL（`{"type": "https_url", "url": "https://..."}`），支持 MP3、WAV、M4A、AAC、FLAC、OGG、Opus。音频时长须在 `0.5` 秒到 **`3,600` 秒（`60 分钟`）**之间，文件不超过 `100 MiB`。超过 `60 分钟` 会在扣费前以 `422 invalid_request`（`details.reason: "audio_too_long"`）拒绝（超长录音请先用 `beatra.audio.process` 的 `operation: "trim"` 切片，见[音频处理](https://docs.beatra.cn/zh/docs/capabilities/speech/audio-processing)）。
- `model`（可选，默认 `"auto"`）：`"auto"`、`"doubao-seed-asr-2.0"` 或 `"elevenlabs-scribe-v3"`。
- `language`（可选，默认 `"auto"`）：`"auto"` 自动检测语种，或传 BCP-47 / ISO-639-1 语言标签（如 `"zh"`、`"yue"`、`"en"`、`"ja"`）。
- `diarize`（可选，布尔，默认 `false`）：在 `segments[]` 中标注不同说话人（`speaker_0`、`speaker_1` 等）。
- `num_speakers`（可选，整数 `1`–`32`）：`elevenlabs-scribe-v3` 支持的预期说话人数量提示；传入该字段会自动开启 `diarize: true`，且在 `model: "auto"` 下自动路由到 `elevenlabs-scribe-v3`。
- `tag_audio_events`（可选，布尔，默认 `false`）：在 `elevenlabs-scribe-v3` 上标记笑声、掌声、音乐等非语言音频事件。`model: "auto"` 下传入 `tag_audio_events: true` 会自动路由到 `elevenlabs-scribe-v3`；若显式指定 `model: "doubao-seed-asr-2.0"` 同时传 `tag_audio_events: true` 或 `num_speakers`，则会附加非阻塞的 `option_ignored` 警告。
- `subtitles`（可选，布尔，默认 `true`）：免费生成并持久化 JSON、SRT、VTT 三种格式的字幕文件包。
- `model_options`（可选，对象）：前向兼容的模型专属扩展选项袋。

## 模型与成本

`beatra.models.list`（传入 `capability: "speech_to_text"`）是可选模型、控制项与价格的实时事实来源。

语音转文字按**输入音频的计费分钟数**（不足 1 分钟按 1 分钟进位，`ceil(duration_seconds / 60)`）预扣积分，并设单次最低起步价：

| 模型 | 单价 | 单次最低 | 适用优势 |
| --- | --- | --- | --- |
| `doubao-seed-asr-2.0`（`auto` 默认） | `15 积分` / 分钟（进位） | `60 积分`（`<= 4 分钟`） | 中文普通话、方言口音、中英混说及英日多语高精度识别，支持说话人区分与时间戳。 |
| `elevenlabs-scribe-v3` | `21 积分` / 分钟（进位） | `61 积分`（`<= 2 分钟`） | 覆盖 90+ 全球语言，最多 32 位说话人区分（`num_speakers`），支持 `tag_audio_events` 非语言声音事件标记（`(laughter)`、`(applause)`、`(music)` 等）。 |

## 结果与字幕

任务成功时，`output` 包含完整文本、逐句分段、可选的非语言事件列表与字幕文件包：

```json
{
  "type": "speech_to_text",
  "model": "doubao-seed-asr-2.0",
  "text": "大家好，欢迎来到今天的播客。谢谢邀请！",
  "language": "zh",
  "duration_seconds": 6.4,
  "segments": [
    {
      "text": "大家好，欢迎来到今天的播客。",
      "start_seconds": 0.12,
      "end_seconds": 3.48,
      "speaker_id": "speaker_0"
    },
    {
      "text": "谢谢邀请！",
      "start_seconds": 3.85,
      "end_seconds": 5.9,
      "speaker_id": "speaker_1"
    }
  ],
  "audio_events": [],
  "subtitles": {
    "url": "https://cdn.beatra.cn/tenants/.../subtitles.json",
    "format": "json",
    "files": {
      "json": "https://cdn.beatra.cn/tenants/.../subtitles.json",
      "srt": "https://cdn.beatra.cn/tenants/.../subtitles.srt",
      "vtt": "https://cdn.beatra.cn/tenants/.../subtitles.vtt"
    },
    "segment_count": 2
  }
}
```

- `subtitles` 与[语音合成字幕](https://docs.beatra.cn/zh/docs/capabilities/speech/text-to-speech#字幕)使用完全一致的 `files.{json, srt, vtt}` 结构，下游视频合成与字幕工作流可直接复用。
- 纯静音或无人声的音频属于正常识别结果，任务会正常成功并返回 `text: ""`、`segments: []`、`subtitles: null`。
- 任务列表接口（`GET /v1/tasks`）对长转写稿只返回带 `truncated: true` 的摘要；获取完整 `text` 与 `segments[]` 请按 ID 读取（`beatra.tasks.get` 或 `GET /v1/tasks/{task_id}`）。

## 任务状态与恢复

`queued` 与 `running` 不是失败。请持续轮询同一个 `task_id`；创建响应丢失时用同一个 `client_request_id` 原样重试，参数有任何变化则换新 ID。失败任务自动退回预扣积分。

## 通过 REST 调用

直连协议集成可使用 `POST /v1/audio/transcriptions`（携带固定的 `Idempotency-Key` 请求头）及共享任务端点，详见[接口参考](https://docs.beatra.cn/zh/docs/api-reference)。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。

---

## 附录：Skill + MCP 通用约定

### 重试标识

一次逻辑上的生成对应一个 `client_request_id`。创建请求的响应丢失时，用同一个 ID 和完全相同的参数重试。提示词、媒体、模型或输出控制项有任何变化，就换一个新 ID。任务处于 `queued` 或 `running` 是正常状态，继续轮询同一个任务即可，不另建付费任务。

### 轮询与计费以任务为准

用有上限的退避间隔调用 `beatra.tasks.get` 轮询，遇到 `succeeded`、`failed` 或 `canceled` 时停止。实际使用的模型、产物、扣除的积分和退回的积分，以任务响应为准。

### 出错后的处理

保留 Beatra 返回的结构化错误码。鉴权失败时重新连接；余额不足时停下来，请用户充值；模型校验失败后用 `beatra.models.list` 刷新当前约束；上传授权过期，或 MIME 类型、长度不符时，申请新的上传授权。生成参数有变化时，一律使用新的 `client_request_id`。