Skip to main content

Characters

Create Character​

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters

Initiates the creation of a character that requires subsequent deployment for activation. The character can't be used in conversation until it is deployed.

Request Body​

characterrequired

Character

The character to create.

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
-d '{
    "defaultCharacterDescription": {
        "description": "Fearless warrior",
        "motivation": "Likes to fight against dragons",
        "givenName": "Axeon the Enchanted"
    }
}'

Get Character​

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters

Get a specific character within a workspace.

Request Body​

viewoptional

CharacterItemView

Specifies what information to include in the response.

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Deploy Character​

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}:deploy

Asynchronously deploys the character. The deployment process is managed as a long-running operation (LRO). The progress and result of this operation should be monitored using the returned LRO object. Upon successful completion, all characters will reflect the updates during their interactions. In the event of a failure, the operation should be retried.

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}:deploy' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

List Characters​

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters

Returns a list of characters that can be filtered by several criteria. When using pagination, ensure that all other parameters provided initially remain unchanged.

Filters can be applied to ListCommonKnowledgeRequest. Filters follow the Google AIP-160 guidelines.

  • Single Filter: This filter accepts only the full resource name of the character. For example, to filter a specific character, use character.name=workspaces/{workspace_id}/character/{uuid}.
  • Multiple Filters: You can also combine multiple filters using the 'OR' condition. For instance, to filter by two different characters, use character.name=workspaces/{workspace_id}/character/{uuid1} OR character.name=workspaces/{workspace_id}/character/{uuid2}.

Request Body​

pageSizeoptional

int32

Max number of items to retrieve per page. Default is 50.

pageTokenoptional

string

A page token received from a previous ListCharacterRequest call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListCharactersRequest must remain the same.

viewoptional

CharacterView

Specifies whether standard or with scenes character list will be returned in the response.

filteroptional

string

Character filter. Filters follow the Google AIP-160 guidelines

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Update Character​

PATCH https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}

Updates the specified character. Changes to the character are not reflected in conversation until the character is deployed.

Request Body​

characterrequired

Character

The character to update.

curl -L -X PATCH 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}}/characters/{character_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
-d '{
    "defaultCharacterDescription": {
        "description": "Likes to sleep and sing."
    }
}'

Delete Character​

DELETE https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}

Delete a specific character within a workspace.

curl -L -X DELETE 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Check Deployment Status​

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}/operations/{operation_id}

Retrieves the current status of a long-running operation. Clients can use it to periodically poll for the operation's result, following the interval recommendations provided by the API service. This approach is useful for tracking the progress and completion status of operations that are not immediately finalized.

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}/operations/{operation_id}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Schemas

Character​

nameoptional

string

Immutable. This field can't be set or changed via API. This field can't Automatically generated resource name by the system based on given_name property.

defaultCharacterDescriptionoptional

CharacterDescription

Structured default character description.

defaultCharacterAssetsoptional

CharacterAssets

Structured list of different assets associated with the character.

initialMoodoptional

CharacterInitialMood

Structured character initial mood.

personalityoptional

CharacterPersonality

Structured character personality.

commonKnowledgeoptional

string

List of assigned common knowledge references.

socialRankoptional

float

Character social rank - the insecure/confident slider’s setting. Affects character conversation. For more details.

scenesoptional

Scene

The list of linked scenes to the character. This field is propagated only for list characters method when CharacterView::WITH_SCENE is set.

personalKnowledgeoptional

PersonalKnowledge

Information that character knows about.

metaoptional

Meta

Immutable. This field can't be set or changed via API. Meta character information.

emotionalFluidityoptional

float

Affects character conversation. Range = [0, 1]. 0 - rare emotions change. 1 - frequent emotions change. For more details.

sharePortalInfooptional

SharedPortalInfo

Immutable. This field can't be set or changed via API. Character portal/arcade info.

yamlConfigoptional

string

Goals and actions v2. For more details.

safetyConfigoptional

SafetyConfigEntry

