Create Agentic Avatar

POST/v1/agentic-avatars

Create an AI-powered avatar with brain/knowledge base integration.

What is an Agentic Avatar?

An agentic avatar is an AI-powered avatar that combines a visual avatar, voice, and knowledge base (brain) to create an intelligent conversational agent. These avatars can understand context, answer questions using your knowledge base, and interact naturally with users through voice or text.

Key Components:

Avatar: The visual appearance and video representation
Voice: The voice used for speech synthesis
Brain (Knowledge Base): The knowledge base that provides context and information
Settings: Personality, greeting, and language configuration

Request History

TIME	STATUS	USER AGENT
Make a request to see history.

0 Requests This Month

Request Body

The request body contains the agentic avatar configuration including the avatar, voice, brain (knowledge base), and behavioral settings. All fields are required to create a functional agentic avatar.

Field	Type	Description
name	string required	A descriptive name for the agentic avatar (e.g., `"Customer Support Agent"`). This name helps you identify and manage your agentic avatars.
avatar_id	string required	The unique identifier of the avatar to use. This must be a valid avatar ID from your account or a public avatar. Use the List All Avatars endpoint to find available avatars.
voice_id	string required	The unique identifier of the voice to use for speech synthesis. This must be a valid voice ID from your account or a public voice. Use the List All Voices endpoint to find available voices.
brain_id	string required	The unique identifier of the knowledge base (brain) to use. The brain provides the avatar with context and information to answer questions intelligently. You must have created a brain/knowledge base before using it here.
settings	object required	Configuration object that controls the avatar's behavior, personality, greeting message, and supported languages.

Settings Object

The settings object allows you to customize the agentic avatar's personality, greeting, and language capabilities. All fields within the settings object are required.

Field	Type	Description
greeting	string required	The initial greeting message the avatar will use when starting a conversation (e.g., `"Hello! How can I assist you today?"`). This sets the tone for the interaction.
personality	string required	A description of the avatar's personality and communication style (e.g., `"professional and helpful"`, `"friendly and casual"`). This influences how the avatar responds to users.
languages	array required	Array of language codes that the avatar can understand and respond in (e.g., `["en", "es", "fr"]` for English, Spanish, and French). Use ISO 639-1 language codes.

Request Example

shell

curl -X POST https://api.konpro.ai/v1/agentic-avatars \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "avatar_id": "avatar-3655",
    "voice_id": "fa4954b5-dd32-47b7-8e11-b552ca35c13f",
    "brain_id": "002a9215-dc48-4537-91cb-93ac182e4e93",
    "settings": {
      "greeting": "Hello! How can I assist you today?",
      "personality": "professional and helpful",
      "languages": ["en", "es", "fr"]
    }
  }'

Response

Field	Type	Description
id	string	Unique identifier of the created agentic avatar. Use this ID to reference the avatar in other API calls.
name	string	The name you provided for the agentic avatar
avatar_id	string	The avatar ID used in this agentic avatar
voice_id	string	The voice ID used in this agentic avatar
brain_id	string	The knowledge base (brain) ID used in this agentic avatar
status	string	Current status of the agentic avatar (e.g., `active`). An active avatar is ready to use in widget sessions.
created_at	string	ISO 8601 timestamp of when the agentic avatar was created

Sample Successful Response

json

{
  "id": "72e527cd-9d40-47a7-8c9d-753f945a7574",
  "name": "Customer Support Agent",
  "avatar_id": "avatar-3655",
  "voice_id": "fa4954b5-dd32-47b7-8e11-b552ca35c13f",
  "brain_id": "002a9215-dc48-4537-91cb-93ac182e4e93",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z"
}

Notes

This endpoint requires authentication using the x-api-key header.
All fields in the request body are required. Make sure you have valid IDs for avatar_id, voice_id, and brain_id.
The avatar_id must be a valid avatar from your account or a public avatar. Use the List All Avatars endpoint to find available avatars.
The voice_id must be a valid voice from your account or a public voice. Use the List All Voices endpoint to find available voices.
The brain_id must be a valid knowledge base (brain) that you have created. You need to create a brain/knowledge base before you can use it in an agentic avatar.
The languages array should contain ISO 639-1 language codes (e.g., "en" for English, "es" for Spanish).
Once created, you can use the agentic avatar ID in widget sessions to create interactive AI-powered widgets.
For error descriptions, see Error Responses.

Delete Widget Session Get All Agentic Avatars