Character API
All the available APIs needed to create your own intelligent character with Convai.
Access Convai endpoints for developing and interacting with an intelligent character, starting with some information like the character name, some background information, and a voice. Unveil the character to the end-user through your custom UI or through other services where Convai provides custom plugins/libraries, for them to have engaging conversations with your creation.
Missing Something? In case you are missing something that is essential for your innovative application, please reach out to us through the Contact Page form on our page and we will positively get back to you for more discussion on the requirement.
post
https://api.convai.com/character
/create
This endpoint is called to create a new character.
Here are some sample codes to demonstrate the request format for the endpoint -->
Python
cURL
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)
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."
}'e
post
https://api.convai.com/character
/update
This endpoint is called to update the details of an existing character
For the list of supported voices please refer to the table in Text To Speech API
Here are some sample codes to demonstrate the request format for the endpoint -->
Python
cURL
import requests
import json
url = "https://api.convai.com/character/update"
payload = json.dumps({
"charID": "<character ID>",
"backstory": "Raymond Reddington is a highly intelligent, highly driven individual with developed sociopathic tendencies. This appears to be the product of PTSD (post-traumatic stress disorder) as there are no signs that he was born this way. Sly, manipulative, and charming, Red is always three steps ahead of everyone else, and is determined to keep himself a mystery. As he puts it, “I’m a criminal. Criminals are notorious liars. Everything about me is a lie.” That’s probably true, actually, but who knows for sure. He dislikes rude people, which is something that Agent Ressler pointed out after Red let a notorious drug dealer get away with false identification. Ressler mentioned that Red wouldn’t let the drug dealer get away because he was rude and Red doesn’t like rude people. Red responded with, “He is on my jet.”",
"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)
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": "Raymond Reddington is a highly intelligent, highly driven individual with developed sociopathic tendencies. This appears to be the product of PTSD (post traumatic stress disorder) as there are no signs that he was born this way. Sly, manipulative, and charming, Red is always three steps ahead of everyone else, and is determined to keep himself a mystery. As he puts it, “I’m a criminal. Criminals are notorious liars. Everything about me is a lie.” That’s probably true, actually, but who knows for sure. He dislikes rude people, which is something that Agent Ressler pointed out after Red let a notorious drug dealer get away with false identification. Ressler mentioned that Red wouldn’t let the drug dealer get away because he was rude and Red doesn’t like rude people. Red responded with, “He is on my jet.”",
"voiceType": "US MALE 1",
"charName": "Raymond Reddington"
}'\
Get Details of Characters
post
https://api.convai.com/character
/get
This endpoint is called to fetch all the necessary details of a particular character.
Here are some sample codes to demonstrate the request format for the endpoint -->
Search by charID:
Python
cURL
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)
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>"
}'
Search by charName:
Python
cURL
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)
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>"
}'
post
https"//api.convai.com/character
/getResponse
This endpoint is called to converse with the character
Important Points to Remember:
- The API endpoint expects the request body to contain only one type of input (either text input, via userText, or audio input via file). Including both types of input or none will result in an error.
- We strictly adhere to OpenAI’s Content Policy for API usage and expect the user to respect the rules as well, to prevent the generation of toxic and inappropriate content.
- Please note that the body of the request should be form-data. This is to maintain consistency of format while uploading audio files.
- Sending -1 as the session ID value starts a new chat session. Use the returned session ID in subsequent getResponse requests to ensure conversation context is maintained.
- While sending an audio file, make sure that it should have a bit depth of at least 16 bits or higher.
Here are some sample codes to demonstrate the request format for the endpoint -->
Request with text only:
Python
cURL
import requests
import json
import base64
url = "https://api.convai.com/character/getResponse"
payload={
'userText': 'What is your name ?',
'charID': '<your character id>',
'sessionID': '-1',
'voiceResponse': 'True'
}
headers = {
'CONVAI-API-KEY': '<your api key>'
}
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 --location --request POST 'https://api.convai.com/character/getResponse' \
--header 'CONVAI-API-KEY: <your api key>' \
--form 'userText="What is your name ?"' \
--form 'charID="<your character id>"' \
--form 'sessionID="-1"' \
--form 'voiceResponse="True"'
Request with audio only:
Python
cURL
import requests
import json
import base64
url = "https://api.convai.com/character/getResponse"
payload={
'charID': '<your character id>',
'sessionID': '-1',
'responseLevel': '5',
'voiceResponse': 'True'}
files=[
('file',('audio.wav',open('<path to the audio file audio.wav>','rb'),'audio/wav'))
]
headers = {
'CONVAI-API-KEY': '<your api key>'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
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 --location --request POST 'https://api.convai.com/character/getResponse' \
--header 'CONVAI-API-KEY: <your api key>' \
--form 'charID="<your character id>"' \
--form 'sessionID="-1"' \
--form 'voiceResponse="True"' \
--form 'file=@"<path to the audio file audio.wav>"'
Last modified 1mo ago