LogoLogo
PlaygroundVideosBlogPricing
  • Welcome
  • Convai Playground
    • Playground Walkthrough
    • Get Started
    • Character Creator Tool
      • Create Character
      • Language and Speech
      • Knowledge Bank
      • Personality and Style
      • State of Mind
      • Memory
      • Actions
      • Narrative Design
      • Character Versioning
    • F.A.Q
  • Plugins & Integrations
    • Introduction
    • Unity Plugin
      • Pre-Requisites
      • Compatibility
      • Downloads
        • Limitations of WebGL Plugin
      • Setting Up Unity Plugin
      • Troubleshooting Guide
        • Disable Assembly Validation
        • Missing Newtonsoft Json
        • Microphone Permission Issues
        • Default Animations Incompatibility
        • Animations have Facial Blendshapes
        • Jaw Bone in Avatar is not Free
        • macOS Permission Issues
      • Creating a Convai Powered Scene from Template
      • Importing Ready Player Me (RPM) Characters
      • Importing Custom Characters
      • Adding Actions to your Character
      • Adding Lip-Sync to your Character
      • Adding Narrative Design to your Character
        • Narrative Design Keys
      • Adding NPC to NPC Conversation
      • Adding Scene Reference and Point-At Crosshairs
      • Utilities
        • Character Emotion
        • Player Data Container
        • Long Term Memory
        • Language Support
        • Managing sessionID Locally
        • Transcript UI System
        • Pre-built UI Prefabs
        • Input Management
        • Notification System
        • Settings Panel
        • Dynamic Information Context
      • Building For Supported Platforms
        • Building for iOS/iPadOS
        • Building for WebGL
        • Convai XR
          • Building for VR
            • VR Automatic Installation
            • VR Manual Installation
          • Building for MR
            • MR Automatic Installation
            • MR Manual Installation
          • Building for AR
          • Interacting with XR UI Elements
        • Building for macOS Universal apps
      • Changelogs
      • Tutorials
        • Narrative Design
        • NPC2NPC
    • Unreal Engine
      • Supported Platforms
      • Installation
      • Guides
        • Dynamic Environment Info
        • Change AI Character Movement Speed
        • Integration with Pixel Streaming
        • Adjust Interaction Radius
        • Creating MetaHuman Characters
          • Adding MetaHuman
          • Adding LipSync to MetaHuman (From plugin version 3.0.0 or later )
          • Change the Parent Class for MetaHuman
          • Change the parent class for Player.
          • Adding LipSync to MetaHuman (Deprecated)
        • Creating ReadyPlayerMe Characters
          • Download Plugins
          • Adding ReadyPlayerMe Character
          • Change the parent class for Player.
        • Creating Reallusion Characters
          • Creating a Reallusion Character
          • Importing Reallusion character and setting up the Convai plugin
          • Binding objects to Reallusion Character
        • Event-Aware Convai Characters
        • Operations Based on the Presence of Certain Words
        • Narrative Design
          • Narrative Design Trigger
          • Narrative Design Keys
        • Actions Guide
          • Stage 1: Default Actions
            • Moves To
            • Follows
          • Stage 2: Custom Actions
            • Simple actions
            • Adding Descriptions to Actions
          • Stage 3: Custom Actions with Single Parameter
          • Main Character and Attention Object
        • Customization
          • Push to Talk
          • Alter Character Response Audio Rate
        • Speech To Text Transcription
        • Enable Multiplayer Support
        • 3D Chat Widget
        • Long Term Memory
        • Saving and Loading Session
      • Blueprints Reference
        • Convai Player
        • Convai Chatbot
        • Convai Environment
        • Convai Object Entry
        • Convai Result Action
        • Convai Extra Params
        • Speech To Text
        • Text To Speech
        • Utility Functions
      • Troubleshoot Guide
        • Missing Unreal Engine Tool Set in Microsoft Visual Studio Toolchain
        • Convai Module Not Found
        • MetaHuman Plugin Conflict
        • Failure to Load Character IDs
      • Microphone Settings
        • Set Audio Gain
        • Set Microphone
        • Microphone test
        • List Microphone Devices
      • Mac Microphone Permission: Required for UE 5.0 and 5.3
      • Guides V2 (Under Development)
        • Getting Started
          • Installation
          • Simple Talking Cube
          • Adding Premade Chat and Settings UI
    • Web Plugin
      • PlayCanvas Plugin
        • Adding External Script
        • First Person View
        • Adding characters to scene
        • Character Animations
        • Convai Integration
        • Chat Overlay
      • Convai Web SDK
        • Getting Started
        • Facial Expressions
        • Actions
      • JavaScript Chat UI SDK
        • Getting Started
        • ChatBubble Props
      • Narrative Design Guide
        • Narrative Design Triggers
        • Narrative Design Keys
      • GLB Characters for Convai
      • GLB/FBX animations for Convai
    • Modding Framework
      • Modding Cyberpunk 2077
    • Other Integrations
      • Roblox
        • Sample Game 1
        • Sample Game 2
        • Code Example
          • Character Conversation API
      • Discord
        • Create a Discord Bot
        • Hosting Discord Bot from Personal Server
        • Hosting Discord Bot from Replit
      • Omniverse Extension
      • Third-Party API Integrations
        • ElevenLabs API Integration
  • Reference
    • Core API Reference
      • Character Base API
      • Interaction API
      • Core AI Setting API
      • Backstory API
      • Chat History API
      • Knowledge Bank API
      • Narrative Design API
      • Action API
      • Language List API
      • Voice List API
      • Character List API
      • Evaluation API
