mcpField
E
elevenlabs-scribe

elevenlabs-scribe

github.com/calesthio创意与媒体219103 次安装15 周前更新
代码仓库

关于 elevenlabs-scribe

面向媒体制作的 ElevenLabs Scribe 语音转文字技能，可将现有音视频转为带时间戳和说话人信息的文本，并支持字幕、编辑准备与内容审查。

主要功能

  1. 01音视频批量转写
  2. 02词级时间戳
  3. 03说话人区分与多声道处理
  4. 04音频事件标记
  5. 05实体检测与文本脱敏
  6. 06字幕与编辑素材准备

适用场景

  1. 01为播客制作带说话人标签的访谈记录
  2. 02生成字幕草稿并整理剪辑时间点
  3. 03检查录音中的个人或敏感信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill elevenlabs-scribe

安装后在 Claude Code 中输入/elevenlabs-scribe确认已加载。

附带文件EVAL.md

详细介绍

ElevenLabs Scribe 语音转文本

当媒体制作任务需要使用 ElevenLabs Speech to Text（Scribe）生成转录文本、字幕时间轴、带说话人标签的访谈记录、播客剪辑准备材料、无障碍字幕、本地化交接材料、通话／访谈分析结果或清理后的转录文本时，请使用此技能。不要将其用于文本转语音、配音、声音克隆或翻译；Scribe 会从现有音频／视频中生成文本、时间信息和元数据。只有在转录文本经过核实且用户有权转换源素材后，才使用配音或 TTS 技能。

以下易变信息已于 2026-07-10 根据 ElevenLabs 官方文档核实。如果要基于实时 API 构建，请在进行不可逆的生产工作之前，重新确认模型名称、限制、定价、数据驻留端点和保留选项。

基于来源的信息

当前模型及适用场景
  • 批量／文件转录请使用 scribe_v2。ElevenLabs 文档指出，Scribe v2 支持 90 多种语言、词级时间戳、最多 32 位说话人的说话人分离、动态音频标签、关键术语提示、实体检测和智能语言检测。
  • 仅在实时流式场景中使用 scribe_v2_realtime，例如 Agent、实时会议或交互式监控。这是一项 WebSocket 语音转文本服务，不是为已完成文件制作后期字幕的常规方案。
  • 请将 scribe_v1 视为已弃用，不适合新任务。核查时，API 架构仍将 scribe_v1 列为允许值，但官方更新日志已宣布于 2026-07-09 移除 Scribe v1。请优先使用 scribe_v2，并将任何对 Scribe v1 的依赖标记为迁移问题。
输入、输出和请求格式

批处理端点：使用 multipart 表单数据调用 POST https://api.elevenlabs.io/v1/speech-to-text。

输入：

  • 只提供一个文件输入路径或 URL 来源。当前 API 参考文档介绍了 file 上传和 source_url；cloud_storage_url 已弃用，改用 source_url。
  • 支持音频和视频文件。官方文档列出了常见音频格式，包括 AAC、AIFF、OGG、MP3、OPUS、WAV、FLAC、M4A、WebM，以及常见视频格式，包括 MP4、AVI、MKV、MOV、WMV、FLV、WebM、MPEG 和 3GPP。
  • 文件大小的文档说明存在冲突：API 参考文档规定，上传文件必须小于 5.0 GB；而概览／关键事实页面规定最大为 3 GB。生产规划时，除非当前 API 测试或账户文档确认支持更大的限制，否则应采用 3 GB 作为保守的预检上限。
  • 时长／多声道的文档说明存在冲突：概览 FAQ 称标准模式最长支持 10 小时，且多声道总时长必须少于 10 小时；而关键事实页面称多声道最长时长为 1 小时。对于无人值守的生产任务，应将 1 小时作为保守的多声道规划上限，并对更长的文件进行分段。

核心响应字段：

  • language_code、language_probability、text 和 words。
  • words[] 条目可根据请求的选项包含 text、start、end、type、speaker_id、characters 和 logprob。
  • 词语类型包括 word、spacing 和 audio_event。启用事件标记时，audio_event 表示笑声或掌声等非语音声音。

