知识库 API

使用 Convai 与你的 AI 角色的知识库交互所需的所有相关 API。

此 API 仅在企业版计划中可用。

上传新的 KB 文件

POST https://api.convai.com/character/knowledge-bank/upload

用户可以上传一个新的 KB 文件。文件成功上传后，他们可以将其连接到角色。调用 API 后，文件只会被上传以供处理，在处理完成之前将无法使用。上传 API 将返回分配给已上传文件的唯一 ID，之后对该文件的所有交互都必须使用该 ID。

请求头

名称	类型	说明
CONVAI-API-KEY*	字符串	每个用户提供的唯一 api-key。在登录 Convai 账户后，可在 Key 图标下找到。

请求体

名称	类型	说明
file_name	字符串	文件名
file	字节	原始文件字节

200：OK 文件已成功上传

{
   "id": "<已上传文件的 UUID>",
   "file_name": "<file_name>",
   "is_available": false,
   "status": "inactive",
   "timestamp": "2024-09-17 20:51:09.216522",
   "file_size": "72374"
}

401 API 密钥验证失败

以下是一些示例代码，用于演示该端点的请求格式 -->

Python

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/upload"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
}

# 要上传的文件路径
file_path = "photosynthesis.txt"

# 以二进制模式打开文件
with open(file_path, "rb") as file:
    # 为表单数据创建一个字典
    form_data = { 
        "file_name": file.name,
        "file": file
    }   

    # 发送带有 multipart/form-data 的 POST 请求
    response = requests.post(url, headers=headers, files=form_data)


print(response.text)

cURL

更新现有 KB 文件

POST https://api.convai.com/character/knowledge-bank/update

用户可以通过上传新版本来更新现有的 KB 文件。文件成功上传后，他们可以将其连接到角色。调用 API 后，文件只会被上传以供处理，在处理完成之前将无法使用。

请求头

名称	类型	说明
CONVAI-API-KEY*	字符串	每个用户提供的唯一 api-key。在登录 Convai 账户后，可在 Key 图标下找到。

请求体

名称	类型	说明
document_id	字符串	需要更新的现有文档的 ID
file	字节	原始文件字节

200：OK 文件已成功上传

{
   "id": "<已上传文件的 UUID>",
   "file_name": "<file_name>",
   "is_available": false,
   "status": "inactive",
   "timestamp": "2024-09-17 20:51:09.216522",
   "file_size": "72374"
}

401 API 密钥验证失败

以下是一些示例代码，用于演示该端点的请求格式 -->

Python

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/update"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
}

# 要上传的文件路径
file_path = "photosynthesis.txt"

# 以二进制模式打开文件
with open(file_path, "rb") as file:
    # 为表单数据创建一个字典
    files = {"file": ("photosynthesis-filename.txt", file, "text/plain")}
    form_data = {"document_id": "<document_id"}

    # 发送带有 multipart/form-data 的 POST 请求
    response = requests.post(url, headers=headers, files=files, data=form_data)


print(response.text)

列出 KB 文件状态

POST https://api.convai.com/character/knowledge-bank/list

列出 KB 文件的状态。使用此 API 检查先前上传的 KB 文件的状态。一旦此 API 返回 "is_available" 作为 true 你的 UUID，你可以放心地认为先前上传的文件已处理完毕，并可连接到你的角色。

请注意，list API 需要将 character_id 作为输入。因此，它会返回一个 "status" 字段，其取值可以是 "active" 或 "inactive。" 此字段表示某个特定文件是否已连接到角色。如果其 "status" 为 "active"，则视为已连接。

请求头

名称	类型	说明
CONVAI-API-KEY*	字符串	每个用户提供的唯一 api-key。在登录 Convai 账户后，可在 Key 图标下找到。

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。

200：OK 文件已成功上传

{
  'docs': [
    '{
        "id": "<文件 UUID>",
        "file_name": "photosynthesis.txt",
        "is_available": true,
        "status": "inactive",
        "timestamp": "2024-09-17 21:44:53.201385",
        "file_size": "1404"
    }',
    '{
        "id": "<文件 UUID>",
        "file_name": "FAQ.txt",
        "is_available": true,
        "status": "inactive",
        "timestamp": "2024-09-17 21:21:35.566677",
        "file_size": "736"
    }']
}

401 API 密钥验证失败

以下是一些示例代码，用于演示该端点的请求格式 -->

Python

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/list"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
}

# 为表单数据创建一个字典
form_data = { 
    'character_id': '<Your-CharacterId>',
}

# 发送带有 multipart/form-data 的 POST 请求
response = requests.post(url, headers=headers, data=form_data)

print(response.text)

cURL

将 KB 文件连接到角色（或断开连接）

POST https://api.convai.com/character/update

Update API 可用于将 KB 文件附加到你的角色，或将其移除。文件成功连接后，之后与该角色的所有交互都将按需从所附加的 KB 中获取知识。

请求头

名称	类型	说明
CONVAI-API-KEY*	字符串	每个用户提供的唯一 api-key。在登录 Convai 账户后，可在 Key 图标下找到。

请求体

名称	类型	说明
charID	字符串	你的角色 ID。
docs	列表	JSON 列表。每个条目对应一个文件。字段为 "id" 和 "status"。

200：OK 文件已成功上传

{"STATUS": "成功"}

401 API 密钥验证失败

以下是一些示例代码，用于演示该端点的请求格式 -->

Python

import requests
import json

url = "https://api.convai.com/character/update"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 负载创建一个字典
payload = { 
    "charID": "<Your-Character-Id>",
    "docs": [
        {   
            "id": "<File-UUID>",
            "status": "active"  # 或根据需要设为 "inactive"
        }   
    ]   
}

# 将负载转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)

cURL

删除 KB 文件

POST https://api.convai.com/character/knowledge-bank/delete

KB 删除 API 可用于永久移除用户账户中的文档。请注意，删除文档后，它会从所有与之关联的角色中移除。

请求头

名称	类型	说明
CONVAI-API-KEY*	字符串	每个用户提供的唯一 api-key。在登录 Convai 账户后，可在 Key 图标下找到。

请求体

名称	类型	说明
document_id	字符串	应删除文档的 ID。

200：OK 文件已成功删除

{"文档已成功删除"}

401 API 密钥验证失败

以下是一些示例代码，用于演示该端点的请求格式 -->

Python

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/delete"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
}

# 为 JSON 负载创建一个字典
form_data = { 
    "document_id": "<File-UUID>"   
}

response = requests.post(url, headers=headers, data=form_data)

print(response.text)

cURL