List of safety configs. For more details.

relationshipoptional

Relationship

Describes character's relationships specification.

cognitiveControloptional

CognitiveControl

Describes degree of cognitive control.

CharacterAssets​

voiceoptional

Voice

Reference to the voice resource used by that character.

avatarImgoptional

string

Link to uploaded and resized avatar image for character provided by user.

avatarImgOriginaloptional

string

Link to uploaded original avatar image for character provided by user.

avatarTypeoptional

AvatarType

Avatar type.

avatarDisplayImageSourceoptional

AvatarDisplayImageSource

Specifies the source from which the 2D avatar image of the character is derived.

rpmAvataroptional

RpmAvatar

RPM avatar.

innequinAvataroptional

InnequinAvatar

Innequin avatar.

CharacterDescription​

given_nameoptional

string

Name of the character. Defaults to 'Character' if empty.

descriptionoptional

string

Free form description to design character's behavior and purpose. Supposed to be composite prompt including NPC info, history and initial scene's state.

pronounoptional

Pronoun

Pronoun of the character. Defaults to PRONOUN_UNSPECIFIED.

nicknamesoptional

string

List of commonly used alternative names of this character.

motivationoptional

string

Motivation of the character.

wikipediaUrioptional

string

Uri to wikipedia for well-known character for additional data extraction. For more details

exampleDialogoptional

string

Example of character dialog. For more details

exampleDialogStyleoptional

ExampleDialogStyle

Enumerated example dialog style. For more details of dialog style.

personalityAdjectivesoptional

string

List of adjectives describing character: "eloquent", "charming", "aggressive"

lifeStageoptional

LifeStage

Specify the stage of life for character.

hobbyOrInterestsoptional

string

Repeated field of strings representing the character's hobbies or interests.

characterRoleoptional

string

Role of the character.

narrativeActionsEnabledoptional

bool

Indicates if narrated actions and scenarios are enabled on this character. For more details

customDialogStylesoptional

CustomDialogStyle

CustomDialogStyle indicates designs are using a new layout for Character pages.

flawsoptional

string

Flaws & Challenges.

dialogResponseLengthoptional

DialogResponseLength

Specify dialog style response length.

CharacterInitialMood​

joyoptional

int32

Determines Sadness(-100)/Joy(100) mood.

fearoptional

int32

Determines Anger(-100)/Fear(100) mood.

trustoptional

int32

Determines Disgust(-100)/Trust(100) mood.

surpriseoptional

int32

Determines Anticipation(-100)/Surprise(100) mood.

CharacterPersonality​

positiveoptional

int32

Determines Negative(-100)/Positive(100).

peacefuloptional

int32

Determines Aggressive(-100)/Peaceful(100).

openoptional

int32

Determines Cautious(-100)/Open(100).

extravertoptional

int32

Determines Introvert(-100)/Extravert(100).

CustomDialogStyle​

uuidoptional

string

Universally unique identifier automatically generated by system.

displayNameoptional

string

The name of the custom dialog style.

isActiveoptional

bool

Is this custom style enabled or not.

adjectivesoptional

string

The list of available adjectives. Adjectives field should be multi-select (up to 3): anxious, contemplative, curt, expressive, hilarious, inquisitive, intense, mischievous, snarky, sympathetic, talkative unflinching etc

colloquialismoptional

string

The name of the new dialog style: business abbreviations, cowboy lingo, hackneyed cliches, Internet meme slang, medical terminology, movie quotes, obscure idioms, Orwellian newspeak, sports metaphors, technical jargon

Fact​

textoptional

string

Text data of the fact. Max length is 255 symbols.

InnequinAvatar​

avatarBackgroundoptional

string

Reference to avatar material asset.

avatarMaterialoptional

string

Reference to avatar background asset.

avatarImgUrioptional

string

Uri to store innequin image.

InteractionCountStat​

totalCountoptional

int32

Total log counters.

totalUnreadCountoptional

int32

Total unread log counters.

