> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 知识库 API

> 创建两种知识库 API 通用的 API 密钥并设置访问范围，安全地替换密钥，以及查明调用被拒绝的原因

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](https://docs.dify.ai/en/api-reference/guides/knowledge-base-api)。

两种知识库各有自己的 API，但使用同样的 API 密钥：

* [Agent 知识库 API](https://docs.dify.ai/zh/api-reference/guides/knowledge-base.md) Cloud
* [经典知识库 API](https://docs.dify.ai/zh/api-reference/guides/knowledge.md)

## 创建 API 密钥

> [!NOTE]
>
> 只有工作空间所有者和管理员可以创建、查看和删除密钥。

在 **知识库** 页面右上角点击 **服务 API**，再点击 **API 密钥**。每个工作空间最多可有 10 个密钥。

同一面板中还显示服务 API 端点，即这两种 API 的基础 URL。

## 选择访问范围

创建密钥时，可以让它访问所有知识库，也可以只访问你选定的知识库，两种知识库都能选。只选择集成实际要用到的知识库。

如果集成还要调用不指定知识库的操作，例如获取经典知识库列表或创建经典知识库、管理标签，或 [获取可用模型](https://docs.dify.ai/zh/api-reference/models/get-available-models.md)，则改为让密钥访问所有知识库。

访问范围创建后无法修改。如需更改，[替换密钥](#replace-a-key)。

## 替换密钥

要更改密钥的访问范围或轮换密钥，先创建新密钥，把集成切换过去，再删除旧密钥。密钥删除后立即失效。

在 Agent 知识库中，研究任务和删除作业只能用发起它们的密钥读取。删除旧密钥前，先等它们完成，并读取结果。

## 密钥被拒绝时

| 原因 | 经典知识库 | Agent 知识库 |
| :- | :- | :- |
| 知识库不在密钥的访问范围内 | 403 `forbidden` | 403 `knowledge_fs_access_denied` |
| 限定范围的密钥调用了不指定知识库的操作 | 403 `forbidden` | 403 `forbidden` |
| 该知识库的 **API 访问** 已关闭 | 403 `forbidden` | 403 `knowledge_fs_access_denied` |
| 密钥已被直接删除，或随其覆盖的唯一知识库一并删除 | 401 `unauthorized` | 401 `unauthorized` |
| 在 Dify Cloud 上，工作空间已达到 [请求频率限制](https://docs.dify.ai/zh/cloud/use-dify/knowledge/knowledge-request-rate-limit.md) | 403 `forbidden` | 403 `forbidden` |

在经典知识库中，403 `forbidden` 可能对应上表中的多种原因，需查看错误的 `message` 加以区分。

限定于某个经典知识库的密钥，不能访问由它升级而来的 Agent 知识库。要访问这个 Agent 知识库，[替换密钥](#replace-a-key)，换成访问范围包含它的密钥。

如果某个 Agent 知识库 ID 在密钥所属的工作空间中不存在，会返回 401 `knowledge_fs_invalid_credential`，与密钥无效时相同。替换密钥前，先检查 ID 是否正确。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.