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 [email protected]
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.
post
https://getember.ai/api/
character
Create Character
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.
post
https://getember.ai/api/
conversation
Create 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.
post
https://getember.ai/api/
conversation/generate
Generate Response

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.
post
https://getember.ai/api/
conversation/append
Append Response
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 [email protected].