实用参数：

  • model_id="scribe_v2"。
  • language_code：ISO-639-1 或 ISO-639-3；语言已知且稳定时请提供，否则允许自动检测。
  • timestamps_granularity：默认为 word；character 为每个词返回字符级时间信息；none 会减少时间信息，不应用于字幕、剪辑决策列表或多声道合并输出。
  • tag_audio_events：默认为 true；适用于播客、纪录片、无障碍内容和剪辑备注等需要关注笑声、掌声、脚步声或其他事件的场景。只有在下游交付内容必须是纯口语文本时才禁用。
  • diarize：默认为 false；对混合单声道的多说话人录音，如果说话人标签有用，请设为 true。
  • num_speakers：可选的说话人数提示，范围为 1-32。说话人数已知时使用；不确定时省略，并通过 QA 调整。
  • diarization_threshold：可选，范围为 0.1-0.4；仅当 diarize=true 且未设置 num_speakers 时使用。阈值越高，越倾向于合并说话人；阈值越低，越倾向于拆分说话人。默认值由模型选择，通常约为 0.22。
  • keyterms：让转录偏向产品名称、人名、术语、品牌、URL、缩写和专有名词。批处理版 Scribe v2 最多支持 1000 个关键术语，每个术语少于 50 个字符，规范化后最多 5 个词；实时版最多支持 50 个关键术语，每个术语少于 20 个字符。使用关键术语提示会增加费用。
  • no_verbatim：Scribe v2 选项，可移除填充词、说话中断、言语不流畅和非语音声音，从而生成更简洁的字幕／摘要。如果法律、研究、调查、定性访谈或纪录片的完整性要求逐字转录，请勿启用。
  • temperature：生产环境中通常省略，或保持为 0／接近 0；较高的值可能降低结果的确定性，通常不适用于转录。
  • seed：尽力实现确定性采样，但不作保证。
说话人处理：说话人分离、声道分离、说话人库、角色

发送文件前，先选择说话人处理策略：

  1. 如果每位参与者都单独录制在一个音频声道中，请使用多声道模式。
  2. 如果所有说话人都混合在同一个单声道／立体声音轨中，请使用说话人分离。
  3. 如果只有一位旁白，请勿请求说话人分离；应将输出核实为单说话人转录文本。

多声道模式：

  • 设置 use_multi_channel=true、diarize=false，以及 timestamps_granularity=word 或 character。
  • 最多支持 5 个声道；每个声道都会独立处理，并确定性地映射为 speaker_0、speaker_1 等。
  • 不要设置 num_speakers；说话人数由声道数量决定。
  • multichannel_output_style="separate" 会在 transcripts 下为每个声道返回一份转录文本。
  • multichannel_output_style="combined" 会返回一份顶层转录文本，其中的词语会合并并按开始时间排序；每个词语都带有 channel_index。合并输出需要时间戳，且不支持通过 webhook 传送、实体检测或敏感信息删改。
  • 计费和并发量会随声道时长线性增长。一个 60 分钟、3 声道的文件，计费和计算量可能相当于 180 声道分钟。

说话人分离模式：

  • 当说话人轮次很重要且声道未分离时，设置 diarize=true。
  • 如果已知说话人数，请提供 num_speakers（例如，主持人 + 嘉宾 = 2）。如果说话人数未知，请将 num_speakers 留空（null），并检查聚类结果。
  • 只有在首次处理显示系统性过度拆分或合并时，才使用 diarization_threshold；不要盲目调参。
  • 说话人标签不代表身份验证。speaker_0 表示“聚类 0”，并非已确认的某个人。听取音频后，再由人工将标签映射到姓名。

说话人库和角色：

  • API 参考中包含 use_speaker_library，可在说话人分离期间与工作区说话人库中的已知说话人匹配。仅当工作区已主动登记说话人，且用户拥有识别他们的权利／已获得同意时才使用。
  • API 参考中包含 detect_speaker_roles，用于标记 agent／customer 角色。此功能要求 diarize=true，不能与多声道模式同时使用，并会增加费用。仅用于呼叫中心风格的音频，不适用于普通播客或纪录片。
