transcribe.so

transcribe-agent

让任何 Agent 都能转录。一个代码库，三种接入方式：纯 JSON CLI （transcribe-so）、适用于 npx skills add 的 Agent 技能，以及捆绑 transcribe.so 远程 MCP 服务的 Claude Code 插件。

transcribe.so 可将 YouTube 视频、播客、直链媒体 URL 和本地文件转换为带说话人标签的转录文本，其中包含带时间戳的片段、章节、部分内容、附引用的问答、字幕文件（SRT、VTT、卡拉 OK VTT）、完整转录文本导出、片段搜索，以及可直接粘贴到 Instagram、X、Threads、LinkedIn、YouTube、Spotify 和 Apple Podcasts 的字幕。

安装

让人类参与流程：每次付费调用都需要设置 max_charge_usd 上限，并且会先进行免费报价。

1. Agent 技能（Claude Code、OpenClaw，以及任何兼容 skills.sh 的 Agent）

npx skills add shsunmoonlee/transcribe-agent

这会安装 SKILL.md，其中向 Agent 介绍 CLI 工作流、硬性规则和退出代码。

2. Claude Code 插件（远程 MCP 服务 + 技能 + /transcribe 命令）

/plugin marketplace add shsunmoonlee/transcribe-agent
/plugin install transcribe-so@transcribe-agent

该插件将 Claude 连接到 https://transcribe.so/mcp 上的远程 MCP 服务（24 个工具），并捆绑 transcribe-audio 和 get-transcript 技能，以及一个单次执行的 /transcribe 命令。首次调用工具时会启动 OAuth 浏览器流程；也可以通过 /mcp 使用 tsk_live_* API 密钥进行身份验证。

3. CLI（任何脚本、定时任务或带 shell 的 Agent）

npm install -g transcribe-so     # or: pnpm install -g transcribe-so
export TRANSCRIBE_API_KEY=tsk_live_...   # https://transcribe.so/settings/api-keys
transcribe-so me

Codex

作为插件（远程 MCP 服务和技能）安装：

codex plugin marketplace add shsunmoonlee/transcribe-agent
codex plugin add transcribe-so@transcribe-agent

或者只连接 MCP 服务：

codex mcp add transcribe --url https://transcribe.so/mcp

Codex 会在首次调用工具时启动 OAuth 流程。插件包含 .codex-plugin/plugin.json 和 .agents/plugins/marketplace.json。

Grok

此代码库包含 .grok-plugin/plugin.json；Grok Build 会读取其中的根目录 .mcp.json 和 skills/。

Cursor

从市场或 Customize 面板中找到 transcribe-so 并点击 Install。也可以手动将其添加到 .cursor/mcp.json：

{"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp"}}}

Antigravity CLI

agy plugin install https://github.com/shsunmoonlee/transcribe-agent

该插件包含 plugin.json 和 mcp_config.json，用于将 Antigravity CLI 指向托管的 MCP 服务，此外还包含 skills/ 中的技能。 Antigravity CLI 无法自行运行 OAuth 登录（其 /mcp 面板会显示“Auth Needed”），因此请使用 API 密钥连接工具，密钥可在 https://transcribe.so/settings/api-keys 获取：

agy mcp add --header "Authorization: Bearer tsk_live_..." transcribe-so-key https://transcribe.so/mcp

请使用 transcribe-so 以外的名称：Antigravity 中的 MCP 服务名称是全局的，而插件自带的 transcribe-so 条目在 CLI 中会一直显示 “Auth Needed”，可以忽略。Antigravity App 和 IDE 也提供了用于连接插件服务的 Authenticate 按钮（Settings、Customizations）。已经使用过 Gemini CLI 扩展？ agy plugin import gemini 可以将其转换。

Gemini CLI

gemini extensions install https://github.com/shsunmoonlee/transcribe-agent