totalReadCountoptional

int32

Total read log counters.

Meta​

totalCommonKnowledgeoptional

int32

Immutable. This field can't be set or changed via API. Indicates the amount of common knowledge created in character.

goalsVersionoptional

int32

Immutable. This field can't be set or changed via API. Goals version used by character.

PersonalKnowledge​

uuidoptional

string

Unique (throughout the entire service) universally unique identifier automatically generated by system.

factsoptional

Fact

List of facts. Max size 10000.

Relationship​

enabledoptional

bool

Enables character's relationships.

fluidityoptional

float

Determines dynamics of relationship changes (-1, 1), where -1 is slow changes and 1 is fast changes.

RpmAvatar​

rpmModelUrioptional

string

Link to the readyplayerme avatar model. To be used in the companion app. Updated through the separate method.

rpmImageUrioptional

string

Link to the rendered readyplayerme avatar image. Used to display avatar image in studio and companion app. Updated through the separate method.

rpmImageUriPortraitoptional

string

Link to the rendered readyplayerme avatar portrait image. in studio and companion app. Updated through the separate method.

rpmImageUriPostureoptional

string

Link to rendered readyplayerme avatar posture image. To be used in the in studio and companion app. Updated through the separate method.

SafetyConfigEntry​

keyoptional

string

valueoptional

SafetyLevel

AvatarDisplayImageSource​

Determines which 2D image will be displayed for current character.

NameNumberDescription
AVATAR_DISPLAY_IMAGE_SOURCE_UNSPECIFIED0Unspecified.
RPM_IMAGE1Use RPM image, that is created from RPM avatar model.
INNEQUIN_IMAGE2Use Innequin image that is created from Innequin avatar model.
USER_PROVIDED_IMAGE3Use user provided image.

AvatarType​

Possible values of avatar type. Default is AVATAR_TYPE_UNSPECIFIED. Determines which 3D avatar system is used in UI.

NameNumberDescription
AVATAR_TYPE_UNSPECIFIED0Unspecified.
AVATAR_TYPE_RPM1RPM.
AVATAR_TYPE_INWORLD2inworld/innequin

CharacterItemView​

CharacterDetailView defines what dependency info should be provided in response. For now only Meta(s) part is optional.

NameNumberDescription
CHARACTER_ITEM_VIEW_UNSPECIFIED0Not specified, equivalent to DEFAULT.
CHARACTER_ITEM_VIEW_DEFAULT1Character information default.
CHARACTER_ITEM_VIEW_WITH_META2Character representation with meta.

CharacterSharePurpose​

