> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/character-api.md).

# 角色基础 API

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

{% hint style="danger" %}
此 API 仅适用于专业版及以上计划。
{% endhint %}

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

## 创建角色

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/create`

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

#### 请求头

| 名称                                              | 类型  | 说明                                          |
| ----------------------------------------------- | --- | ------------------------------------------- |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 为每位用户提供的唯一 api-key。登录 Convai 账户后，可在钥匙图标下找到。 |

#### 请求体

| 名称                                         | 类型  | 说明                                                                                                                                                    |
| ------------------------------------------ | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| charName<mark style="color:红色;">\*</mark>  | 字符串 | 正在创建的新角色名称。                                                                                                                                           |
| voiceType<mark style="color:红色;">\*</mark> | 字符串 | <p>角色应具有的语音类型。</p><p>\[有关支持语音列表，请参阅 <a href="/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/voice-list-api.md">语音列表 API</a>]</p> |
| backstory<mark style="color:红色;">\*</mark> | 字符串 | 角色的基础背景信息，用于开始创建。                                                                                                                                     |
| actions                                    | 字符串 | 供角色选择的一系列动作，这些动作将根据与用户的交互由角色执行。                                                                                                                       |

{% tabs %}
{% tab title="201：已使用必要详情创建了一个新角色" %}

```json
{
    "charID": "<新角色 ID>"
}
```

{% endtab %}

{% tab title="400：错误请求 新角色注册失败" %}

```json
{
    "INTERNAL_ERROR": "创建角色时出错。请检查所有输入数据是否有效。更多信息请联系支持。"
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "API_ERROR": "提供的 API 密钥无效。" / "未找到 api_key。"
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Python" %}

```python
import requests
import json

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

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

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

print(response.text)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location --request POST 'https://api.convai.com/character/create' \
--header 'CONVAI-API-KEY: <你的 api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charName": "Raymond",
    "voiceType": "MALE",
    "backstory": "Raymond Reddington 是 NBC 剧集《黑名单》中的主要角色。Reddington 是一个犯罪天才，在 FBI 十大通缉要犯名单中曾排到第 4 位，后来又升至第 1 位；在躲避 FBI 20 多年后，他突然自首。这似乎是创伤后应激障碍（post traumatic stress disorder）的结果，因为没有迹象表明他天生如此。Red 诡诈、善于操纵且富有魅力，总是比其他人领先三步，并决心让自己始终保持神秘。正如他所说：“我是个罪犯。罪犯以臭名昭著的谎言高手而闻名。关于我的一切都是谎言。”实际上这大概是真的，不过谁又能确定呢。他不喜欢粗鲁的人，这一点是 Agent Ressler 指出的——在 Red 放走了一名臭名昭著的毒贩并让其使用假身份证明脱身后。Ressler 提到，Red 本不该让那名毒贩逃脱，因为那人很粗鲁，而 Red 不喜欢粗鲁的人。Red 回答说：“他在我的飞机上。”"
}'
```

{% endtab %}
{% endtabs %}

## 更新角色

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/update`

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

#### 请求头

| 名称                                              | 类型  | 说明                                          |
| ----------------------------------------------- | --- | ------------------------------------------- |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 为每位用户提供的唯一 api-key。登录 Convai 账户后，可在钥匙图标下找到。 |

#### 请求体

| 名称                                      | 类型    | 说明                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| charID<mark style="color:红色;">\*</mark> | 字符串   | 要更新的角色的角色 ID。                                                                                                                                                                                                                                                                                                                                    |
| charName                                | 字符串   | 角色的新名称                                                                                                                                                                                                                                                                                                                                           |
| backstory                               | 字符串   | 更新后的背景故事                                                                                                                                                                                                                                                                                                                                         |
| voiceType                               | 字符串   | 角色的新语音类型 \[有关支持语音列表，请参阅 [语音列表 API](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/voice-list-api.md).]                                                                                                                                                                                                                      |
| 动作                                      | 字符串   | 角色的新动作列表                                                                                                                                                                                                                                                                                                                                         |
| languageCodes                           | 字符串列表 | 角色需要支持的语言代码列表 \[有关可用语言列表，请参阅 [语言列表 API](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/language-list-api.md)]                                                                                                                                                                                                               |
| functions                               | 数组    | 为该角色关联或取消关联外部 API 函数。每一项为 `{ "id": "<函数 UUID>", "status": "active" \| "inactive" }`。请参阅 [关联](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md#link-functions-to-a-character) 和 [取消关联](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md#unlink-functions-from-a-character). |

{% tabs %}
{% tab title="200：OK 详情已成功更新" %}

```json
{
   "STATUS": "SUCCESS"
}
```

{% endtab %}

{% tab title="400：错误请求 由于各种原因，更新可能会失败 " %}

```json
{
    "ERROR": "无法从 all_characters 表中获取角色详情。" / 
             "无法更新角色背景故事。" / 
             "无法更新 all_characters 表。"
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "API_ERROR": "提供的 API 密钥无效。" / "未找到 api_key。"
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

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

payload = json.dumps({
  "charID": "<角色 ID>",
  "backstory": "Raymond Reddington 是一个高度聪明、目标明确的人，并表现出发展中的反社会倾向。这似乎是创伤后应激障碍（PTSD）的产物，因为没有迹象表明他天生如此。Red 诡诈、善于操纵且富有魅力，总是比其他人领先三步，并决心让自己始终保持神秘。正如他所说，‘我是个罪犯。罪犯以臭名昭著的说谎者而闻名。关于我的一切都是谎言。’这大概是真的，不过谁又能确定呢。他不喜欢粗鲁的人，这一点是 Agent Ressler 指出的——在 Red 放走了一名臭名昭著的毒贩并让其使用假身份证明脱身后。Ressler 提到，Red 本不会让那名毒贩逃脱，因为那人很粗鲁，而 Red 不喜欢粗鲁的人。Red 回答说，‘他在我的飞机上。’",
  "voiceType": "US MALE 1",
  "charName": "Raymond Reddington"
})
headers = {
  'CONVAI-API-KEY': '<你的 api key>',
  'Content-Type': 'application/json'
}

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

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl --location --request POST 'https://api.convai.com/character/update' \
--header 'CONVAI-API-KEY: <你的 api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charID": "<角色 ID>",
    "backstory": "Raymond Reddington 是一个高度聪明、目标明确的人，并表现出发展中的反社会倾向。这似乎是创伤后应激障碍（post traumatic stress disorder）的产物，因为没有迹象表明他天生如此。Red 诡诈、善于操纵且富有魅力，总是比其他人领先三步，并决心让自己始终保持神秘。正如他所说，‘我是个罪犯。罪犯以臭名昭著的说谎者而闻名。关于我的一切都是谎言。’这大概是真的，不过谁又能确定呢。他不喜欢粗鲁的人，这一点是 Agent Ressler 指出的——在 Red 放走了一名臭名昭著的毒贩并让其使用假身份证明脱身后。Ressler 提到，Red 本不会让那名毒贩逃脱，因为那人很粗鲁，而 Red 不喜欢粗鲁的人。Red 回答说，‘他在我的飞机上。’",
    "voiceType": "US MALE 1",
    "charName": "Raymond Reddington"
}'\
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 获取详情

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/get`

用户可以检索他们已创建或已列为公开的某个特定角色的全部信息。

#### 请求头

| 名称                                              | 类型  | 说明                 |
| ----------------------------------------------- | --- | ------------------ |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 每个用户提供的唯一 api-key。 |

#### 请求体

| 名称                                      | 类型  | 说明             |
| --------------------------------------- | --- | -------------- |
| charID<mark style="color:红色;">\*</mark> | 字符串 | 要获取全部详情的角色 ID。 |

{% tabs %}
{% tab title="200：OK 返回对应角色的所有信息" %}

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

{% endtab %}

{% tab title="400：错误请求 获取信息失败。请检查 character-id 是否有效" %}

```json
{
    "ERROR": "内部服务器错误，一个或多个数据库调用失败！"
}
```

{% endtab %}
{% endtabs %}

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

按以下字段搜索 **charID:**

{% tabs %}
{% tab title="Python" %}

```python
import requests
import json

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

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

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

print(response.text)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location --request POST 'https://api.convai.com/character/get' \
--header 'CONVAI-API-KEY: <你的 api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charID": "<角色 ID>"
}'
```

{% endtab %}
{% endtabs %}

按以下字段搜索 **charName:**

{% tabs %}
{% tab title="Python" %}

```python
import requests
import json

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

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

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

