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 harris.rothaermel@gmail.com
An API key will follow this format:
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).
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. |
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. |
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. |
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. |
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 harris.rothaermel@gmail.com.
Last updated