CharacterShareType defines the purpose of share the character(where it is expected to be used):

  • in oculus
  • in portal simulator(standalone)

    • NameNumberDescription
    CHARACTER_SHARE_PURPOSE_UNSPECIFIED0Not specified, equivalent to DEFAULT.
    CHARACTER_SHARE_PURPOSE_OCULUS1Character shared for the oculus device.
    CHARACTER_SHARE_PURPOSE_PORTAL2Character shared for the portal simulator.

    CharacterView​

    CharacterView defines what dependency info should be provided in response. For now only Scene(s) part is optional

    NameNumberDescription
    CHARACTER_VIEW_UNSPECIFIED0Not specified, equivalent to DEFAULT.
    CHARACTER_VIEW_DEFAULT1Character information without scene information.
    CHARACTER_VIEW_WITH_SCENES2Character representation with scene.

    CognitiveControl​

    Specifies degree of cognitive control.

    NameNumberDescription
    COGNITIVE_CONTROL_UNSPECIFIED0Missing value.
    COGNITIVE_CONTROL_NONE1None.
    COGNITIVE_CONTROL_MILD2Mild control.
    COGNITIVE_CONTROL_STRICT3Strict control.

    DialogResponseLength​

    response_length represents dialog style response length

    NameNumberDescription
    DIALOG_RESPONSE_LENGTH_UNSPECIFIED0No response length specified / unknown.
    DIALOG_RESPONSE_LENGTH_VERY_SHORT1-2 very short response
    DIALOG_RESPONSE_LENGTH_SHORT2-1 short response
    DIALOG_RESPONSE_LENGTH_MEDIUM30 medium (neutral) response
    DIALOG_RESPONSE_LENGTH_LONG41 long response
    DIALOG_RESPONSE_LENGTH_VERY_LONG52 very long response

    ExampleDialogStyle​

    List of styles for example dialogue.

    NameNumberDescription
    EXAMPLE_DIALOG_STYLE_UNSPECIFIED0No style specified / unknown.
    EXAMPLE_DIALOG_STYLE_DEFAULT1The default character dialog is engaging and realistic.
    EXAMPLE_DIALOG_STYLE_BUBBLY2The dialog style is thoughtful, energetic, and friendly.
    EXAMPLE_DIALOG_STYLE_FORMAL3The dialog style is formal and matter-of-fact.
    EXAMPLE_DIALOG_STYLE_BLUNT4The dialog style is short, direct, and to the point.
    EXAMPLE_DIALOG_STYLE_INQUISITIVE5The dialog style is inquisitive, which will usually include a question.
    EXAMPLE_DIALOG_STYLE_COMMANDING6The dialog style is intense and determined.
    EXAMPLE_DIALOG_STYLE_EMPATHETIC7The dialog style is gentle and compassionate.
    EXAMPLE_DIALOG_STYLE_ENTERTAINING8The dialog style is entertaining, animated, and comical.
    EXAMPLE_DIALOG_STYLE_HYPOCHONDRIAC.9The dialog style is neurotic and fearful.
    EXAMPLE_DIALOG_STYLE_LAIDBACK10The dialog style is relaxed, informal, and nonchalant.
    EXAMPLE_DIALOG_STYLE_LONG_WINDED11The dialog style is verbose and meandering.
    EXAMPLE_DIALOG_STYLE_MORAL12The dialog style is principled and incorruptible.
    EXAMPLE_DIALOG_STYLE_MYSTERIOUS13The dialog style is elusive and cryptic.
    EXAMPLE_DIALOG_STYLE_RACONTEUR14The dialog style is entertaining and descriptive.
    EXAMPLE_DIALOG_STYLE_SARCASTIC15The dialog style is snide and contemptuous.
    EXAMPLE_DIALOG_STYLE_TENACIOUS16The dialog style is determined and persistent
    EXAMPLE_DIALOG_STYLE_VILLAINOUS17The dialog style is sinister and cruel.
    EXAMPLE_DIALOG_STYLE_CUSTOM18An custom style selected by user and expected to be specified.

    LifeStage​

    List of life stages for character.

    NameNumberDescription
    LIFE_STAGE_UNSPECIFIED0No stage of life specified / unknown.
    LIFE_STAGE_ADOLESCENCE5Adolescence.
    LIFE_STAGE_YOUNG_ADULTHOOD6Young adulthood.
    LIFE_STAGE_MIDDLE_ADULTHOOD7Middle adulthood.
    LIFE_STAGE_LATE_ADULTHOOD8Late adulthood.
    LIFE_STAGE_CHILDHOOD9Childhood.

    Pronoun​

    Structure describing the pronounce for the character.

    NameNumberDescription
    PRONOUN_UNSPECIFIED0No pronoun specified / unknown
    PRONOUN_FEMALE1She/Her/Hers
    PRONOUN_MALE2He/Him/His
    PRONOUN_OTHER3They/Them/Theirs

    SafetyLevel​

    Topic-based safety aggressiveness level config.

    NameNumberDescription
    SAFETY_LEVEL_UNSPECIFIED0Missing value.
    SAFETY_LEVEL_NO_CONTROL1No safety filter is applied to the given topic.
    SAFETY_LEVEL_MILD_CONTROL2Allows 'level 0' of given topic.
    SAFETY_LEVEL_STRICT_CONTROL3All filters applied to the given topic.