print(response.text)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location --request POST 'https://api.convai.com/character/get' \
--header 'CONVAI-API-KEY: <你的 api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charName": "<角色名称>"
}'
```

{% endtab %}
{% endtabs %}

## 克隆角色

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/user/clone_character`

用户可以使用此 API 克隆自己的角色。

#### 请求头

| 名称                                              | 类型  | 说明                 |
| ----------------------------------------------- | --- | ------------------ |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 每个用户提供的唯一 api-key。 |

#### 请求体

| 名称                                      | 类型  | 说明                                      |
| --------------------------------------- | --- | --------------------------------------- |
| charID<mark style="color:红色;">\*</mark> | 字符串 | 要克隆的角色 ID。                              |
| 知识库                                     | 布尔值 | 如果也应克隆知识库，则为 True；否则为 False。默认值为 False。 |

{% tabs %}
{% tab title="200：OK 角色已成功克隆。" %}

```json
{
    "charID": "<新克隆角色 ID>"
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl -X POST "https://api.convai.com/user/clone_character" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \\
     -d '{"charID": "<你的角色 ID>"}'
```

{% endtab %}
{% endtabs %}

## 删除角色

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/delete`

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

#### 请求头

| 名称                                              | 类型  | 说明                 |
| ----------------------------------------------- | --- | ------------------ |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 每个用户提供的唯一 api-key。 |

#### 请求体

| 名称                                      | 类型  | 说明         |
| --------------------------------------- | --- | ---------- |
| charID<mark style="color:红色;">\*</mark> | 字符串 | 要删除的角色 ID。 |

{% tabs %}
{% tab title="200：OK 角色已成功删除" %}

```json
{
    "STATUS": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl -X POST "https://api.convai.com/character/delete" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \\
     -d '{"charID": "<你的角色 ID>"}'
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/character-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.