Powered by GitBook
On this page
  • Convai's Character List API endpoint
  • Request
  • Response
  • Sample Code Snippet

Was this helpful?

  1. Reference
  2. Core API Reference

Character List API

API to retrieve the list of characters, created by a user.

PreviousVoice List APINextEvaluation API

Last updated 2 months ago

Was this helpful?

Convai's Character List API endpoint

POST

This endpoint is called to get the list of characters for a user account. The character list includes information regarding all the characters.

Request

The request body only requires the following header field:

Headers

Field Name
Type
Value / Description

CONVAI-API-KEY*

String

User's Convai API Key

Response

On success, the API will return a nested JSON object in the following format :

{
  "characters": [
    {
      "character_name": "Rafael",
      "collection_name": "convai_default_collection",
      "user_id": "SOME_USER_ID",
      "character_id": "SOME_CHAR_ID",
      "model_type": "RPM-3D",
      "state_names": [],
      "state_links": [],
      "listing": "unlisted",
      "voice_type": "SOME_VOICE",
      "voice_pitch": 0.0,
      "blockchain": "NULL",
      "contract_address": "NULL",
      "mint_address": "NULL",
      "owner_address": "NULL",
      "timestamp": "2023-11-07T02:57:59",
      "character_actions": [
        "laugh",
        "walk",
        "run",
        "giggle"
      ],
      "character_emotions": [],
      "model_details": {
        "modelType": "RPM-3D",
        "modelLink": "https://models.readyplayer.me/63f8983f9dc8b8dcb3aff14a.glb",
        "modelPlaceholder": "https://models.readyplayer.me/63f8983f9dc8b8dcb3aff14a.png?pose=relaxed&background=0,0,60",
        "METAHUMAN": {
          "avatar_id": "4d923463-f1c8-4169-95f4-d6d19f6ad49a",
          "avatar_image": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/4d923463-f1c8-4169-95f4-d6d19f6ad49a_avatar_image.png?img_last_modified=1737042662?img_last_modified=1737113901",
          "avatar_image_square": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/4d923463-f1c8-4169-95f4-d6d19f6ad49a_avatar_image_square?img_last_modified=1737042662?img_last_modified=1737113901",
          "experience_id": "faa18c71-fc1d-4282-b616-f88a79cd9d62",
          "bg_image": ""
        }
      },
      "language_code": "en-US",
      "guard_rails": {
        "type1": "3"
      },
      "metadata_filter": {},
      "personalised_prompt_config": {
        "MODEL": "gpt-4o",
        "PROMPT": "",
        "VERBOSITY": 2,
        "TEMPERATURE": 0.07,
        "MODERATION_ENABLED": true,
        "USE_COMBINED_PROMPT": "true",
        "ALLOWED_MODERATION_FILTERS": [
          "violence",
          "violence/graphic"
        ],
        "USE_ACTION_OPTMIZED_PROMPT": true
      },
      "boosted_words": {
        "words": []
      },
      "guardrail_meta": {
        "limitResponseLevel": 4,
        "blockedWords": []
      },
      "start_narrative_section_id": null,
      "is_narrative_driven": false,
      "character_traits": {
        "catch_phrases": [],
        "speaking_style": "None",
        "personality_traits": {
          "openness": 2,
          "sensitivity": 2,
          "extraversion": 2,
          "agreeableness": 2,
          "meticulousness": 2
        }
      },
      "language_codes": [
        "en-US"
      ],
      "memory_settings": {
        "enabled": false
      },
      "last_interacted_with": "2025-02-20T07:20:13",
      "pronunciation_metadata": {
        "pronunciations": [
          {
            "word": "OCMO",
            "ipaPronunciation": "ɔkmow",
            "customPronunciation": "aukmo"
          }
        ]
      },
      "description": "",
      "speaking_style": {
        "description": "",
        "sample_dialogues": ""
      },
      "embodiment": null,
      "embodiment_data": {}
    },
    {
      "character_name": "Steven",
      "collection_name": "convai_default_collection",
      "user_id": "SOME_USER_ID",
      "character_id": "SOME_CHAR_ID",
      "model_type": "RPM-3D",
      "state_names": [],
      "state_links": [],
      "listing": "unlisted",
      "voice_type": "SOME_VOICE",
      "voice_pitch": 0.0,
      "blockchain": "NULL",
      "contract_address": "NULL",
      "mint_address": "NULL",
      "owner_address": "NULL",
      "timestamp": "2024-12-19T10:30:42",
      "character_actions": [],
      "character_emotions": [],
      "model_details": {
        "modelType": "RPM-3D",
        "modelLink": "https://models.readyplayer.me/673282ecef64719015ef8068.glb",
        "modelPlaceholder": "https://models.readyplayer.me/673282ecef64719015ef8068.png?pose=relaxed&background=0,0,60&size=512",
        "METAHUMAN": {
          "avatar_id": "c63e322d-c2cb-46f0-a466-9fd7c8073f9b",
          "avatar_image": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/c63e322d-c2cb-46f0-a466-9fd7c8073f9b_avatar_image.png?img_last_modified=1737042663",
          "avatar_image_square": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/c63e322d-c2cb-46f0-a466-9fd7c8073f9b_avatar_image_square?img_last_modified=1737042663",
          "experience_id": "7eb6e6eb-158d-44b1-8ecf-1657205f7765",
          "bg_image": ""
        }
      },
      "language_code": "en-US",
      "guard_rails": {
        "type1": "3"
      },
      "metadata_filter": {},
      "personalised_prompt_config": {
        "PROMPT": "",
        "MODEL": "gpt-4o-mini",
        "VERBOSITY": 2,
        "SPEAKER": "User",
        "MODERATION_ENABLED": true,
        "ALLOWED_MODERATION_FILTERS": [
          "violence",
          "violence/graphic"
        ],
        "USE_COMBINED_PROMPT": true,
        "TEMPERATURE": 0.7
      },
      "boosted_words": {
        "words": []
      },
      "guardrail_meta": {
        "limitResponseLevel": 4,
        "blockedWords": []
      },
      "start_narrative_section_id": "d20e62cc-bdf5-11ef-a5c2-42010a7be016",
      "is_narrative_driven": true,
      "character_traits": {
        "catch_phrases": [],
        "speaking_style": "None",
        "personality_traits": {
          "openness": 2,
          "sensitivity": 2,
          "extraversion": 2,
          "agreeableness": 2,
          "meticulousness": 2
        }
      },
      "language_codes": [
        "en-US"
      ],
      "memory_settings": {
        "enabled": true
      },
      "last_interacted_with": "2025-02-12T08:23:05",
      "pronunciation_metadata": {
        "pronunciations": []
      },
      "description": "",
      "speaking_style": {
        "description": "",
        "sample_dialogues": ""
      },
      "embodiment": null,
      "embodiment_data": {
        "looks_description": "",
        "clothes_description": ""
          }
        }, .... 
    ]
    }

No CONVAI-API-KEY provided by the user in the Request.

Invalid CONVAI-API-KEY provided by the user in the Request.

Server Side Failure. Please reach out to support.

Response Field Descriptions

  • character_name: Name of the character.

  • user_id: User ID of the user / character owner.

  • character_id: Unique ID of the character.

  • voice_type: Voice set for the character.

  • model_type: Model (Avatar) used by the character.

  • timestamp: Timestamp when the character was created.

  • character_actions: Set of actions described by the user for the character.

  • character_emotions: Set of emotions described by the user for the character.

  • personalised_prompt_config: Information regarding the model and prompt used by the character at the backend.

  • language_codes: List of languages supported by the character.

  • pronunciation_metadata: Information related to the custom pronunciations set for the character.

Sample Code Snippet

import requests

# URL of the API endpoint
url = 'https://api.convai.com/character/list'

# creating the header
headers = {
     'CONVAI-API-KEY': '<your api key>',
}

# Make the request
response = requests.post(url, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    # Print the response content
    print(response.json())
else:
    print(f"Failed to retrieve data. Status code: {response.status_code}")

https://api.convai.com/character/list