字幕、字幕文件和剪辑准备

如果 API 客户端支持，请使用 additional_formats；如果 SDK／工具层未提供该功能，则根据 JSON 响应生成字幕。官方 API 架构列出的导出选项包括 docx、html、pdf、segmented_json、srt 和 txt；ElevenLabs 产品 UI 文档说明，字幕导出格式为 SRT 和 VTT，转录文本导出格式为纯文本、JSON、HTML、SRT 和 VTT。承诺通过 API 提供 VTT 前，请确认客户端支持的具体 API 格式。

字幕工作流：

  • 请求 timestamps_granularity=word。
  • 将 SRT／VTT 作为草稿交付物，而非最终无障碍字幕，除非用户接受机器生成的字幕。
  • 只有在交付内容为字幕／摘要，且原始转录文本另行保存时，才优先使用 no_verbatim=true，以生成易读字幕。
  • 根据词语时间戳生成字幕条目，并满足平台限制：大致控制在 1–2 行、字符数易于阅读、单条时长不过长、条目之间不重叠，并在短语边界处切分。
  • 将原始转录 JSON 保留为事实来源。SRT／VTT 应视为衍生文件。
  • ElevenLabs 的产品字幕编辑器将转录文本和字幕编辑分开保存；如果人工编辑了字幕，不要假定这些编辑也修改了底层转录文本。

剪辑准备：

  • 保留词语级时间戳，以便进行文字剪辑、选择精彩片段和规划跳切。
  • 将带有说话人标签的词语转换为轮次级片段，并包含 speaker_id、start、end、text 和置信度／QA 备注。
  • 如果音频事件可能影响故事节奏、反应节点、掌声、笑声或无障碍体验，请予以保留。
异步任务和 Webhook

对于小型／交互式任务，请使用同步批量转录，并等待 JSON 响应。

对于长文件、大批量处理或无人值守处理：

  • 在 ElevenLabs 控制面板中配置 Speech-to-Text Webhook。
  • 发送 webhook=true；请求会提前返回一个请求标识符，稍后通过 Webhook 接收转录文本。
  • 配置了多个 Webhook 时，使用 webhook_id 指定要调用的 Webhook。
  • 使用 webhook_metadata 传递项目 ID、源资产 ID、预期时长、哈希值、编辑器任务 ID 和保管链引用。保持结构扁平：官方文档规定最大深度为 2，最大大小为 16 KB。
  • 验证 Webhook 签名。ElevenLabs 文档建议使用 HMAC 或 OAuth 身份验证方法，并验证签名。
  • Webhook URL 必须使用 HTTPS。
  • 只有在有效载荷已持久化存储后，才返回 2xx。对于可重试的服务器故障，返回 5xx；4xx 表示不可重试的客户端错误。
  • Webhook 投递不支持合并的多通道输出；请使用分离输出，并在客户端进行合并。
实体检测、脱敏和敏感内容

Scribe v2 支持实体检测，可提供精确位置／时间戳以及 pii、phi、pci、other 和 offensive_language 等类别，还支持许多单独的标签（姓名、出生日期、信用卡、SSN、健康状况、药物、地点、电子邮件、电话号码、URL 等）。此功能会增加费用。

在以下情况下使用实体检测：

  • 从客户通话或访谈中制作公开片段。
  • 根据包含个人、医疗、财务或账户数据的录音创建本地化或编辑备注。
  • 构建脱敏审核队列。

当转录文本本身必须安全可分享时，使用实体脱敏。API 参考要求脱敏目标必须是 entity_detection 的子集；脱敏会抑制 entities 字段。脱敏内容可以格式化为 {REDACTED}、{ENTITY_TYPE} 或带编号的实体标记。

对于受监管的内容或公开发布内容，不要仅依赖自动脱敏。请将其作为初步处理，然后由人工审核原始音频和转录文本。

定价、费用和限制

