> 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/narrative-design-api.md).

# 叙事设计 API

本页列出了与叙事设计交互所需的所有 API

## 切换叙事设计

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/toggle-is-narrative-driven`

为你的角色启用/禁用叙事图。

#### 标头

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

#### 请求体

| 名称                    | 类型  | 说明                           |
| --------------------- | --- | ---------------------------- |
| character\_id         | 字符串 | 你的角色 ID。                     |
| is\_narrative\_driven | 布尔值 | 将其设为 true 或 false，以启用或禁用叙事图。 |

{% tabs %}
{% tab title="200：成功 " %}

```json
{"STATUS": "成功"}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/toggle-is-narrative-driven"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id": "<Your-Character-Id>",
    "is_narrative_driven": True
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/toggle-is-narrative-driven" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{"character_id": "<Your-Character-Id>", "is_narrative_driven": true}'
```

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

## 创建节

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

为你的角色创建新节。

#### 标头

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

#### 请求体

| 名称                       | 类型   | 说明             |
| ------------------------ | ---- | -------------- |
| character\_id            | 字符串  | 你的角色 ID。       |
| objective                | 字符串  | 节目标            |
| section\_name            | 字符串  | 节名称。           |
| updated\_character\_data | JSON | \*忽略\* 该字段未使用。 |
| behavior\_tree\_code     | 字符串  | \*忽略\* 该字段未使用。 |
| bt\_constants            | 字符串  | \*忽略\* 该字段未使用。 |

{% tabs %}
{% tab title="200：成功创建节 " %}

```json
{
    "section_id": "<New-Section-Id>"
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/create-section"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "objective":"节目标",
    "section_name":"节名称",
    "updated_character_data":{},
    "behavior_tree_code":"",
    "bt_constants":""
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/create-section" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "objective": "节目标",
         "section_name": "节名称",
         "updated_character_data": {},
         "behavior_tree_code": "",
         "bt_constants": ""
     }'
```

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

## 编辑节

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

编辑你的角色的节。你应通过 updated\_character\_data JSON 发送所有要更新为节的数据。以下为有效键。

* "section\_name"
* "objective"
* "decisions"：这是一个 JSON 列表。列表中的每一项应具有以下格式。

  ```
  {
      "criteria":"决策条件",
      "next_section_id":"要跳转到的节 ID"
  }
  ```

#### 标头

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

#### 请求体

| 名称                       | 类型   | 说明        |
| ------------------------ | ---- | --------- |
| character\_id            | 字符串  | 你的角色 ID。  |
| updated\_character\_data | JSON | 包含已更新的字段。 |
| section\_id              | 字符串  | 要更新的节 ID。 |

{% tabs %}
{% tab title="200：成功更新节 " %}

```json
{
    "status": "success",
    "section_id": "<Section-Id>",
    "updated_data": {
        "objective": "某个新的目标。"
    }
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/edit-section"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->",
    "updated_data":{
        "decisions":[
            {"criteria":"用户同意参观。", "next_section_id":"b9d7f568-7d06-11ef-be6a-42010a7be011"}
        ],  
        "objective":"为用户提供博物馆导览。",
        "section_name":"欢迎节"
    }   
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/edit-section" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->",
         "updated_data": {
             "decisions": [
                 {
                     "criteria": "用户同意参观。",
                     "next_section_id": "b9d7f568-7d06-11ef-be6a-42010a7be011"
                 }
             ],
             "objective": "为用户提供博物馆导览。",
             "section_name": "欢迎节"
         }
     }'
```

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

## 获取节

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

获取你的角色某个特定叙事节的详细信息。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明        |
| ------------- | --- | --------- |
| character\_id | 字符串 | 你的角色 ID。  |
| section\_id   | 字符串 | 要获取的节 ID。 |

{% tabs %}
{% tab title="200：成功获取节详情 " %}

```json
{
   "character_id": "<Your-CharacterId>",
   "section_id": "<Your-SectionId>",
   "objective": "为用户提供历史博物馆导览。",
   "decisions": [{"criteria": "用户同意参观。", "next_section_id": "12345568-7890-1123-4456-424242424242"}],
   "parents": null,
   "updated_character_data": {},
   "bt_constants": "",
   "behavior_tree_code": "",
   "section_name": "欢迎节",
   "triggers": null,
   "node_position": []
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/get-section"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/get-section" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>",
           "section_id": "<Section-Id->"
         }'
```

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

## 列出节

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

列出给定角色的所有叙事节的详细信息。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明       |
| ------------- | --- | -------- |
| character\_id | 字符串 | 你的角色 ID。 |

{% tabs %}
{% tab title="200：成功获取节详情列表 " %}

```json
[
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "123456789-7ddd-dddd-bbbb-424242424242",
    "objective": "",
    "decisions": null,
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "节 1",
    "triggers": null,
    "node_position": []
  },
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "100000789-7ddd-dddd-bbbb-42424242424",
    "objective": "为用户提供历史博物馆导览。",
    "decisions": [
      {
        "criteria": "用户同意参观。",
        "next_section_id": "123456789-7ddd-dddd-bbbb-424242424242"
      }
    ],
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "欢迎节",
    "triggers": null,
    "node_position": []
  }
]
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/list-sections"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/list-sections" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>"
         }'
