TypeHop
下载

开发者 · API 密钥

TypeHop API 密钥参考

API 密钥让 AI 应用或你自己的代码可以读取同步到你 TypeHop 帐户的听写内容,无论来自哪台设备。密钥是只读的:只能搜索和读取听写内容及你的自定义词汇,绝不会修改或删除任何内容。所有访问都通过一个远程 MCP 端点完成,因此 Claude Code、Cursor 和 Codex 等应用只需一行配置即可使用。

创建密钥

  1. 打开 TypeHop Mac 应用,前往 集成 → API 密钥。
  2. 点击 创建 API 密钥,并以将使用它的应用或设备命名,例如“我笔记本上的 Cursor”。
  3. 请立即复制密钥。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 · -32602 tools/call 指定了不存在的工具。
  • 500 · -32603 服务器错误。请使用退避策略重试。

限制与安全

有效密钥
每个帐户最多 10 个。撤销一个后才能再创建。
请求大小
每个请求最大 256 KB,每个批量请求最多 20 条消息。
结果
每次调用最多 50 条听写;recent_dictations 最多回溯 365 天。
范围
同步到你帐户的听写内容,以及你的自定义词汇。不会写入任何内容。
  • 每个应用或设备使用一个密钥,这样撤销其中一个不会影响其他的。
  • 将密钥保存在你的电脑或后端。切勿放入浏览器代码、移动应用包或公开仓库。
  • 密钥泄露:请在 集成 → API 密钥 中撤销。它会在下一次请求时失效。

有疑问:support@typehop.com。想看概览?请参阅TypeHop API。

Other products from us:SmashSend·TidySupport·SuperBuilder·Inbounter·Blossu·KnowledgeSDK