该扩展包含 gemini-extension.json，用于将 Gemini CLI 指向托管的 MCP 服务。首次使用时会打开浏览器进行登录。 自 2026-06-18 起，Gemini CLI 支持付费 Gemini API 密钥和企业密钥；个人 Google AI 账户请使用 Antigravity CLI（见上文）。

ChatGPT

进入 Settings、Connectors、Developer mode，然后添加 https://transcribe.so/mcp 并使用 transcribe.so 账户登录。

OpenClaw 和任何 skills.sh Agent

npx skills add shsunmoonlee/transcribe-agent

与上文的第 1 种接入方式使用同一条命令：该技能与运行时无关，可介绍 CLI 工作流、硬性规则和退出代码。

30 秒上手 CLI

# Price it (free), then transcribe under an explicit budget
transcribe-so quote --source youtube --url "https://www.youtube.com/watch?v=..."
transcribe-so run   --source youtube --url "https://www.youtube.com/watch?v=..." --max-usd 2

# Local file
transcribe-so upload ./interview.mp3         # prints upload_id (+ ffprobe duration)
transcribe-so run --source upload --upload-id <id> --duration <s> --max-usd 5

# Artifacts
transcribe-so result <id> | jq '.chapters[]'
transcribe-so transcript <id> > out.txt                      # the whole transcript, never capped
transcribe-so subtitles <id> --format srt > out.srt
transcribe-so captions <id> --for instagram --variant highlights
transcribe-so search "pricing" | jq -r '.hits[] | "\(.speaker): \(.text)"'
transcribe-so ask <id> -q "What did the guest say about pricing?"

命令

命令	功能
auth:status	TRANSCRIBE_API_KEY 是否有效？
me	账户、钱包余额、套餐限额、API 密钥权限范围和支出
capabilities	一个 JSON 对象：账户 + 流水线目录 + 所有格式枚举 + 退出代码
pipelines	每分钟定价和支持的语言
quote	免费价格预览（不会将任何内容加入队列）
create	提交任务。--max-charge-usd <n> 会在服务端限制费用
run	quote → 预算检查 → create → 等待 → 结果，一条命令完成
wait <id>	长轮询，直到任务进入终态
result <id>	章节、分段、问答（--include、--segments-offset、--segments-limit）
transcript <id>	原始输出：完整转录文本，格式为 txt 或 md，绝不截断
subtitles <id>	原始输出：SRT / VTT / 卡拉 OK VTT / JSON
captions <id> --for <dest>	原始输出：适用于各平台、可直接粘贴的字幕或章节时间戳
search <q>	“谁在什么时候说了 X”，可搜索整个资料库或限定 --id
ask <id> -q "..."	带引用的问答（使用每日额度，不扣钱包余额）
list / get <id>	浏览任务；状态／阶段／进度快照
upload <file>	为本地文件执行预签名 PUT；输出 upload_id
retry <id> --yes	发起新的付费尝试（再次传入 --max-charge-usd）
delete <id> --yes	不可撤销

为 Agent 设计的契约：

• 除三个原始输出命令（subtitles、transcript 和不带 --json 的 captions）外，所有命令的标准输出均为 JSON。这三个命令会输出可通过管道写入文件的正文。错误始终以 JSON 信封格式返回。所有进度信息都会输出到标准错误，因此 | jq . 始终可用。
• 退出代码含义明确：0 表示成功，1 表示 API 错误，2 表示用法错误，3 表示身份验证错误，4 表示支付错误，5 表示暂时性错误，6 表示本地 --max-usd 预算拒绝，7 表示服务端 max_charge_exceeded（未扣费，未启动任务）。
• 两种预算，均需明确指定：run --max-usd 根据免费报价在本地拒绝；--max-charge-usd 会发送到 API，并在钱包预扣时强制执行。除非传入 --no-server-ceiling，否则 run 也会将其 --max-usd 作为服务端上限发送。
• create/run/quote/retry 始终会发送 Idempotency-Key。显式传入 --idempotency-key，可确保跨进程重试安全：自动生成的密钥仅对单次调用有效，因此重新运行命令会使用第二个密钥，并产生第二笔费用。
• 遇到 409 not_ready 时，会根据其 reason 采取相应操作：只有 transcription_processing 会触发重试。
• 除非传入 --allow-custom-host，否则 CLI 会拒绝向非默认主机发送你的 API 密钥。

