交互 API

此页面详细说明你如何与角色交互。

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

与角色交互

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

用户可以实现一个聊天机器人会话，让终端用户与他们的角色进行对话。用户可以通过在所发起的 API 请求中维护 session-id 来保持对话上下文。

请记得查看末尾提到的“重要注意事项”列表。它们包含了成功调用此端点所需的限制和要求的关键信息。

请求头

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

请求体

名称	类型	说明
用户文本*	字符串	与角色交互的用户所发出的查询或输入。
charID*	字符串	用户正在交互的角色 ID。
会话ID*	字符串	用于标识一个对话会话，以保持上下文。
语音响应*	布尔值	生成以角色声音呈现的回复音频文件。
文件*	文件	包含用户查询的音频文件。必须为 WAV 格式且为单声道。
采样率	字符串	所发送音频文件的采样率。
流式	字符串（"True" 或 "False"）	启用 SSE 流式传输，使响应能够实时分块返回，而无需等待完整响应。

200：OK 角色能够为用户生成回复

{
    "charID": "<请求体中发送的角色 ID>",
    "text": "<由语言模型针对该查询生成的回复>",
    "audio": null / "<base64 编码的音频>"
    "sample_rate": null / "<音频采样率（Hz）>"
    "sessionID": "<你的会话 ID。若为新会话，则返回新生成的值；否则返回旧值>"
}

404：未找到，响应生成失败，无法处理请求

400：错误请求 输入有误时

重要注意事项：

• 该 API 端点期望请求体中只包含一种输入类型（要么是文本输入，通过 用户文本，要么是通过 file 提供的音频输入）。同时包含 这两种输入，或者两者都不提供，都会导致错误。
• 我们严格遵守 OpenAI 的内容政策来使用 API，也希望用户同样遵守相关规则，以防生成有毒和不当内容。重复违规将导致 API 密钥被列入黑名单。
• 请注意，请求体应为 form-data。这样做是为了在上传音频文件时保持格式一致。
• 将 -1 作为 session ID 值发送 会开启新的聊天会话。请在后续的 getResponse 请求中使用返回的 session ID，以确保对话上下文得以保持。
• 在发送音频文件时，请确保其具有 位深度 至少为 16 位或更高.

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

请求方式： 仅文本：

Python

import requests
import json
import base64

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

payload={
    'userText': '你叫什么名字？',
    'charID': '<你的角色 ID>',
    'sessionID': '-1',
    'voiceResponse': 'True'
}

headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>'
}

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

data = response.json()

character_response = data["text"]

decode_string = base64.b64decode(data["audio"])

with open('audioResponse.wav','wb') as f:
  f.write(decode_string)

cURL

请求方式： 仅音频：

Python

import requests
import json
import base64

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

payload={
		'charID': '<你的角色 ID>',
		'sessionID': '-1',
		'responseLevel': '5',
		'voiceResponse': 'True'}
files=[
  ('file',('audio.wav',open('<音频文件 audio.wav 的路径>','rb'),'audio/wav'))
]
headers = {
  'CONVAI-API-KEY': '<你的 API 密钥>'
}

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

character_response = data["text"]
sessionID = data["sessionID"]

print("Session ID: ", sessionID)
print("Response: ", character_response)

decode_string = base64.b64decode(data["audio"])

with open('audioResponse.wav','wb') as f:
  f.write(decode_string)

cURL

生成对话选项

POST https://api.convai.com/character/generate-starter-conversation

Generate Starter Conversation API 采用服务器发送事件（SSE）实现。它使用角色背景故事和当前聊天历史，生成下一组可能的后续对话选项。

请求头

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

请求体

名称	类型	说明
角色ID	字符串	要为其生成对话选项的角色 ID。
会话ID	字符串	要生成下一轮对话的会话 ID。将其设为 "-1" 可生成开场对话选项。

200：OK 返回多个 SSE 事件。

# 输出格式：
# 响应将以服务器发送事件（SSE）的形式流式传输。
# 每个事件都会有一个 'data' 字段，其中包含一个字符串，即一条单独的聊天建议。
# 单个事件示例：

data: 我很好奇你有过的最具挑战性的比赛。

# 将收到多个事件，每个事件都包含一条单独的聊天建议。

401 API 密钥验证失败

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

Python

import json
import requests

url = "https://api.convai.com/character/generate-starter-conversation"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
}

form_data = { 
    'charId': '<你的角色 ID>',
    'sessionId': '<你的会话 ID>'
}

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

print(response.text)

cURL