语音转文字

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

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

Agent 主路径

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

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

工具参数

{
  "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" 切片，见音频处理）。
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 包含完整文本、逐句分段、可选的非语言事件列表与字幕文件包：

{
  "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.ai/tenants/.../subtitles.json",
    "format": "json",
    "files": {
      "json": "https://cdn.beatra.ai/tenants/.../subtitles.json",
      "srt": "https://cdn.beatra.ai/tenants/.../subtitles.srt",
      "vtt": "https://cdn.beatra.ai/tenants/.../subtitles.vtt"
    },
    "segment_count": 2
  }
}

subtitles 与语音合成字幕使用完全一致的 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 请求头）及共享任务端点，详见接口参考。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。