开放 API 文档

为了满足插件、系统集成等高阶需求，小黑 OmniBox 对外提供了 Open API。

	地址	Swagger 文档
云服务	api.omnibox.pro	OmniBox Open API Docs
本地部署	<your-server>/open/api/	<your-server>/open/api/docs

获取 API Key

参见：如何创建 API Key

创建 API Key 时可以添加备注，建议记录用途、调用方或关联助手，方便后续管理和清理。

API Key 权限与范围

创建 API Key 时，需要设置 权限范围 和具体权限。

权限范围 决定这个 API Key 可以访问知识库中的哪一部分。选择某个文件或文件夹后，API Key 只能访问该资源及其子内容；如果创建资源时没有指定保存位置，资源会默认保存到这个范围内。

目前支持的权限包括：

权限	可选操作	说明
资源权限	创建、读取、更新、删除	管理文件、文件夹、资源内容、资源标签关联、网页收藏和文件上传
对话权限	创建	调用 AI 对话能力
标签权限	创建、读取	创建标签、查询标签
搜索权限	读取	在 API Key 的权限范围内搜索资源

如果 API Key 没有所需权限，接口会返回权限不足。建议只勾选当前集成真正需要的权限，避免给自动化脚本过大的访问范围。

在外部 Agent 中使用 Open API Skill

如果你希望让外部 Agent、自动化脚本或内部工具调用小黑 Open API，建议先让 Agent 读取小黑提供的 SKILL.md。该文件会说明 Open API 地址、认证方式、权限范围、额度规则和常用调用流程。

云服务地址：

https://api.omnibox.pro/v1/SKILL.md

自部署场景请使用你的 Open API 访问地址，例如：

https://<your-domain>/open/api/v1/SKILL.md

调用次数限制：

• 基础版空间：每 24 小时 10 次
• 高级版空间：每 24 小时 1000 次

调用 Open API 时请使用 Bearer Token：

Authorization: Bearer <api-key>

安全建议：不要把 API Key 写入日志、文档、URL 或聊天上下文。完整接口参数和响应结构请以 Swagger 文档 以及 SKILL.md 为准。