完整命令参考和工作流规则：SKILL.md。发行说明：CHANGELOG.md。示例： examples/。

定价

转录费用按分钟从你的 transcribe.so 钱包中扣除；报价免费（提交前使用 quote）。片段渲染按每个已开始的 60 秒计费。实时问答使用每日额度，不扣钱包余额。当前价格： https://transcribe.so/pricing

目录

插件清单（.codex-plugin、.claude-plugin、.cursor-plugin、 .grok-plugin、gemini-extension.json）采用统一版本管理，并与 MCP 服务版本保持一致；package.json 中的 CLI 有独立版本。

构建用于提交到 OpenAI Plugins Directory 的 ZIP：

pnpm run build:openai-plugin -- --video-url https://.../demo.mp4   # or DEMO_RECORDING_URL=...
# -> out/transcribe-so-openai-plugin.zip (.codex-plugin/plugin.json, .mcp.json, skills/, assets/)

如果面向模型的文案违反目录收录规则，脚本会失败：interface 块、发行说明、skills/**/SKILL.md、commands/*.md 和所有清单描述中不得出现有关费用、促销或账户等级的措辞，不得使用长破折号，也不得包含 transcribe.so 和 github.com 以外的链接。Agent 只会了解 getQuote 报告的内容，以及何时应在开始前询问用户，仅此而已。如果清单中的版本不一致，或 skills/ 中包含 <skill>/SKILL.md 以外的内容，脚本也会失败。规则： https://developers.openai.com/plugins/plugin-guidelines.

根目录中的 SKILL.md 记录了供 npx skills add 使用的 CLI 说明，不属于任何目录清单；--max-charge-usd 等 CLI 标志也记录在其中。

Claude 插件的运行与发送内容

• 一个远程 MCP 服务，在 .mcp.json 中声明： https://transcribe.so/mcp，通过 HTTPS 连接。Claude 会将你提供的链接、问题 和转录文本 ID 发送给它；它会返回转录文本、章节、答案、字幕文件和片段链接。首次调用工具时，你可以在浏览器中通过 OAuth 登录，也可以通过 /mcp 输入 transcribe.so API 密钥。
• 本地文件，仅限 Claude Code，且仅在你提出请求时处理：createUpload 会返回一个短时有效的预签名 HTTPS URL，用于将文件上传到 transcribe.so 在 Cloudflare R2 上的文件存储（地址为 r2.cloudflarestorage.com），随后 Claude 会通过 HTTP PUT 将文件发送到该地址。聊天客户端不会上传文件。
• **除此之外，没有其他操作：**没有钩子、没有本地服务、没有软件包下载、没有遥测，也不会读取你机器上的凭据。技能和 /transcribe 命令是供 Claude 使用的 Markdown 指令。
• 开始转录或渲染片段会扣除 transcribe.so 账户余额。除非你已经提供了消费限额，否则 Claude 会先检查免费报价，并在开始任何操作前征求你的同意。

隐私政策

此工具会将你提供的媒体 URL、上传文件和问题发送到 transcribe.so 进行处理。有关数据收集、使用、存储、保留期限和联系方式，请参阅 transcribe.so 隐私政策： https://transcribe.so/privacy-policy。除 API 和 MCP 工具传输的数据外，CLI 或插件本身不会收集任何数据。

链接

• Agent 主页：https://transcribe.so/agent
• 文档：https://transcribe.so/developers/docs
• OpenAPI：https://transcribe.so/openapi.json
• MCP 服务卡片：https://transcribe.so/.well-known/mcp/server-card.json
• 身份验证指南：https://transcribe.so/auth.md
• 支持：[email protected]