> ## Documentation index
> Fetch the complete documentation index at: https://dify-docs.docs7.io/llms.txt
> Ask it with GET https://dify-docs.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# 知识库 API

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

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

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

- [Agent 知识库 API](/zh/api-reference/guides/knowledge-base) <Badge color="blue" size="sm">Cloud</Badge>
- [经典知识库 API](/zh/api-reference/guides/knowledge)

## 创建 API 密钥 {#create-an-api-key}

<Info>
只有工作空间所有者和管理员可以创建、查看和删除密钥。
</Info>

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

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

## 选择访问范围 {#choose-a-scope}

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

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

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

## 替换密钥 {#replace-a-key}

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

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

## 密钥被拒绝时 {#when-a-key-is-refused}

| 原因 | 经典知识库 | 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 上，工作空间已达到 [请求频率限制](/zh/cloud/use-dify/knowledge/knowledge-request-rate-limit) | 403 `forbidden` | 403 `forbidden` |

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

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

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