开发者 · API 密钥
TypeHop API 密钥参考
API 密钥让 AI 应用或你自己的代码可以读取同步到你 TypeHop 帐户的听写内容,无论来自哪台设备。密钥是只读的:只能搜索和读取听写内容及你的自定义词汇,绝不会修改或删除任何内容。所有访问都通过一个远程 MCP 端点完成,因此 Claude Code、Cursor 和 Codex 等应用只需一行配置即可使用。
创建密钥
- 打开 TypeHop Mac 应用,前往 集成 → API 密钥。
- 点击 创建 API 密钥,并以将使用它的应用或设备命名,例如“我笔记本上的 Cursor”。
- 请立即复制密钥。TypeHop 只存储哈希值,因此完整密钥只显示一次。丢失了?请创建新密钥并撤销旧密钥。
密钥以 thp_mcp_ 开头。应用中的列表会显示每个密钥的前几个字符、创建时间和上次使用时间。撤销密钥会立即停止所有使用该密钥的应用。
认证
在每个请求中以 Bearer 令牌的形式发送密钥。无需 OAuth 流程,也无需建立会话。
- 端点
https://api.typehop.com/v1/mcp- 方法
- 仅支持
POST。GET和DELETE返回 405。 - 请求头
Authorization: Bearer thp_mcp_YOUR_KEY- 请求体
- JSON-RPC 2.0,
Content-Type: application/json
密钥缺失或已被撤销
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="typehop-mcp"
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "This token is invalid or was revoked." } }连接 AI 应用
大多数人从不需要手动调用该端点。Mac 应用会在连接应用下显示 Claude Code、Cursor、VS Code、Windsurf、Codex、Gemini CLI、Zed 和 Claude Desktop 的具体配置,并已填入你的新密钥。相同的代码片段也可在 MCP 页面找到。例如 Claude Code:
claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"
任何其他支持基于 Streamable HTTP 的远程 MCP 服务器的客户端,使用上面的端点 URL 和请求头即可。Claude.ai 和 ChatGPT 的自定义连接器需要 OAuth,TypeHop 暂不支持。
通过代码调用
该端点使用模型上下文协议(Model Context Protocol):以 POST 发送 JSON-RPC 2.0 消息,返回一个 JSON 响应。它是无状态的,因此没有会话头,也没有服务器发送事件。支持的协议版本: 2025-06-18, 2025-03-26, 2024-11-05.
1. 初始化(可选,但 MCP 客户端都会执行)
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'2. 列出工具
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. 调用工具
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_dictations","arguments":{"query":"launch plan","limit":5}}}'响应 · 200
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "[2026-11-03T09:14:22.000Z · Slack · id 3f6c1a2e-8b1d-4c55-9a0e-6b2f7d1e4c90]\nThe launch plan moves to next Tuesday..."
}
],
"isError": false
}
}结果中的每条听写都以一行头部信息开头:[created at · app · id <id>],随后是整理后的文本。将该 id 传给 get_dictation 即可获取原始转录。你也可以在一个请求中发送最多 20 条消息的数组;通知(不含 id 的消息)返回 202,无响应体。支持 ping。
工具
所有工具均为只读,并在 result.content[0].text 中返回纯文本。
search_dictations · 搜索听写
对用户的所有听写内容进行全文搜索。按时间由新到旧返回匹配结果。
query(string,必填): 要查找的词或短语。limit(integer 1–50,默认 20)
recent_dictations · 最近的听写
用户最近的听写内容,可选择仅返回最近几天的。
limit(integer 1–50,默认 20)days(integer 1–365): 仅返回最近 N 天的听写。
get_dictation · 获取一条听写
按 id 获取一条听写:整理后的文本和原始转录。
id(string,必填): 搜索或最近结果中显示的 id。
list_dictionary · 自定义词汇
用户的自定义词汇和拼写(人名、行话)。
无参数。
当工具无法给出答案时(查询为空、id 未知、临时读取失败),回复仍是 200 结果,带有 isError: true 以及模型可读的一句话。
错误
协议错误会以 JSON-RPC error 对象的形式返回:{ "code": <number>, "message": "<text>" }。
401 · -32001缺少 Authorization 请求头,或密钥无效或已被撤销。400 · -32700请求体不是有效的 JSON。413 · -32600请求体超过 256 KB。200 · -32600消息不是 JSON-RPC 2.0(缺少 "jsonrpc": "2.0" 或 "method")。200 · -32601未知方法。200 · -32602tools/call 指定了不存在的工具。500 · -32603服务器错误。请使用退避策略重试。
限制与安全
- 有效密钥
- 每个帐户最多 10 个。撤销一个后才能再创建。
- 请求大小
- 每个请求最大 256 KB,每个批量请求最多 20 条消息。
- 结果
- 每次调用最多 50 条听写;
recent_dictations最多回溯 365 天。 - 范围
- 同步到你帐户的听写内容,以及你的自定义词汇。不会写入任何内容。
- 每个应用或设备使用一个密钥,这样撤销其中一个不会影响其他的。
- 将密钥保存在你的电脑或后端。切勿放入浏览器代码、移动应用包或公开仓库。
- 密钥泄露:请在 集成 → API 密钥 中撤销。它会在下一次请求时失效。
有疑问:support@typehop.com。想看概览?请参阅TypeHop API。