官方 API 定价已于 2026-07-10 核实：

  • Scribe v1/v2：标价为每小时 $0.22。
  • Scribe v2 Realtime：标价为每小时 $0.39。
  • 实体检测：标价为每小时 $0.070。
  • 关键术语提示：定价表标价为每小时 $0.050，而 API 参考将关键术语描述为在基础转录费用上加收 20%。请将定价视为可能变动；只有在解释差异时才同时列出两种价格，并在向客户报价前重新核实。
  • API 参考说明，实体检测和脱敏会加收 30%，角色检测会加收 10%。
  • 多通道按每个通道的完整时长分别计费。

预估费用时，请使用：

billable_audio_hours = duration_hours * max(1, channel_count_when_multichannel)

然后加上已启用功能的附加费用。如果文档内容不一致，请向用户展示较保守的估算，并注明核实日期。

隐私、保留、安全与保管

在用户确认其对材料拥有适当权利、已获得同意且隐私保护措施到位之前，不要上传源录音。

截至 2026-07-10 核实的官方保留与安全信息：

  • 默认情况下，ElevenLabs 会根据其隐私政策保留数据，用于服务改进、故障排查和系统安全。
  • 企业客户可为语音转文本启用零保留模式。对于 API 产品，可通过 enable_logging=false 启用；在 STT 中使用时，请求音频输入和文本输出不会被记录或长期存储，但支持与调试能力有限，且无法使用转录存储功能。
  • 零保留模式仅适用于部分企业客户；与 HIPAA 相关的集成要求在处理 HIPAA 工作负载前联系 ElevenLabs 销售团队签署 BAA。
  • ElevenLabs 文档建议使用服务账户、隔离环境、限定范围的 API 密钥、最小权限和资源级权限。
  • 官方文档列出了欧盟、印度和新加坡的隔离数据驻留 API/WebSocket 基础 URL；默认情况下，标准环境托管在美国，而 api.us.elevenlabs.io 可将 API 流量固定路由至美国服务器，以满足延迟或路由需求。若合同有要求，请使用工作区配置的环境端点；不要假设公共全局端点符合数据驻留要求。
  • Webhook 可能包含转录文本和元数据。应将 Webhook 负载视为敏感的生产资料。

资料保管规则：

  • 将原始音频/视频、提交的分块、返回的 JSON、SRT/VTT/DOCX/PDF 导出文件、脱敏版本和人工编辑的字幕文件作为单独资料存储，并保留来源信息。
  • 记录请求参数、模型 ID、核验日期、源媒体哈希、分块边界、声道映射、说话人标签映射、成本估算和保留模式。
  • 生成清理后的转录文本时，绝不要覆盖原始转录文本；应将 raw、corrected、caption 和 redacted 状态明确区分。
  • 避免发送有效期超过转录任务所需时间的预签名 URL。使用最小权限 URL，并在任务完成后撤销或使其过期。
  • 将 API 密钥保留在服务器端；仅当当前文档支持相应流程时，才为客户端实时 STT 使用一次性令牌。
同意、权利、安全与披露

对于转录，关键的权利问题通常是录制和处理人类语音，而非语音合成。转录前：

  • 确认用户有权上传和处理该录音。
  • 对于私人通话、访谈、未成年人、医疗/财务数据或工作场所录音，要求提供书面同意或明确的法律依据。录音同意法律因司法管辖区而异；不能仅凭持有文件就推断已获许可。
  • 将敏感源媒体发送至云端 API 前，提醒用户。如项目要求本地/离线转录，即便 Scribe 的质量更好，也应提供该选项。
  • 对于面向公众的字幕、摘要或剪辑，如政策、平台规则、合同或当地法律有要求，应披露实质性的 AI 参与情况。
  • 不得使用 Scribe 输出进行冒充、监视、人肉搜索、骚扰、规避同意要求或制造误导性归属。
  • 如果转录文本将用于生成配音、克隆声音或合成替代语音，应暂停并遵循相关的语音同意/配音/TTS 政策；同意转录并不自动授权生成合成语音。

