清晰地构建。

当前进展

API 已构建并测试完毕。在第一条模型路由开放之前，聊天请求会返回 503 inference_not_configured。实时状态始终可在 https://undergrove.vercel.app/api/status 查看。

它遵循 OpenAI API 格式，因此现有的 SDK 只需更改基础 URL 即可使用：支持带图片的聊天、函数调用和结构化输出，以及嵌入、转录和语音。要让请求连我们的网关也无法读取，请像工作区一样使用加密模式。

快速入门

基础 URL：https://undergrove.vercel.app/v1。用 GET /v1/models 列出模型，然后以流式方式获取回复：

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "stream": true,
    "messages": [{"role": "user", "content": "Help me explore an idea."}]
  }'

试验场

在此页面用你自己的密钥发送聊天请求，查看回答、用量和原始响应，以及对应的 curl 请求。它和其他 API 调用一样，从你的浏览器发送到本站的 /v1，并照常消耗你的配额或额度。

选择“加密”即可按 SDK 加密模式的方式发送：Tinfoil 的 SDK 在此页面中验证安全飞地，然后用它的密钥密封请求。试验场会显示实际离开页面的字节、返回的内容，以及请求所密封到的安全飞地的回执。

curl --no-buffer https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {
        "role": "user",
        "content": "帮我探索一个想法。"
      }
    ],
    "stream": true
  }'

身份验证

以 Bearer token 的形式发送 Undergrove API 密钥。密钥以 ugk_ 开头，内测期间通过邀请发放。在开启了自助密钥的地方，内测成员可在工作区设置中创建最多五个密钥，每个密钥都会消耗所属账户的配额和额度。我们只存储每个密钥的单向哈希，因此丢失的密钥无法找回，只能更换。

每个自助密钥都可以有自己的限制，可在创建时或之后在设置中配置：每日支出上限（达到后，该密钥的请求会被拒绝，直到 UTC 午夜），以及它可以使用的模型列表。设有上限的密钥仍会计入所属账户的配额。在限制功能推出之前创建的密钥没有限制，照常使用。

curl https://undergrove.vercel.app/v1/models \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY"

端点

响应使用标准的 chat.completion 结构。流式响应发送 chat.completion.chunk 事件，并以 data: [DONE] 结束。推理模型会在 delta.reasoning_content 中单独流式输出推理过程，最后一个分块会报告 token 用量。如果流被中断，最后一个事件会是一个错误对象而不是 [DONE]，因此不完整的回答绝不会被误认为完整的回答。

curl https://undergrove.vercel.app/v1/embeddings \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "undergrove/nomic-embed-text",
    "input": ["Where is the signed contract?", "Payment terms"]
  }'

参数

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "max_tokens": 500,
    "messages": [{"role": "user", "content": "Is it raining in Lisbon?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

加密模式

标准 API 由我们的网关在内存中读取，以检查每个请求。要让请求对 Undergrove 也不可读，请用你的密钥搭配 Tinfoil 的 SDK。它会验证安全飞地的硬件证明，然后加密每个请求，使只有该安全飞地能读取。我们的中继检查你的密钥和配额，并把密文转发出去。

import { SecureClient } from "tinfoil"; // npm install tinfoil

const RELAY = "https://undergrove.vercel.app/api/enclave";
const client = new SecureClient({
  baseURL: `${RELAY}/v1/`,
  attestationBundleURL: RELAY,
});
await client.ready(); // verifies the enclave; throws if it can't

const response = await client.fetch("chat/completions", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.UNDERGROVE_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "gemma4-31b", // enclave_model in /v1/models
    max_tokens: 1000,
    messages: [{ role: "user", content: "Summarise this contract." }],
  }),
});
console.log((await response.json()).choices[0].message.content);

同一个客户端还可以访问 embeddings、audio/transcriptions 和 audio/speech。由于中继无法读取这些请求，模型需以 /v1/models 中的 enclave_model ID 指定，回答以 Tinfoil 的格式返回，用量则根据加密数据的大小估算。配额和额度照常适用。

MCP 服务器

Undergrove 同时也是一个 Model Context Protocol 服务器，地址为 https://undergrove.vercel.app/mcp。每个实时模型都是一个工具，例如 ask_<model>，Claude Code、Cursor 和 Claude Desktop 等 MCP 客户端可以用你的 API 密钥调用它。工具接受一个 prompt，以及可选的 system、max_tokens，对于能搜索的模型还有 web_search，并以文本形式返回模型的回答。

