Character Base API

All the relevant APIs needed to create your own intelligent AI characters with Convai.

Access Convai endpoints for developing and interacting with an intelligent character, starting with some basic information like the character 's name, background information, and a voice selection. Unveil the character to the end-user through your custom UI or through other services where Convai provides custom plugins/libraries, for users to have engaging conversations with your new characters.

Missing Something? In case you are missing something that is essential for your application, please reach out to us through the [e-mail] email and we'll get to your inquiry shortly!

API access requires an active Enterprise or Partner subscription.

Create Character

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

Users can either use the character creator tool to create their own characters on the platform or use this API endpoint to dynamically create characters, by providing some basic information as defined below.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name	Type	Description
charName*	String	Name of the new character being created.
voiceType*	String	The type of voice the character is expected to have. [Please refer to the list of available voices in the Text to Speech API]
backstory*	String	Basic background information of the character to start with.
actions	String	A list of actions for the character to choose from, to be performed by the character based on the interactions with the user.

201: Created A new character has bee created with the necessary details

{
    "charID": "<character id for new character>"
}

400: Bad Request The registration of the new character has failed

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

401 API Key validation has failed

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

Here are some sample codes to demonstrate the request format for the endpoint -->

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)

cURL

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."
}'

Update Character

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

Users can update some of the existing details of a character that has been previously created. Users need to only pass any new character information that needs to be updated. The rest of the character information will not be changed.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name	Type	Description
charID*	String	Character ID of the character to update for.
charName	String	New name of the character
backstory	String	Updated backstory
voiceType	String	New voice type of the character [Please refer to the list of available voices in the Text to Speech API]
action	String	New list of actions for the character
languageCodes	List <String>	The list of language codes, the character needs to support [Please refer to the list of available languages in the Text to Speech API]

200: OK The details have been updated successfully

{
   "STATUS": "SUCCESS"
}

400: Bad Request The update might be unsuccessful due to various reason

{
    "ERROR": "Could not fetch character details from all_characters table." / 
             "Could not update character backstory." / 
             "Could not update all_characters table."
}

401 API Key validation has failed

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

Here are some sample codes to demonstrate the request format for the endpoint -->

Python

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

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

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

Users can retrieve all the information about a particular character that they have created or that has been listed as public.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user.

Request Body

Name	Type	Description
charID*	String	Character ID of the character for which to fetch all the details.

200: OK Returns all the information of the corresponding character

{
    "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>"
}

400: Bad Request Failed to fetch the information. Check if the character-id is valid

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

Here are some sample codes to demonstrate the request format for the endpoint -->

Search by charID:

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)

cURL

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

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

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>"
}'

Clone Character

POST https://api.convai.com/user/clone_character

Users can clone their character using this API.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user.

Request Body

Name	Type	Description
charID*	String	ID of the character to Clone.
KB	Bool	True, if KB should be cloned as well. Else False. Default is False.

200: OK Character is successfully Cloned.

{
    "charID": "<id of the newly created cloned character>"
}

Here are some sample codes to demonstrate the request format for the endpoint -->

Python

import requests
import json

url = "https://api.convai.com/user/clone_character"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
  'Content-Type': 'application/json'
}

# Create a dictionary for the form data
payload = { 
    'charID': '<Your-Character-Id>'
}


# Convert the payload to JSON
json_payload = json.dumps(payload)

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

print(response.text)

cURL

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>"}'

Delete Character

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

Delete an existing character using this command. Please be careful hat this action is irreversible and once deleted, the character cannot be recovered.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user.

Request Body

Name	Type	Description
charID*	String	ID of the character to Delete.

200: OK Character successfully deleted

{
    "STATUS": "SUCCESS"
}

Here are some sample codes to demonstrate the request format for the endpoint -->

Python

import requests
import json

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


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
  'Content-Type': 'application/json'
}

# Create a dictionary for the form data
payload = { 
    'charID': '<Your-Character-Id>'
}


# Convert the payload to JSON
json_payload = json.dumps(payload)

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

print(response.text)

cURL

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>"}'