# 语音转文字
> 将语音音频转写为文字，支持说话人区分、时间戳、非语言事件标记及 JSON/SRT/VTT 字幕。

将语音音频转写为文字，返回逐句时间戳、可选的说话人区分（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` 轮询任务直到终态，并从该单任务响应读取完整转写稿。

## AI 指南

AI integration guide: https://docs.beatra.cn/llms/audio-speech-to-text.md

## 工具参数

```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 适合自定义应用直连。