> 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 仅适用于 Professional 计划及更高级别的计划。
{% endhint %}

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

## 创建角色

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

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

#### 请求头

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

#### 请求正文

| 名称                                         | 类型  | 说明                                                                                                                                                                          |
| ------------------------------------------ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| charName<mark style="color:必填;">\*</mark>  | 字符串 | 要创建的新角色的名称。                                                                                                                                                                 |
| voiceType<mark style="color:必填;">\*</mark> | 字符串 | <p>角色预期使用的语音类型。</p><p>\[支持的语音列表请参阅 <a href="https://docs.convai.com/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": "<character id for new character>"
}
```

{% endtab %}

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

```json
{
    "INTERNAL_ERROR": "Error in creating the character. Check if all the input data is valid. Contact support for more info."
}
```

{% endtab %}

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

```json
{
    "API_ERROR": "Invalid API key provided." / "api_key not found."
}
```

{% 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 is a main character in the NBC series The Blacklist. Reddington is a criminal mastermind, making it to #4 and later to #1 on the FBI's Ten Most Wanted Fugitives, who suddenly turns himself in after 20+ years of evading the FBI."
})
headers = {
  'CONVAI-API-KEY': '<your 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: <your api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charName": "Raymond",
    "voiceType": "MALE",
    "backstory": "Raymond Reddington is a main character in the NBC series The Blacklist. Reddington is a criminal mastermind, making it to #4 and later to #1 on the FBI'\''s Ten Most Wanted Fugitives, who suddenly turns himself in after 20+ years of evading the FBI."
}'
```

{% endtab %}
{% endtabs %}

## 更新角色

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

用户可以更新先前创建的角色的部分现有信息。只需传入需要更新的角色新信息，其余角色信息将保持不变。

#### 请求头

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

#### 请求正文

| 名称                                      | 类型             | 说明                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| charID<mark style="color:必填;">\*</mark> | 字符串            | 要更新的角色的 ID。                                                                                                                                                                                                                                                                                                                                                                                              |
| charName                                | 字符串            | 角色的新名称                                                                                                                                                                                                                                                                                                                                                                                                   |
| backstory                               | 字符串            | 更新后的背景信息                                                                                                                                                                                                                                                                                                                                                                                                 |
| voiceType                               | 字符串            | 角色的新语音类型 \[支持的语音列表请参阅 [语音列表 API](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/voice-list-api.md).]                                                                                                                                                                                                                                                         |
| action                                  | 字符串            | 角色的新动作列表                                                                                                                                                                                                                                                                                                                                                                                                 |
| languageCodes                           | List \<String> | 角色需要支持的语言代码列表 \[可用语言列表请参阅 [语言列表 API](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/language-list-api.md)]                                                                                                                                                                                                                                                   |
| 函数                                      | 数组             | 为此角色关联或取消关联外部 API 函数。每个项目的格式为 `{ "id": "<function uuid>", "status": "active" \| "inactive" }`。请参阅 [关联](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md#link-functions-to-a-character) 和 [取消关联](https://docs.convai.com/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": "Could not fetch character details from all_characters table." / 
             "Could not update character backstory." / 
             "Could not update all_characters table."
}
```

{% endtab %}

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

```json
{
    "API_ERROR": "Invalid API key provided." / "api_key not found."
}
```

{% 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": "<character ID>",
  "backstory": "雷蒙德·雷丁顿是一个极其聪明、意志坚定的人，表现出明显的反社会倾向。这似乎是创伤后应激障碍（PTSD）的结果，因为没有迹象表明他天生如此。雷德狡猾、善于操纵他人又富有魅力，总是比别人快人三步，并决心让自己始终保持神秘。正如他所说：“我是个罪犯。罪犯出了名地爱撒谎。我所说的一切都是谎言。”这大概是真的吧，不过谁又能确定呢？他不喜欢粗鲁的人。雷斯勒探员曾指出这一点：在雷德放走一名恶名昭彰的毒贩、让对方用虚假身份脱身之后，雷斯勒提到，雷德不让那名毒贩逃脱，是因为对方很粗鲁，而雷德不喜欢粗鲁的人。雷德回答说：“他在我的飞机上。”",
  "voiceType": "US MALE 1",
  "charName": "Raymond Reddington"
})
headers = {
  'CONVAI-API-KEY': '<your 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: <your api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charID": "<character ID>",
    "backstory": "雷蒙德·雷丁顿是一个极其聪明、意志坚定的人，表现出明显的反社会倾向。这似乎是创伤后应激障碍（PTSD）的结果，因为没有迹象表明他天生如此。雷德狡猾、善于操纵他人又富有魅力，总是比别人快人三步，并决心让自己始终保持神秘。正如他所说：“我是个罪犯。罪犯出了名地爱撒谎。我所说的一切都是谎言。”这大概是真的吧，不过谁又能确定呢？他不喜欢粗鲁的人。雷斯勒探员曾指出这一点：在雷德放走一名恶名昭彰的毒贩、让对方用虚假身份脱身之后，雷斯勒提到，雷德不让那名毒贩逃脱，是因为对方很粗鲁，而雷德不喜欢粗鲁的人。雷德回答说：“他在我的飞机上。”",
    "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 密钥。 |

#### 请求正文

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

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

```json
{
    "character_name": "<name of the character>",
    "user_id": "<the id of the user who created it>",
    "character_id": "<id of the character>",
    "voice_type": "<voice type set for the character>",
    "timestamp": "<when the character was created>",
    "backstory": "<backstory of the character>"
}
```

{% endtab %}

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

```json
{
    "ERROR": "INTERNAL SERVER ERROR, one or more database calls failed!"
}
```

{% endtab %}
{% endtabs %}

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

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

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

```python
import requests
import json

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

payload = json.dumps({
  "charID": "<id of the character>"
})
headers = {
  'CONVAI-API-KEY': '<your 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: <your api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charID": "<the id of the character>"
}'
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

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

payload = json.dumps({
  "charName": "name of the character"
})
headers = {
  'CONVAI-API-KEY': '<your 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: <your api key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "charName": "<the name of the character>"
}'
```

{% endtab %}
{% endtabs %}

## 克隆角色

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

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

#### 请求头

| 名称                                              | 类型  | 说明                 |
| ----------------------------------------------- | --- | ------------------ |
| CONVAI-API-KEY<mark style="color:必填;">\*</mark> | 字符串 | 为每位用户提供的唯一 API 密钥。 |

#### 请求正文

| 名称                                      | 类型  | 说明                                      |
| --------------------------------------- | --- | --------------------------------------- |
| charID<mark style="color:必填;">\*</mark> | 字符串 | 要克隆的角色 ID。                              |
| KB                                      | 布尔值 | 如果也应克隆 KB，则为 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': '<Your-API-Key>',
  'Content-Type': 'application/json'
}

# 为表单数据创建字典
payload = { 
    'charID': '<Your-Character-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": "<Your-Character-Id>"}'
```

{% endtab %}
{% endtabs %}

## 删除角色

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

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

#### 请求头

| 名称                                              | 类型  | 说明                 |
| ----------------------------------------------- | --- | ------------------ |
| CONVAI-API-KEY<mark style="color:必填;">\*</mark> | 字符串 | 为每位用户提供的唯一 API 密钥。 |

#### 请求正文

| 名称                                      | 类型  | 说明         |
| --------------------------------------- | --- | ---------- |
| 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': '<Your-API-Key>',
  'Content-Type': 'application/json'
}

# 为表单数据创建字典
payload = { 
    'charID': '<Your-Character-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": "<Your-Character-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.