生产工作流

  1. 审查源文件。

    • 确认时长、文件大小、格式、声道数、语言、说话人数、隐私敏感程度和下游交付物。
    • 对于视频，决定是直接上传视频，还是先提取音频。提取干净的 WAV 可以减小上传文件的大小，并让文件保管流程更加明确。

  2. 选择模式。

    • 单人说话：diarize=false。
    • 单个音轨中有多位说话人：diarize=true，可选 num_speakers。
    • 说话人声道彼此隔离：use_multi_channel=true，diarize=false。
    • 实时/Agent：scribe_v2_realtime，WebSocket 工作流。

  3. 准备音频。

    • 优先使用干净的无损或高质量音频。对于多声道音频，移除未使用的声道，并确保每个声道只有一位说话人。
    • 对于时长较长或风险较高的文件，在自然静音处或已知时间码间隔处分段，并保留偏移元数据。
    • 对于 pcm_s16le_16，确保音频为 16-bit PCM、16 kHz、单声道、小端序；仅在低延迟很重要且采集工具能够完全满足此格式时使用。

  4. 添加词汇和隐私选项。

    • 根据人名、品牌、产品术语、缩略词、领域术语、剧集标题和非英语专有名词构建 keyterms。
    • 仅在需要时添加 entity_detection/entity_redaction；同时考虑成本和输出格式的影响。
    • 仅当账户已启用企业版 Zero Retention Mode，且可以接受请求历史记录和转录文本不再保存时，才使用 enable_logging=false。

  5. 转录并保留原始产物。

    • 清理前先保存原始 JSON。
    • 保存请求元数据和源文件哈希。
    • 对于 Webhook，验证签名，并按请求 ID 幂等地持久化载荷。

  6. 使用输出前进行质量检查。

    • 抽听有代表性的样本和所有关键片段。
    • 核对说话人轮次、人名、数字、剪辑附近的时间戳，以及任何法律、医疗或金融术语。
    • 将源文件时长与转录覆盖范围进行比较；调查较大的空白、重复片段或时间戳漂移。
    • 对于字幕，打开字幕观看视频，并检查可读性、换行、字幕时间和与场景切换的冲突。

运行注意事项

  • 混合单声道说话人分离很有用，但不能证明说话人身份；重叠语音、串音、相似音色、房间混响和电话音频可能会把一位说话人拆分成多个簇，或将不同说话人合并。
  • 当每位说话人的音频确实彼此隔离时，多声道模式通常比说话人分离更干净；如果声道间串音严重或包含多人，则效果更差。
  • 关键词有助于正确拼写术语和处理行话，但过多低价值词条可能增加成本，还可能在意想不到的位置影响输出。优先使用经过筛选的高价值词条列表。
  • no_verbatim=true 可以提高字幕的可读性，但也可能抹去犹豫、情绪，以及纪录片、研究、法律或编辑场景中重要的证据。
  • 音频事件标签有助于无障碍访问和剪辑节奏，但可能存在噪声；应将其视为需要审核的注释，而不是最终的舞台指示。
  • Webhook 作业需要幂等存储，因为生产系统中可能发生重试或重复通知。

生产启发式

  • 对于播客/访谈：请求词级时间戳、说话人分离或多声道标签、开启音频事件、为嘉宾姓名和节目专属词汇添加关键术语，然后生成原始版和清理后的轮次级转录文本。
  • 对于社交媒体字幕：保留原始 JSON；只有在用户想要易读字幕时，才使用 no_verbatim=true 创建清理后的字幕草稿，然后根据最终剪辑人工检查字幕时间点。
  • 对于本地化准备：使用 Scribe 生成源语言转录文本和时间信息，然后将经核实的文本交给翻译/配音流程。不要将 Scribe 当作翻译系统。
  • 对于剪辑决策：根据词级时间戳提取片段，但最终剪辑点应依据音频/视频审核确定，而不只是依照词语边界。
  • 对于敏感通话：将实体检测/脱敏作为初筛层；如果可用，使用企业级零数据保留，并将脱敏和未脱敏转录文本分别存放在访问受控的存储区。
  • 对于长文件：优先使用 Webhook 或分块处理。尽可能在静音处切块；否则记录精确的时间偏移，并确认边界处没有遗漏词语。

