角色基础 API

使用 Convai 创建你自己的智能 AI 角色所需的所有相关 API。

此 API 仅适用于专业版及以上套餐。

访问 Convai 端点以开发并与智能角色交互，首先提供一些基本信息，例如角色名称、背景信息和语音选择。 通过你的自定义 UI 或 Convai 提供自定义插件/库的其他服务向终端用户展示该角色，让用户可以与你的新角色进行有趣的对话。

创建角色

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

用户既可以使用角色创建工具在平台上创建自己的角色，也可以使用此 API 端点，通过提供如下所定义的一些基本信息来动态创建角色。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	为每位用户提供的唯一 api-key。登录您的 Convai 账户后，可在钥匙图标下找到。

请求正文

名称	类型	描述
角色名称*	字符串	正在创建的新角色名称。
语音类型*	字符串	角色应具备的语音类型。 [有关支持的语音列表，请参阅 语音列表 API]
背景故事*	字符串	角色的基础背景信息，作为起始内容。
actions	字符串	供角色选择的一组动作，角色将根据与用户的交互执行这些动作。

201：已使用必要的详细信息创建了一个新角色

{
    "charID": "<新角色的角色 ID>"
}

400：错误请求 新角色注册失败

401 API 密钥验证失败

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

Python

import requests
import json

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

payload = json.dumps({
  "charName": "Raymond",
  "voiceType": "MALE",
  "backstory": "雷蒙德·雷丁顿是 NBC 剧集《黑名单》中的主要角色。雷丁顿是一个犯罪天才，曾在 FBI 十大通缉逃犯名单中排到第 4 位，后来又升至第 1 位；在躲避 FBI 20 多年后，他突然自首。"
})
headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

cURL

更新角色

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

用户可以更新之前创建的某个角色的一些现有详情。用户只需传入需要更新的任何新角色信息，其余角色信息将不会更改。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	为每位用户提供的唯一 api-key。登录您的 Convai 账户后，可在钥匙图标下找到。

请求正文

名称	类型	描述
角色ID*	字符串	要更新的角色 ID。
角色名称	字符串	角色的新名称
背景故事	字符串	更新后的背景故事
语音类型	字符串	角色的新语音类型 [有关支持的语音列表，请参阅 语音列表 API.]
动作	字符串	角色的新动作列表
语言代码	列表 <String>	角色需要支持的语言代码列表 [有关可用语言列表，请参阅 语言列表 API]

200：OK 详情已成功更新

{
   "STATUS": "成功"
}

400：错误请求 由于多种原因，更新可能会失败

401 API 密钥验证失败

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

Python

import requests
import json

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

payload = json.dumps({
  "charID": "<角色 ID>",
  "backstory": "雷蒙德·雷丁顿是一个极其聪明、极具驱动力且带有明显反社会倾向的人。这似乎是创伤后应激障碍（PTSD）的结果，因为没有迹象表明他天生如此。狡猾、善于操纵且富有魅力的雷德总是比其他人领先三步，并决心让自己始终成为一个谜。正如他所说：‘我是个罪犯。罪犯以臭名昭著的说谎闻名。关于我的一切都是谎言。’这大概是真的，不过谁又能确定呢。他不喜欢粗鲁的人；这一点是特工雷斯勒在雷德让一名臭名昭著的毒贩凭假身份证逃脱后指出的。雷斯勒提到，雷德不会让那个毒贩逃掉，因为他很粗鲁，而雷德不喜欢粗鲁的人。雷德回应道：‘他在我的飞机上。’",
  "voiceType": "US MALE 1",
  "charName": "Raymond Reddington"
})
headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

cURL

获取详情

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

用户可以检索他们已创建或已标记为公开的某个角色的所有信息。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	为每个用户提供的唯一 API 密钥。

请求正文

名称	类型	描述
角色ID*	字符串	要获取全部详情的角色 ID。

200：OK 返回对应角色的所有信息

{
    "character_name": "<角色名称>",
    "user_id": "<创建该角色的用户 ID>",
    "character_id": "<角色 ID>",
    "voice_type": "<为角色设置的语音类型>",
    "timestamp": "<角色创建时间>",
    "backstory": "<角色背景故事>"
}

400：错误请求 获取信息失败。请检查 character-id 是否有效

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

按以下方式搜索 角色ID：

Python

import requests
import json

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

payload = json.dumps({
  "charID": "<角色 ID>"
})
headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

cURL

按以下方式搜索 角色名称：

Python

import requests
import json

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

payload = json.dumps({
  "charName": "角色名称"
})
headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

cURL

克隆角色

POST https://api.convai.com/user/clone_character

用户可以使用此 API 克隆他们的角色。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	为每个用户提供的唯一 API 密钥。

请求正文

名称	类型	描述
角色ID*	字符串	要克隆的角色 ID。
知识库	布尔值	如果也应克隆知识库，则为 True；否则为 False。默认值为 False。

200：OK 角色已成功克隆。

{
    "charID": "<新创建的克隆角色 ID>"
}

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

Python

import requests
import json

url = "https://api.convai.com/user/clone_character"


headers = { 
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

# 为表单数据创建一个字典
payload = { 
    'charID': '<你的角色 ID>'
}


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

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

print(response.text)

cURL

删除角色

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

使用此命令删除现有角色。请注意，此操作不可逆，一旦删除，角色将无法恢复。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	为每个用户提供的唯一 API 密钥。

请求正文

名称	类型	描述
角色ID*	字符串	要删除的角色 ID。

200：OK 角色已成功删除

{
    "STATUS": "成功"
}

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

Python

import requests
import json

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


headers = { 
  'CONVAI-API-KEY': '<你的 API 密钥>',
  'Content-Type': 'application/json'
}

# 为表单数据创建一个字典
payload = { 
    'charID': '<你的角色 ID>'
}


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

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

print(response.text)

cURL