叙事设计 API

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

切换叙事设计

POST https://api.convai.com/character/toggle-is-narrative-driven

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
is_narrative_driven	布尔	将其设置为 true 或 false，以启用或禁用叙事图。

200：OK

{"STATUS": "成功"}

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/toggle-is-narrative-driven"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

创建章节

POST https://api.convai.com/character/narrative/create-section

为你的角色创建新章节。

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
objective	字符串	章节目标
section_name	字符串	章节名称。
updated_character_data	JSON	*忽略* 此字段未被使用。
behavior_tree_code	字符串	*忽略* 此字段未被使用。
bt_constants	字符串	*忽略* 此字段未被使用。

200：OK 章节已创建

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

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/create-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

编辑章节

POST https://api.convai.com/character/narrative/edit-section

编辑你角色的章节。你应将想要更新的该章节所有字段通过 updated_character_data JSON 发送。以下为有效键。

• "section_name"
• "objective"
• "decisions": 这是一个 JSON 列表。列表中的每个条目应具有以下格式。

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
updated_character_data	JSON	包含已更新的字段。
section_id	字符串	要更新的章节 ID。

200：OK 章节已更新

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

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/edit-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

获取章节

POST https://api.convai.com/character/narrative/get-section

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
section_id	字符串	要获取的章节 ID。

200：OK 章节详情

{
   "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": []
}

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/get-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

列出章节

POST https://api.convai.com/character/narrative/list-sections

列出给定角色的所有叙事章节详情。

请求头

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

请求体

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

200：OK 章节详情列表

[
  {
    "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": []
  }
]

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/list-sections"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

删除章节

POST https://api.convai.com/character/narrative/delete-section

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
section_id	字符串	要删除的章节 ID。

200：OK 章节已删除

{"STATUS": "成功"}

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/delete-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)

cURL

创建触发器

POST https://api.convai.com/character/narrative/create-trigger

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
trigger_name	字符串	触发器名称。对一个角色必须唯一。
trigger_message	字符串	触发器消息。通常描述触发器被调用的事件。例如：用户进入了场景。
desgination_section	字符串	此触发器的目标章节 ID。如果你不想将触发器连接到任何章节，请不要传递此字段。

200：OK 触发器已创建

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

401 API 密钥验证失败

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

Python

import requests
import json

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

# 为 JSON 负载创建一个字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "trigger_message":"用户已进入博物馆。",
    "trigger_name":"StartTrigger",
    "destination_section": "<Destination-Section-ID-to-connect-to>"
}

# 将负载转换为 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/narrative/update-trigger

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

• "trigger_name": 新的触发器名称。必须唯一。
• "trigger_message": 新的触发器消息。
• "destination_section": 触发器的新目标章节 ID。

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
updated_data	JSON	包含已更新的字段。
trigger_id	字符串	要更新的触发器 ID。

200：OK 触发器已更新

{
    "STATUS": "Successful",
    "message": "触发器已成功更新"
}

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/update-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)                  

cURL

删除触发器

POST https://api.convai.com/character/narrative/delete-trigger

删除现有触发器。

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
trigger_id	字符串	要删除的触发器 ID。

200：OK 触发器已删除

{
    "STATUS": "Successful",
    "message": "触发器已成功删除"
}

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/delete-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)                 

cURL

获取触发器

POST https://api.convai.com/character/narrative/get-trigger

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

请求头

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

请求体

名称	类型	说明
character_id	字符串	你的角色 ID。
trigger_id	字符串	要获取的触发器 ID。

200：OK 触发器详情

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

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/get-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)              

cURL

列出触发器

POST https://api.convai.com/character/narrative/list-triggers

列出角色的所有触发器。

请求头

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

请求体

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

200：OK 触发器详情列表

[
  {
    "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": "UserEntry",
    "trigger_message": "用户已进入博物馆。",
    "destination_section": null,
    "node_position": [ ]
  }
]

401 API 密钥验证失败

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

Python

import requests
import json

url = "https://api.convai.com/character/narrative/list-triggers"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    '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)              

cURL