Buda API Claws NEW

Buda API Claw（爪）是什么？

Buda 给开发者的那扇门：用几行 REST 调用，给自己的产品挂上一个云端托管的 AI 智能体。

官方的开篇场景写得很具体：智能手表、IoT 设备、聊天插件，它们都想内置 AI 智能体。但在设备本地跑大模型不可行——算力不够、功耗太高、效果也差。

API Claw（爪）就是为此而生。只需对 Buda 位于 /api/v1 的 REST API 发起几次调用，第三方开发者就能为自己的产品配备一个云端托管的 AI 智能体，它具备对话能力和私有知识库，按需唤醒，闲置时不占用任何资源。

关键在于官方强调的一点：你接入的不是一个原始的模型 API，而是一个托管的智能体能力层——它已经包含了模型接入、运行时、知识库、会话管理以及运维扩缩容。

命名说明：官方文档标题是「API Claw（爪）」，文档路径为 /zh-CN/docs/developers/api-claws，定价页在开发者区块写作「API Claw」。本文按官方文档标题称其为 API Claw（爪）。

它面向谁

官方列了三类：智能硬件厂商（想内置 AI 助手的手表、耳机、IoT 设备）、软件开发者（想嵌入 AI 对话的小程序、应用、浏览器扩展）、SaaS 提供商（想给客户提供「AI 驱动的私有空间」）。

它给你省掉了什么

这一节是理解 API Claw 价值的关键。官方列了七项「开发者无需自己构建或运维」的东西：

• 模型配置与供应商切换
• 推理机器或 GPU 基础设施
• 智能体运行时与工具沙箱
• 文件摄取与知识库处理
• 会话与上下文管理
• 面向不同用户或客户的租户隔离
• 针对空闲智能体的唤醒/休眠编排

官方的总结是：这正是核心价值——你的团队可以专注产品体验，而 Buda 在背后提供智能体基础设施层。

为什么不直接调用 LLM API？

官方给了一张对照表：

官方的结论很直白：「调用模型 API 给你的是模型输出。API Claw（爪）给你的是一个可运营的 AI 智能体。」

工作原理与 API 结构

调用链是：你的产品（硬件 / 软件）→ API 调用 → Buda OpenAPI → Space（租户）→ Agent（AI 助手）+ Drive（知识库）→ Chat Session（对话）。

官方把 API 归为五个协作分组：

官方还给了一条经验法则：把持久知识放进 Drive，把瞬时用户输入放进 Chat Session，把客户或设备隔离放进 Space，把角色与运行时身份放进 Agent。只有当调用方是无法安全持有主 API Key 的前端时，才使用 Embed API。

前端集成：不要把主 Key 发给客户端

这是官方反复强调的一条。对于微信小程序、移动应用、浏览器扩展或任何你无法完全掌控的前端，不要下发主 Buda API Key，而要走嵌入流程：

• 你的后端用真实 API Key 调用 Buda，签发一个短期嵌入令牌。
• 小程序只存储这个短期令牌。
• 小程序通过 /api/v1/embed/... 发送消息并轮询状态。
• 令牌过期后，后端再签发一个新的。

如果要现成的托管对话界面，就改调 /embed-urls 拿一个短期 embedUrl 直接放进 iframe。官方特意提醒：令牌位于 URL 的哈希片段中，所以不会作为首次页面请求的一部分被发到服务器。

一个持续演进的 Agent 是怎么搭起来的

官方把最有用的模式总结成一句话：不要把「每次提示词都把全部内容发过去」当常态。而是把 Drive 当作 Agent 的持久大脑：

• 把产品手册、政策、发布说明和用户特定状态写进 Drive
• 每段对话以一条小的运行时消息开始（用户的问题或最新的设备事件）
• 轮询 Chat Session 的状态和消息
• 当产品学到可持久保留的内容时，把它作为文件写回 Drive
• 让下一次运行自动继承这份改进后的上下文

官方说这正是设备或第三方应用获得「随时间不断进步的 Agent」的方式。

价格与计费

按 Space 计费，而不是按终端用户。 你作为开发者购买 Space；如何向你的终端用户收费完全由你决定，官方明确 Buda 不干预你的定价、也不抽成。