工具调用和其他 API 请求一样：网关在内存中读取它，通过模型公开的路由发送出去，不保留副本，并计入你密钥的限制、配额和额度。服务器使用可流式 HTTP，以 JSON 回答，不保留会话。它支持的协议版本为 2025-11-25、2025-06-18 和 2025-03-26。

claude mcp add --transport http undergrove https://undergrove.vercel.app/mcp \
  --header "Authorization: Bearer ugk_your_key"

{
  "mcpServers": {
    "undergrove": {
      "url": "https://undergrove.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer ugk_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "undergrove": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://undergrove.vercel.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ugk_your_key"
      }
    }
  }
}

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer ugk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

然后调用某个模型的工具：

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "ask_<model>",
      "arguments": {"prompt": "Name three uses for a sealed envelope."}
    }
  }'

反过来，工作区也可以使用你在设置中连接的 MCP 服务器提供的工具。这些调用经由 Undergrove 的服务器以明文发送到你连接的服务器，因此请只使用你放心交给其工具相应内容的服务器。

错误与限制

错误使用 OpenAI 格式：{"error": {"message", "type", "code"}}。

内测期间，每个密钥或账户都有每分钟请求数、每日请求数和每日支出配额。当前数值发布在 /api/status。

HTTP/2 429
retry-after: 41

{
  "error": {
    "message": "You’re sending messages quickly. Please wait a moment.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

了解你的数据去向

网关检查你的密钥、执行限制，并只把上述字段转发到模型路由。它不保留提示词或回答的副本，也不记录它们。其日志只记录路由名称、状态码和耗时。速率限制计数器使用你的密钥或账户的单向哈希，并在两天内过期。

每条模型路由的运营方、所在地和数据保留方式都发布在 /api/status 的模型登记表和隐私页面上。请求绝不会回退到其他路由。我们的托管方 Vercel 会保留 IP 地址等标准请求元数据。

在机密计算路由上，API 网关在建立连接前会验证安全飞地的硬件证明，并加密每个请求，使只有该安全飞地能读取。但网关本身仍会在内存中读取 API 请求以进行检查。

工作区数据

同步、共享链接和共享项目只存储浏览器生成的密文。每张图都逐步展示谁持有密钥。

验证能证明什么

在发送任何内容之前，工作区会在你的浏览器中运行 Tinfoil 的开源验证器。它对照 AMD 或 Intel 的签名密钥检查安全飞地的硬件证明报告，检查安全飞地中度量的代码是否与 Tinfoil 在 GitHub 上发布并签名的版本一致，并检查所用的加密密钥是否属于该安全飞地。在工作区中选择已验证，即可查看每一项检查、版本和度量值。

它证明你的消息只能由运行该公开代码的那台硬件解密。它不能证明公开的代码没有缺陷，不能防范处理器本身的弱点，也不涵盖回答到达你的浏览器之后你如何使用它们。工作区代码由 Undergrove 提供，因此你需要信任我们按公开版本提供验证器；验证此页面会把你的浏览器加载的代码与构建清单进行比较，npm run verify:site 则会把网站与你自己基于同一提交构建的版本进行比较。我们计划进行独立评估。

来自安全飞地的每个回答都有一个回执按钮。它会显示在发送该请求之前验证过的安全飞地、版本和度量值，以及请求加密所用的密钥，并可将它们下载为 JSON。在标签页关闭之前，下载内容包含证明报告，你以后可以再次对其运行验证器；之后则包含报告的哈希，以及获取该安全飞地当前报告的位置。回执是你浏览器的记录，而不是签名声明，其中列出的安全飞地是 Tinfoil 的模型路由器；路由器会把请求转交给模型自己的安全飞地。回执也会列出该安全飞地，你的浏览器会尝试以同样的方式验证它。大多数模型安全飞地运行在 Intel TDX 上，浏览器验证器目前还无法检查；对于这些安全飞地，回执会注明这一点，检查则依赖路由器，其公开代码会在使用每个模型安全飞地之前对其进行验证。

# The attestation bundle the gateway verified, what it checked
# in it, and the steps to check it again yourself
curl https://undergrove.vercel.app/v1/attestation

接下来