Quickstart

Generate your first conversation in a few minutes!

Create Your Character(s)

Characters are a vital building block of Ember AI's API. Each Character object is stored within our databases and represents an instance of a virtual character. The only information needed to create a virtual character is:

• First Name

• Last Name

• Background

The first and last name of a character helps our AI systems identify the character in natural text.

The background provides the majority of the information regarding a character to be used by the AI systems in generating responses. This background can be as short or long as desired, but the best results have been found by using a few compact and dense sentences to provide the most important info about a character.

Examples:

Medieval Fantasy: Roy Lightclaw is a human and a novice merchant. His most developed skills are charisma, and intelligence, alongside his average dexterity, but slightly below average strength, and constitution. Roy Lightclaw's home is the town of Lightclaw Manor but is currently in Milvar to sell his collection of magic scrolls.

Modern Parody: Richard Hendricks is a Stanford dropout and coder at tech company Hooli. Richard quits his job to pursue his compression application Pied Piper. The company initially starts out as a simple data compression platform, but when this, and a video chat that Dinesh created with the algorithm fails, Richard pivots toward creating a new, decentralized internet, called PiperNet. For the most part, Richard is shy and weak-willed and does not have much of a temper, but when he finally reaches his limit, is prone to intimidating explosions of anger. Richard is constantly struggling with the demands of the business world, preferring instead to disappear into the coding of his application, but realizes that as CEO he must do more.

API Request:

To create a character, you'll need your API key which will be given to you once onboarded.

To be onboarded please contact Harris Rothaermel at [e-mail]

An API key will follow this format:

sk_live_103b56fb0a694b2fa2c28865fb70e2c9

API keys must be attached as an Authorization header in the Bearer format for all requests that modify the state of an object (POST, PATCH, DELETE).

Authorization: Bearer sk_live_103b56fb0a694b2fa2c28865fb70e2c9

To create a character, a POST request should be sent to https://getember.ai/api/character with the specified information from above.

Create Character

POST https://getember.ai/api/character

This endpoint creates a new character object with the provided properties.

Headers

Name	Type	Description
Authorization	string	A Bearer token with your provided API key.

Request Body

Name	Type	Description
firstName	string	The first name of the character to be created.
lastName	string	The last name of the character to be created.
background	string	A written background of the character to be created. This can range from a few words to a paragraph.

201 The character was successfully created and inserted into the database. The insertedId field provides the ObjectID of the new character object.

{
    "acknowledged": true,
    "insertedId": "61577fc9765bf80c0f1d9024"
}

400 The request is invalid: It may be missing required arguments or be in an incorrect format.

{
    "error": "Missing lastName from body."
}

401 The Authorization header is missing or does not contain a valid Bearer API key.

{}

500 If this error persists please contact support with the desired request and provided error.

{
    "error": "Internal Server Error."
}

In order to create the highest quality responses, real-life humans that will be interacting with virtual characters will need a Character object that contains their background. This background will naturally be different depending on the role the user is taking on in the specific application e.g. the main character of a Skyrim-like video game vs a customer to a virtual store.

Create Your Conversation(s)

Conversation objects are the ying to the character object's yang. Both are needed to utilize Ember AI's natural language processing AI to generate responses.

Once one or more characters have been created, a conversation object can be created, and requires the following information:

• Context

• Participants

• Next Speaker

Context:

Context is similar to backgrounds for characters but describes the purpose and surrounding conditions of the conversation. This can also be as short or as long as desired, but the best results are found when the context includes writing that flows naturally into a conversation.

Examples:

Medieval Fantasy:

• Roy Lightclaw walks by Emilia Stormwind, and says "Oh hey Emilia, haven't seen you in a while."

• Boriv runs into Althaea, an old friend who he's kept in touch with in an on and off manor, while walking towards the markets of Windfall. They stop, and start talking.

Modern Parody: Pied Piper officially pivots to PiperChat, a video chat app created by Dinesh, which is steadily gaining users and is superior to all competitors. However, the team is unable to gain funding due to the scandal of their click farm upticks and demise of the compression platform. After clashing with Dinesh and Gilfoyle over the development of the app and attempting to gain investment from Hanneman, Richard realizes that he can't be the CEO of a project he doesn't believe in. Just as the team prepares to replace him with Big Head, he quits his position and signs over his equity in exchange for use of his algorithm and the Pied Piper brand in the pursuit of a more ambitious goal: a decentralized internet based on users and smartphones instead of large companies and mainframes. He suggests Dinesh become the CEO of PiperChat, which was his creation. In a conversation between the two, Dinesh says, "After every VC in town shut us down, we decided the only way to stay alive until we hit a million users was to cut our server usage. Remember?"