计费走 Space 积分，与 Buda 主产品共用同一个积分池，不是独立订阅。Buda 侧公开的定价页显示：免费版 $0（2 个 Agent、300 积分/天）、Plus $20/月/Agent、Pro $100/月/Agent、企业版定制（含私有化部署、SSO、审计日志、BYOK），另提供批量定价与积分充值。模型按倍率消耗积分，从 0.03x（GPT-6 Luna）到 5.0x（Claude Fable 5.1 / GPT-6 Astra）不等。

空闲休眠不计费：官方说 Agent 空闲时自动休眠，有消息才唤醒，不跑的时候不产生费用。

值不值得用？

优点：

• 接入成本低。 不用自建推理栈、会话管理和知识库，几次 REST 调用就能给产品挂上云托管智能体。官方那句「你的团队可以专注产品体验」不是空话。
• 交付的是可运营的智能体，不是模型补全。 会话、知识库、运行时、多租户、运维都在 Buda 侧，这是它和裸模型 API 最本质的差别。
• 多租户原生。 按 Space 划分客户、团队、设备或付费账户边界。对 SaaS 和硬件厂商来说，这部分自己实现代价很高。
• 前端路径干净。 Embed API 的短期令牌放在 URL 哈希片段中，不随首次页面请求发到服务器；小程序和移动端不必持有主 Key。
• 计费模型对开发者友好。 按 Space 而非按终端用户，且不抽成、不干预你的定价。
• 闲时不烧钱。 空闲自动休眠，官方称不跑不产生费用。

缺点：

• 是云托管服务，不是自托管方案。 数据必须离开你的环境。对数据合规要求「全在本地」的场景，这条路直接不适用。
• 成本随用量浮动。 走积分池，模型倍率跨度大（0.03x 到 5.0x），需要自己盯消耗。
• 仍有集成工作量。 官方文档要求你按「创建、注入、运行、读取、学习、更新」的生命周期自己编排，不是装上就完。
• 产品线较多。 定价页同时有免费版、Plus、Pro、企业版、部署服务、积分充值和 Marketplace 模板，选购时容易看花眼。
• 配额与限流细节未公开。 规模化前的容量评估需要直接和官方确认。

总体结论： 如果你在做智能硬件、小程序、SaaS 或浏览器扩展，需要给产品加一个「有记忆、有私有知识库、按需唤醒」的 AI 助手，又不想自建后端和运维，API Claw 是当下少见的「按租户计费、不抽成、不锁模型」的选项。反过来，如果你的硬约束是数据不出自己的机房，那就别考虑它。

使用建议

1. 先用免费版跑通一条最小链路。 免费版给 2 个 Agent、300 积分/天，足够走通「建 Space → 建 Agent → 写 Drive 文件 → 开会话 → 轮询结果」的完整闭环。

2. 按官方的生命周期来设计。 创建、注入、运行、读取、学习、更新。把持久知识放 Drive、瞬时输入放 Chat Session、隔离放 Space、角色放 Agent——这条映射关系理清了，架构就顺了。

3. 前端一律走 Embed API。 不要把主 API Key 下发到小程序、移动应用或扩展。短期令牌 + 后端续签是官方指定的路径。

4. 盯住积分倍率。 模型从 0.03x 到 5.0x，差两个数量级。先挑性价比档位跑通业务，再按效果往上调。

5. 用 Drive 做「越用越聪明」的机制。 每次产品学到可持久的内容就写回 Drive。这是官方点名的核心模式，也是它区别于「每次重发长提示词」的地方。

6. 规模化前先谈批量定价。 官方提供批量定价通道。终端用户数上去之前，先和官方确认配额与限流细节。

适合谁用？

推荐： 做智能手表、耳机、IoT 等联网硬件、想给设备内置 AI 助手的厂商；要给小程序、移动应用或浏览器扩展嵌入 AI 对话的软件团队；想给客户提供「AI 驱动的私有空间」的 SaaS 提供商。

可考虑： 希望快速验证 AI 助手产品形态、不想先搭一套基础设施的创业团队；需要原生多租户隔离、又不想自己实现的中型产品。

不推荐： 硬约束是数据必须留在自有环境的合规场景；只想调用模型补全、不需要会话与知识库的简单场景；对成本波动敏感又不愿意监控用量的团队。

一句话：它把「给产品加一个云端 AI 智能体」这件事从「搭一套基础设施」压缩成「调几个 REST 接口」，代价是把运行环境交给云端。