```

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

## 删除节

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

删除你角色的一个叙事节。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明        |
| ------------- | --- | --------- |
| character\_id | 字符串 | 你的角色 ID。  |
| section\_id   | 字符串 | 要删除的节 ID。 |

{% tabs %}
{% tab title="200：成功删除节 " %}

```json
{"STATUS": "成功"}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/delete-section"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/delete-section" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->"
     }'
```

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

## 创建触发器

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

为你的角色创建新的触发器。

#### 标头

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

#### 请求体

| 名称                   | 类型  | 说明                                    |
| -------------------- | --- | ------------------------------------- |
| character\_id        | 字符串 | 你的角色 ID。                              |
| trigger\_name        | 字符串 | 触发器名称。对角色而言必须唯一。                      |
| trigger\_message     | 字符串 | 触发器消息。通常用于说明触发器被调用的事件。例如：用户进入场景。      |
| desgination\_section | 字符串 | 此触发器的目标节 ID。如果你不想将触发器连接到任何节，请不要传递此字段。 |

{% tabs %}
{% tab title="200：成功创建触发器 " %}

```json
{
    "character_id": "<Your-Character-Id>,
    "trigger_id": "<ID-Of-The-Newly-Created-Trigger>",
    "trigger_name": "开始触发器",
    "trigger_message": "用户已进入博物馆。",
    "destination_section": "<Destination-Section-ID>",
    "node_position": []
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/create-trigger"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "trigger_message":"用户已进入博物馆。",
    "trigger_name":"开始触发器",
    "destination_section": "<要连接的目标节 ID>"
}

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

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

print(response.text)
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/create-trigger" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "trigger_message": "用户已进入博物馆。",
         "trigger_name": "开始触发器",
         "destination_section": "<要连接的目标节 ID>"
     }'
```

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

## 更新触发器

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

编辑触发器。你应通过 updated\_data JSON 发送所有要更新的触发器字段。以下为有效键。

* "trigger\_name": 新触发器名称。必须唯一。
* "trigger\_message": 新触发器消息。
* "destination\_section": 触发器的新目标节 ID。

#### 标头

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

#### 请求体

| 名称            | 类型   | 说明          |
| ------------- | ---- | ----------- |
| character\_id | 字符串  | 你的角色 ID。    |
| updated\_data | JSON | 包含已更新的字段。   |
| trigger\_id   | 字符串  | 要更新的触发器 ID。 |

{% tabs %}
{% tab title="200：成功更新触发器 " %}

```json
{
    "STATUS": "成功",
    "message": "触发器更新成功"
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/update-trigger"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "updated_data": {
        "destination_section":"<New-Destination-Section-Id>",
        "trigger_message":"用户已进入计算机历史博物馆"
    }   
}

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

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

print(response.text)                  
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/update-trigger" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Section-Id>",
         "updated_data": {
             "destination_section": "<New-Destination-Section-Id>",
             "trigger_message": "用户已进入计算机历史博物馆"
         }
     }'
```

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

## 删除触发器

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

删除现有触发器。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明          |
| ------------- | --- | ----------- |
| character\_id | 字符串 | 你的角色 ID。    |
| trigger\_id   | 字符串 | 要删除的触发器 ID。 |

{% tabs %}
{% tab title="200：成功删除触发器 " %}

```json
{
    "STATUS": "成功",
    "message": "触发器删除成功"
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/delete-trigger"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

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

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

print(response.text)                 
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/delete-trigger" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Trigger-Id>"
     }'
```

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

## 获取触发器

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

获取现有触发器的详细信息。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明          |
| ------------- | --- | ----------- |
| character\_id | 字符串 | 你的角色 ID。    |
| trigger\_id   | 字符串 | 要获取的触发器 ID。 |

{% tabs %}
{% tab title="200：成功获取触发器详情 " %}

```json
{
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "trigger_name": "用户进入",
    "trigger_message": "用户已进入博物馆。",
    "destination_section": null,
    "node_position": []
}
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/get-trigger"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

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

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

print(response.text)              
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/get-trigger" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Character-Id>",
           "trigger_id": "<Trigger-Id>"
         }'
```

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

## 列出触发器

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

列出某个角色的所有触发器。

#### 标头

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

#### 请求体

| 名称            | 类型  | 说明       |
| ------------- | --- | -------- |
| character\_id | 字符串 | 你的角色 ID。 |

{% tabs %}
{% tab title="200：成功获取触发器详情列表 " %}

```json
[
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID1>",
    "trigger_name": "触发器 1",
    "trigger_message": "",
    "destination_section": null,
    "node_position": []
  },
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID2>",
    "trigger_name": "用户进入",
    "trigger_message": "用户已进入博物馆。",
    "destination_section": null,
    "node_position": [ ]
  }
]
```

{% endtab %}

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

```json
{
    "ERROR": "提供的 API key 无效。"
}
```

{% endtab %}
{% endtabs %}

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

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

```python
import requests
import json

url = "https://api.convai.com/character/narrative/list-triggers"
headers = { 
    'CONVAI-API-KEY': '<您的 API 密钥>',
    'Content-Type': 'application/json'
}

# 创建 JSON 负载的字典
payload = { 
    "character_id":"<Character-Id>", 
}

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

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

print(response.text)              
```

{% endcode %}
{% endtab %}

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

```shell
curl -X POST "https://api.convai.com/character/narrative/list-triggers" \
     -H "CONVAI-API-KEY: <您的 API 密钥>" \
     -H "Content-Type: application/json" \
     -d '{"character_id":"<Character-Id>"}'
```

{% endcode %}
{% 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/narrative-design-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.