Participants:

Each conversation requires at least 1 virtual character to be a participant. When there is only 1 participant, the conversation can be assumed to be the virtual character talking to themselves or speaking out to a crowd with no response, depending on the developer-provided context.

Next Speaker

The next speaker parameter determines which character should generate a response next. This variable will change over time as responses are generated, and will not follow a strict back-and-forth pattern. The natural language AI models will modify the next speaker variable with who it believes should speak next as it generates responses. This allows for more natural, and free-flowing conversation where a character can speak multiple lines before switching to a different character.

Create Conversation

POST https://getember.ai/api/conversation

This endpoint creates a new conversation object with the provided properties.

Headers

Name	Type	Description
Authorization	string	A Bearer token with your provided API key.

Request Body

Name	Type	Description
context	string	A written context of the conversation instance. This can range from a few words to a paragraph.
participants	array	An array of character ObjectIds that are participating in the conversation instance.
nextSpeaker	string	The ObjectID of the virtual character that will speak next in the conversation.

201 The conversation was successfully created and inserted into the database. The insertedId field provides the ObjectId of the new conversation object.

{
    "acknowledged": true,
    "insertedId": "61578e44765bf80c0f1d9027"
}

400 The request is invalid: It may be missing required arguments or be in an incorrect format.

{
    "error": "Missing context from body."
}

401 The Authorization header is missing or does not contain a valid Bearer API key.

{}

500 If this error persists please contact support with the desired request and the provided error.

{
    "error: "Internal Server Error"
}

Generate Response

Once a conversation has been created, responses can be generated using the natural language processing models. Once a response has been generated, the conversation's log and nextSpeaker value will be returned to the client and will be automatically updated in the database.

Generate Response

POST https://getember.ai/api/conversation/generate

This endpoint will generate the next response in the provided conversation, and update its state.

Headers

Name	Type	Description
Authorization	string	A Bearer token with your provided API key.

Request Body

Name	Type	Description
id	string	The ObjectID of the desired conversation to generate a response from.

200 Conversational response successfully generated.

{
    "response": "Yeah, well, that only works until we hit a million users.",
    "nextSpeaker": "61578d94765bf80c0f1d9026"
}

400 The request is invalid: It may be missing required arguments or be in an incorrect format.

{
    "error": "Missing id from body."
}

401 The Authorization header is missing or does not contain a valid Bearer API key.

{}

500 If this error persists please contact support with the desired request and the provided error.

{
    "error": "Internal Server Error."
}

Append Response

It's often the case where we'll want to interleave generated virtual character responses with natural responses from real users. To do so, it's best to create a Character object with the real user's background, and then include them as part of the Conversation object. When appending a response, the natural language model will calculate who it thinks the next speaker should be and return that Character's ObjectId.

Append Response

POST https://getember.ai/api/conversation/append

This endpoint will append the provided response to the specified conversation

Headers

Name	Type	Description
Authorization	string	A Bearer token with your provided API key.

Request Body

Name	Type	Description
conversationId	string	The ObjectID of the desired conversation to append the provided response to.
characterId	string	The ObjectID of the desired character to associate the response to. The endpoint will handle the case where the character is not already a member of the conversation, and add them to it.
response	string	The response to be appended to the conversation log.

200 Response successfully appended to the specified conversation.

{
    "nextSpeaker": "615e18d18de739411e0f36e4"
}

400 The request is invalid: It may be missing required arguments or be in an incorrect format.

{
    "error": "Missing characterId from body."
}

401 The Authorization header is missing or does not contain a valid Bearer API key.

{}

404 Could not find an object provided in this query.

{
    "error": "Unable to find character."
}

500 If this error persists please contact support with the desired request and the provided error.

{
    "error": "Internal Server Error"
}

Congrats! You now have the toolset to create characters, create conversations, generate responses and append custom responses. These are the fundamental building blocks to creating dynamic and natural conversations with virtual characters. If you have any other questions, please feel free to contact support at [e-mail].