示例

示例：混合立体声/单声道的双人播客剪辑准备

制作目标：为一段 72 分钟的播客创建可搜索的转录文本、主持人/嘉宾轮次列表和候选片段，其中多位说话人混合在同一音轨中。

工作流：

  1. 如果源文件是视频文件，将音频提取为干净的 WAV 文件。
  2. 提交给 Scribe v2：
{
  "model_id": "scribe_v2",
  "diarize": true,
  "num_speakers": 2,
  "timestamps_granularity": "word",
  "tag_audio_events": true,
  "keyterms": ["guest name", "company name", "product name", "technical acronym"],
  "no_verbatim": false
}

预期结果：

  • 包含词级时间戳和 speaker_id 聚类的原始 JSON。
  • 按说话人将连续词语分组后生成的轮次级转录文本。
  • 保留笑声/掌声/反应等音频事件。

故障模式：

  • 静音或串话后，说话人聚类可能发生交换。
  • 如果关键术语不完整，产品名称仍可能拼写错误。
  • 长段背景音乐或广告期间可能出现时间戳漂移。

变体：

  • 如果每位参与者位于单独声道，请使用多声道模式，而不是说话人分离。
  • 对于公开节目说明，在保留逐字原始转录文本后，再创建清理后的转录文本。
示例：带脱敏的双声道客户通话

制作目标：为一段客户支持通话创建安全的审核转录文本；客服和客户位于不同声道，且可能提及账户数据。

工作流：

{
  "model_id": "scribe_v2",
  "use_multi_channel": true,
  "diarize": false,
  "multichannel_output_style": "separate",
  "timestamps_granularity": "word",
  "entity_detection": ["pii", "pci"],
  "entity_redaction": ["pii", "pci"],
  "entity_redaction_mode": "enumerated_entity_type",
  "tag_audio_events": false
}

预期结果：

  • 分别对应 speaker_0 和 speaker_1 的声道转录文本。
  • 适合更广泛内部审核的脱敏转录文本。
  • 启用脱敏后，不包含未脱敏的 entities 字段。

故障模式：

  • 如果请求同时输出合并后的多声道结果并启用实体检测/脱敏，请求会失败。
  • 声道串音可能导致客户说的话出现在客服声道中。
  • 自动脱敏可能漏掉以口语形式说出的 ID 变体；对外发布前仍需人工审核。

变体：

  • 如果角色未按声道隔离，但音频是呼叫中心风格的单声道混音，可考虑使用 detect_speaker_roles=true 和 diarize=true，并权衡成本和质量保证。
  • 对于异步处理，可使用 Webhook 交付，并分别输出；如有需要，由客户端进行合并。
示例：产品发布视频的字幕草稿

制作目标：为一段 90 秒的最终 MP4 生成第一版字幕，并交给编辑。

工作流：

{
  "model_id": "scribe_v2",
  "timestamps_granularity": "word",
  "language_code": "en",
  "tag_audio_events": true,
  "no_verbatim": true,
  "additional_formats": [
    {
      "format": "srt",
      "max_segment_duration_s": 4,
      "max_characters_per_line": 42
    }
  ],
  "keyterms": ["brand name", "feature name", "speaker name"]
}

预期结果：

  • 原始转录文本 JSON，以及在客户端/工具提供 additional_formats 时生成的 SRT 草稿。
  • 字幕比逐字稿更流畅，但仍需完整观看检查。

故障模式：

  • SDK 封装可能不提供返回的 additional_formats；如有需要，可根据 JSON 生成 SRT。
  • no_verbatim=true 可能会删掉有意重复的内容或符合品牌风格的说法。
  • 字幕可能跨越镜头切换，或超出平台的可读性限制。

变体：

  • 如果法律审批要求逐字准确的口语内容，请禁用 no_verbatim。
  • 如果最终交付格式为 VTT，且当前客户端尚未确认支持 API VTT，请根据经核实的词级时间戳 JSON 或 ElevenLabs UI 导出生成 VTT。

已于 2026-07-10 核实的来源链接

评论

支持 Markdown