AI Agent Chat Services

API list

Action	Description
aiAgent.listChatDeviceHistoryPage	Get chat history
aiAgent.delChatDeviceChatHistory	Delete a role’s chat history
aiAgent.getChatDeviceMemorySwitch	Query memory enabling status
aiAgent.delChatDeviceMemory	Delete role memory
aiAgent.listChatDeviceMemories	Query memory list
aiAgent.updateChatDeviceMemory	Update role memory
aiAgent.listChatDeviceSummary	Query chat summary
aiAgent.updateChatDeviceSummary	Update chat summary
aiAgent.delDeviceChatContext	Clear role context
aiAgent.addChatDeviceCustomRole	Create custom role
aiAgent.listChatDeviceCustomRolePage	Query custom roles on pages
aiAgent.getChatDeviceCustomRoleDetail	Query custom role details
aiAgent.updateChatDeviceCustomRole	Modify custom role
aiAgent.delChatDeviceCustomRole	Delete custom role
aiAgent.addChatCustomRoleFromTemplate	Create template-based custom role
aiAgent.listChatDeviceRoleTemplates	Query role templates
aiAgent.getChatDeviceRoleTemplateDetail	Query role template details
aiAgent.bindChatDeviceAgentRole	Bind role
aiAgent.getChatDeviceAgentBindRole	Query role bound with agent
aiAgent.initChatDeviceAgentBindRole	Initialize binding relationship
aiAgent.listChatDeviceAvatar	Query avatars
aiAgent.listChatDeviceLanguage	Query languages
aiAgent.listChatDeviceLargeModel	Query large language models
aiAgent.getChatDeviceWakeUpWords	Get wake words
aiAgent.listChatDeviceAgentVariable	Query variables
aiAgent.updateChatDeviceAgentVariable	Update variables
aiAgent.listChatDeviceTimbreMarket	Get voice tones

Agent chat services

Get chat history

API description

Get the chat history of the specified device and return it in descending order by time.

API endpoint

action: aiAgent.listChatDeviceHistoryPage

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes
gmt_end	Long	The timestamp when the chat message ends. Chat messages earlier than this time point will be returned.	Yes
page_size	Integer	The number of items returned per page. Maximum value: 20.	Yes

Sample request

{
  "device_id": "6c50600a0e15d1fb78h***",
  "bind_role_type": 1,
  "role_id": "94300***",
  "gmt_end": 1753079987512,
  "page_size": 20
}

Response parameters

Parameter name	Type	Description
result	List	The list of chat history.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
gmt_create	Long	The timestamp when the chat is created.
answer	List	The list of answers.
question	List	The list of questions.
request_id	String	The ID of the chat history.

Description of answer/question objects

Parameter name	Type	Description
context	String	The message content.
type	String	The message type.

Sample response

{
  "result": [
    {
      "gmt_create": 1753344939913,
      "answer": [
        {
          "context": "You told me *** before",
          "type": "text"
        }
      ],
      "question": [{ "context": "My***", "type": "text" }],
      "request_id": "ccbda733-e3d2-4ee3-bb19-d201-***"
    }
  ],
  "success": true,
  "t": 1753707608368
}

Delete a role’s chat history

API description

Delete the chat history of the specified device and role.

API endpoint

action: aiAgent.delChatDeviceChatHistory

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes
clear_all_history	Boolean	Specifies whether to clear all history.	Yes
request_ids	String	The list of up to 20 request IDs, separated by commas (,).	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***",
  "clear_all_history": false,
  "request_ids": "0ed72c5a-11e4-47f3-a08f-b1d4-42767***,c487de49-d08e-4fb5-a0f0-e181-***"
}

Response parameters

Parameter name	Type	Description
result	Boolean	The returned result.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753090288674
}

Query memory enabling status

API description

Query whether the agent memory of the specified device is enabled.

API endpoint

action: aiAgent.getChatDeviceMemorySwitch

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
memory_open	Boolean	Indicates whether the memory feature is enabled.
summary_open	Boolean	Indicates whether the summary feature is enabled.

Sample response

{
  "memory_open": true,
  "summary_open": true
}

Agent role services

Delete role memory

API description

Delete the memory contents of the specified device and role.

API endpoint

action: aiAgent.delChatDeviceMemory

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes
clear_all_memory	Boolean	Specifies whether to clear all memories.	Yes
memory_keys	String	The list of up to 20 memory keys, separated by commas (,). This value is required when clear_all_memory is false.	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***",
  "clear_all_memory": false,
  "memory_keys": "sys.memoryInterests,sys.memoryBirthday"
}

Response parameters

Parameter name	Type	Description
result	Boolean	The returned result.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753091337419
}

Query memory list

API description

Get the memory list of the specified device and role.

API endpoint

action: aiAgent.listChatDeviceMemories

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***"
}

Response parameters

Parameter name	Type	Description
memory_list	List	The list of memory information.
effective_scope_name	String	The scope name of the memory.
effective_scope	Integer	The ID of the memory scope.

Description of the memory_list object

Parameter name	Type	Description
memory_value	String	The memory content.
memory_key	String	The memory key.
memory_name	String	The memory name.
effective_scope_name	String	The scope name of the memory.
effective_scope	Integer	The effective scope of the memory.

Sample response

[
  {
    "memory_list": [
      {
        "memory_value": "Playing football, playing basketball, writing code, reading",
        "memory_key": "sys.memoryInterests",
        "memory_name": "Hobbies",
        "effective_scope_name": "Role's memory",
        "effective_scope": 3
      },
      {
        "memory_value": "100 years old",
        "memory_key": "sys.memoryAge",
        "memory_name": "Age",
        "effective_scope_name": "Role's memory",
        "effective_scope": 3
      },
      {
        "memory_value": "July 7",
        "memory_key": "sys.memoryBirthday",
        "memory_name": "Birthday",
        "effective_scope_name": "Role's memory",
        "effective_scope": 3
      },
      {
        "memory_value": "Tuyaya",
        "memory_key": "sys.memoryUserFullName",
        "memory_name": "Name",
        "effective_scope_name": "Role's memory",
        "effective_scope": 3
      }
    ],
    "effective_scope_name": "Role's memory",
    "effective_scope": 3
  }
]

Update role memory

API description

Update the memory contents of the specified device and role.

API endpoint

action: aiAgent.updateChatDeviceMemory

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes
clear_all_memory	Boolean	Specifies whether to clear all memories.	Yes
memory_map	Object	The key-value pair of the memory content.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***",
  "clear_all_memory": false,
  "memory_map": {
    "sys.memoryInterests": "Fishing, playing football, playing basketball, writing code, reading, writing, drawing",
    "sys.memoryBirthday": "July 7",
    "sys.memoryAge": "22"
  }
}

Response parameters

Parameter name	Type	Description
result	Boolean	The returned result.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753091337419
}

Query chat summary

API description

Get chat summary information of the specified device and role.

API endpoint

action: aiAgent.listChatDeviceSummary

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***"
}

Response parameters

Parameter name	Type	Description
result	List	The list of chat summary information.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": [
    "The user first introduces himself as ***",
    "The user also asked a lot of questions: asking about his age, hobbies, birthday; ***."  ],
  "success": true,
  "t": 1753189379795
}

Update chat summary

API description

Update chat summary information of the specified device and role.

API endpoint

action: aiAgent.updateChatDeviceSummary

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes
summary_items	List	The list of chat summary content.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***",
  "summary_items": [
    "User's hobbies include playing football, playing basketball, reading, and swimming***"
  ]
}

Response parameters

Parameter name	Type	Description
result	Boolean	The returned result.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753097137086
}

Clear role context

API description

Clear the chat context information of the specified device role. That is, when a new chat is initiated, the context will not contain the previous chat information.

API endpoint

action: aiAgent.delDeviceChatContext

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes
role_id	String	The ID of the specified role.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "bind_role_type": 1,
  "role_id": "94300***"
}

Response parameters

Parameter name	Type	Description
result	Boolean	The returned result.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753091337419
}

Create custom role

API description

Create a custom role for the specified device.

API endpoint

action: aiAgent.addChatDeviceCustomRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
role_name	String	The name of the specified role.	Yes
role_desc	String	The description of the specified role.	No
role_introduce	String	The introduction to the specified role.	Yes
role_img_url	String	The URL of the specified role image.	Yes
use_lang_code	String	The code of the specified language.	Yes
use_timbre_id	String	The ID of the specified voice tone.	Yes
use_llm_id	String	The ID of the specified large language model.	Yes
speed	String	The speech speed, determined by the voice tone. It can be left unspecified.	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "role_name": "Alice***",
  "role_desc": "You are an astronomer",
  "role_introduce": "You are an astronomer with a wealth of knowledge. You are good at inspiring children's curiosity and interest in space, and you patiently answer their questions about space. You are humorous and witty, making you popular with children.",
  "role_img_url": "https://images.tuyacn.com/***/icon/2.png",
  "use_lang_code": "en",
  "use_timbre_id": "6*",
  "use_llm_id": "8*",
  "speed": "50"
}

Response parameters

Parameter name	Type	Description
result	String	The ID of the specified role.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": "163000112",
  "success": true,
  "t": 1753164320995
}

Query custom roles on pages

API description

Query the list of custom roles for the specified device on pages.

API endpoint

action: aiAgent.listChatDeviceCustomRolePage

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
page_no	Integer	The page number.	Yes
page_size	Integer	The number of items returned per page. Maximum value: 20.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "page_no": 1,
  "page_size": 10
}

Response parameters

Parameter name	Type	Description
result	Object	The result of the query.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
total	Integer	The total number of entries to be returned.
list	List	The list of roles.

Description of the list object

Parameter name	Type	Description
use_timbre_id	String	The ID of the specified voice tone.
role_introduce	String	The introduction to the specified role.
last_text_answer	String	The last text answer.
use_llm_name	String	The name of the specified large language model (LLM).
role_name	String	The name of the specified role.
use_lang_code	String	The code of the specified language.
role_id	String	The ID of the specified role.
role_desc	String	The description of the specified role.
template_id	String	The ID of the specified template.
in_bind	Boolean	Indicates whether a role has been bound.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.

Sample response

{
  "result": {
    "total": 2,
    "list": [
      {
        "use_timbre_id": "clone_45701***",
        "role_introduce": "A lively ***",
        "last_text_answer": "***",
        "use_llm_name": "1.5 Pro ***",
        "role_name": "Test 1***",
        "use_lang_code": "en",
        "role_id": "165600***",
        "role_desc": "The role description",
        "template_id": "94300***",
        "in_bind": true,
        "role_img_url": "https://images.tuyacn.com/smart/***/1748412117d6db500f***.jpeg",
        "use_lang_name": "English",
        "use_timbre_name": "My Voice Tone"
      }
    ]
  },
  "success": true,
  "t": 1753693705434
}

Query custom role details

API description

Get detailed information about a custom role for the specified device.

API endpoint

action: aiAgent.getChatDeviceCustomRoleDetail

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
role_id	String	The ID of the specified role.	Yes

Sample request

{
  "device_id": "6c50600a0e15d1fb78h***",
  "role_id": "165600***"
}

Response parameters

Parameter name	Type	Description
result	Object	The details of the specified role.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
use_llm_id	String	The ID of the specified large language model.
use_timbre_id	String	The ID of the specified voice tone.
role_introduce	String	The introduction to the specified role.
use_timbre_tags	List	The tags of the voice tones.
speed	String	The speech speed.
llm_support_func_tag_list	List	The list of functional tags supported by LLM. ["functionCall", "text", "audio"]
use_llm_name	String	The name of the specified large language model (LLM).
role_name	String	The name of the specified role.
use_lang_code	String	The code of the specified language.
role_id	String	The ID of the specified role.
role_desc	String	The remarks on the role.
template_id	String	The ID of the specified template.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.

Sample response

{
  "result": {
    "use_llm_id": "8*",
    "use_timbre_id": "clone_45701***",
    "role_introduce": "Introduction ***",
    "use_timbre_tags": ["English"],
    "speed": "50.0",
    "llm_support_func_tag_list": ["functionCall", "text", "audio"],
    "use_llm_name": "1.5 Pro ***",
    "role_name": "Test***",
    "use_lang_code": "en",
    "role_id": "165600***",
    "role_desc": "The role description",
    "template_id": "94300***",
    "role_img_url": "https://images.tuyacn.com/smart/***/1748412117d6db500f***.jpeg",
    "use_lang_name": "English",
    "use_timbre_name": "My Voice Tone"
  },
  "success": true,
  "t": 1753694295702
}

Modify custom role

API description

Modify the information about a custom role for the specified device.

API endpoint

action: aiAgent.updateChatDeviceCustomRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
role_id	String	The ID of the specified role.	Yes
role_name	String	The name of the specified role.	No
role_desc	String	The description of the specified role.	No
role_introduce	String	The introduction to the specified role.	No
role_img_url	String	The URL of the specified role image.	No
use_lang_code	String	The code of the specified language.	No
use_timbre_id	String	The ID of the specified voice tone.	No
use_llm_id	String	The ID of the specified large language model.	No
speed	String	The code of the specified language.	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "role_id": "163000***",
  "role_name": "Test***",
  "role_desc": "The role description***",
  "role_introduce": "You are a student tutor***",
  "role_img_url": "https://images.tuyacn.com/***/icon/2***.png",
  "use_lang_code": "en",
  "use_timbre_id": "6*",  
  "use_llm_id": "8*",
  "speed": "30"
}

Response parameters

Parameter name	Type	Description
result	Boolean	Indicates whether the operation is successful.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753168703906
}

Delete custom role

API description

Delete a custom role for the specified device.

API endpoint

action: aiAgent.delChatDeviceCustomRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
role_id	String	The ID of the specified role.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "role_id": "162600***"
}

Response parameters

Parameter name	Type	Description
result	Boolean	Indicates whether the operation is successful.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753169664947
}

Create template-based custom role

API description

Create a custom role based on a template.

API endpoint

action: aiAgent.addChatCustomRoleFromTemplate

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
template_id	String	The ID of the specified template.	Yes
role_name	String	The name of the specified role.	Yes
role_desc	String	The description of the specified role.	No
role_introduce	String	The introduction to the specified role.	Yes
role_img_url	String	The URL of the specified role image.	Yes
use_lang_code	String	The code of the specified language.	Yes
use_llm_id	String	The ID of the specified large language model.	Yes
use_timbre_id	String	The ID of the specified voice tone.	Yes
speed	String	The speech speed.	No
need_bind	Boolean	Indicates whether to directly bind the created role.	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "template_id": "94300***",
  "role_name": "*** created from template",
  "role_desc": "The role description***",
  "role_introduce": "You are an astronomer with a wealth of knowledge. You are good at inspiring children's curiosity and interest in space.***",  "role_img_url": "https://images.tuyacn.com/***/icon/2***.png",
  "use_lang_code": "en",
  "use_llm_id": "8*",
  "use_timbre_id": "6*",
  "speed": "30",
  "need_bind": true
}

Response parameters

Parameter name	Type	Description
result	String	The ID of the newly created role.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": "164600***",
  "success": true,
  "t": 1753252126233
}

Query role templates

API description

Get a list of agent role templates for the device.

API endpoint

action: aiAgent.listChatDeviceRoleTemplates

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	List	The list of role templates.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
role_name	String	The name of the specified role.
use_llm_id	String	The ID of the specified large language model.
bind_status	Boolean	The binding status. Valid values: true: Already bound. false: Not bound.
last_text_answer	String	The last text answer.
use_lang_code	String	The code of the specified language.
use_timbre_id	String	The ID of the specified voice tone.
template_id	String	The ID of the specified template.
role_introduce	String	The introduction to the specified role.
role_desc	String	The description of the specified role.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.
use_llm_name	String	The name of the specified large language model (LLM).

Sample response

{
  "result": [
    {
      "role_name": "Template***",
      "use_llm_id": "8*",
      "bind_status": false,
      "last_text_answer": "I am***",
      "use_lang_code": "en",
      "use_timbre_id": "5*",
      "template_id": "63700***",
      "role_introduce": "I am a***",
      "role_desc": "I am***"
      "role_img_url": "https://images.tuyacn.com/smart/***/17459093538f665740***.png",
      "use_lang_name": "English",
      "use_timbre_name": "Test***",
      "use_llm_name": "1.5 Pro ***"
    }
  ],
  "success": true,
  "t": 1753252060794
}

Query role template details

API description

Get the details of agent role templates for the device.

API endpoint

action: aiAgent.getChatDeviceRoleTemplateDetail

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
template_id	String	The ID of the specified template.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "template_id": "94300***"
}

Response parameters

Parameter name	Type	Description
result	Object	The details of the specified role template.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
use_llm_id	String	The ID of the specified large language model.
use_timbre_id	String	The ID of the specified voice tone.
role_introduce	String	The introduction to the specified role.
speed	String	The speech speed.
llm_support_func_tag_list	List	The list of functional tags.
use_llm_name	String	The name of the specified large language model (LLM).
role_name	String	The name of the specified role.
use_lang_code	String	The code of the specified language.
role_id	String	The ID of the specified role.
role_desc	String	The remarks on the role.
template_id	String	The ID of the specified template.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.

Sample response

{
  "result": {
    "use_llm_id": "8*",
    "use_timbre_id": "1*",
    "role_introduce": "Lovely***",
    "speed": "30.0",
    "llm_support_func_tag_list": ["functionCall", "text", "audio"],
    "use_llm_name": "1.5 Pro ***",
    "role_name": "Test***",
    "use_lang_code": "en",
    "role_id": "94300***",
    "role_desc": "The role description***",
    "template_id": "94300***",
    "role_img_url": "https://images.tuyacn.com/smart/***/17484121597b219879***.jpeg",
    "use_lang_name": "English",
    "use_timbre_name": "Young Zi Xin"
  },
  "success": true,
  "t": 1753253131796
}

Bind role

API description

Bind an agent role with the specified device.

API endpoint

action: aiAgent.bindChatDeviceAgentRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
role_id	String	The ID of the specified role.	Yes
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "role_id": "94300***",
  "bind_role_type": 1
}

Response parameters

Parameter name	Type	Description
result	Boolean	Indicates whether the operation is successful.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": true,
  "success": true,
  "t": 1753172097839
}

Query role bound with agent

API description

Get the agent role that is bound with the specified device.

API endpoint

action: aiAgent.getChatDeviceAgentBindRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	Object	The details of the specified role.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
use_llm_id	String	The ID of the specified large language model.
use_timbre_id	String	The ID of the specified voice tone.
role_introduce	String	The introduction to the specified role.
last_text_answer	String	The last text answer.
speed	String	The speech speed.
llm_support_func_tag_list	List	The list of functional tags.
use_llm_name	String	The name of the specified large language model (LLM).
role_name	String	The name of the specified role.
use_lang_code	String	The code of the specified language.
role_id	String	The ID of the specified role.
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.
role_desc	String	The remarks on the role.
template_id	String	The template ID associated with the role. This value is only available for custom roles created from templates.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.

• If bind_role_type is 0, it is a custom role. role_id is the custom role ID. If template_id has a value, it indicates the template role ID associated with this role.
• If bind_role_type is 1, it is a template role, and role_id is the template role ID.

Sample response

{
  "result": {
    "use_llm_id": "8*",
    "use_timbre_id": "clone_45701***",
    "role_introduce": "A teacher***",
    "last_text_answer": "Just introduced ***",
    "speed": "30.0",
    "llm_support_func_tag_list": ["functionCall", "text", "audio"],
    "use_llm_name": "1.5 Pro ***",
    "role_name": "Test***",
    "use_lang_code": "en",
    "role_id": "165600***",
    "bind_role_type": 0,
    "role_desc": "The role description***",
    "template_id": "94300***",
    "role_img_url": "https://images.tuyacn.com/smart/***/1748412117d6db500f***.jpeg",
    "use_lang_name": "English",
    "use_timbre_name": "My Voice Tone"
  },
  "success": true,
  "t": 1753696939321
}

Initialize binding relationship

API description

Initialize the binding relationship between the role and the agent based on the device ID. To ensure synchronization between Tuya Developer Platform roles and agent assignments, implement the following initialization call every time the agent functionality page is accessed.

API endpoint

action: aiAgent.initChatDeviceAgentBindRole

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	Object	The details of the specified role.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
use_llm_id	String	The ID of the specified large language model.
use_timbre_id	String	The ID of the specified voice tone.
role_introduce	String	The introduction to the specified role.
last_text_answer	String	The last text answer.
speed	String	The speech speed.
llm_support_func_tag_list	List	The list of functional tags.
use_llm_name	String	The name of the specified large language model (LLM).
role_name	String	The name of the specified role.
use_lang_code	String	The code of the specified language.
role_id	String	The ID of the specified role.
bind_role_type	Integer	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension.
role_desc	String	The remarks on the role.
template_id	String	The template ID associated with the role. This value is only available for custom roles created from templates.
role_img_url	String	The URL of the specified role image.
use_lang_name	String	The name of the specified language.
use_timbre_name	String	The name of the specified voice tone.

Sample response

{
  "result": {
    "use_llm_id": "8*",
    "use_timbre_id": "45701***",
    "role_introduce": "A***",
    "last_text_answer": "Sorry***",
    "speed": "50.0",
    "llm_support_func_tag_list": ["functionCall", "text", "audio"],
    "use_llm_name": "1.5 Pro ***",
    "role_name": "Test***",
    "use_lang_code": "en",
    "role_id": "165600***",
    "bind_role_type": 0,
    "role_desc": "The role description***",
    "template_id": "94300***",
    "role_img_url": "https://images.tuyacn.com/smart/***/1748412117d6db500f***.jpeg",
    "use_lang_name": "English",
    "use_timbre_name": "My Voice Tone"
  },
  "success": true,
  "t": 1753697514286
}

Agent settings

Query avatars

API description

Get the list of avatars supported by the specified device.

API endpoint

action: aiAgent.listChatDeviceAvatar

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	List	The URLs of the specified avatars.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
url	String	The URL of the specified avatar.

Sample response

{
  "result": [
    { "url": "https://images.tuyacn.com/***/icon/1***.png" },
    { "url": "https://images.tuyacn.com/***/icon/2***.png" },
    { "url": "https://images.tuyacn.com/***/icon/3***.png" },
    { "url": "https://images.tuyacn.com/***/icon/4***.png" },
    { "url": "https://images.tuyacn.com/***/icon/5***.png" },
    { "url": "https://images.tuyacn.com/***/icon/6***.png" }
  ],
  "success": true,
  "t": 1753155603441
}

Query languages

API description

Get the list of languages supported by the specified device.

API endpoint

action: aiAgent.listChatDeviceLanguage

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	List	The list of languages.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
has_default	Boolean	Indicates whether it is the default language.
lang_name	String	The name of the specified language.
lang_code	String	The code of the specified language.

Sample response

{
  "result": [
    { "has_default": false, "lang_name": "Hunan dialect", "lang_code": "zh_hn" },
    { "has_default": false, "lang_name": "Minnan dialect", "lang_code": "zh_mn" },
    { "has_default": false, "lang_name": "English", "lang_code": "en" },
    { "has_default": true, "lang_name": "Chinese", "lang_code": "zh" }
  ],
  "success": true,
  "t": 1753162485939
}

Query large language models

API description

Query the list of large language models supported by the specified device.

API endpoint

action: aiAgent.listChatDeviceLargeModel

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	List	The list of models.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
llm_name	String	The name of the specified model.
llm_id	Integer	The ID of the specified model.

Sample response

{
  "result": [
    {
      "llm_name": "1.5 Pro ***",
      "llm_id": 85
    }
  ],
  "success": true,
  "t": 1753162676439
}

Get wake words

API description

Get the wake word for the specified device.

API endpoint

action: aiAgent.getChatDeviceWakeUpWords

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	String	The wake word.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Sample response

{
  "result": "Test***",
  "success": true,
  "t": 1753162892431
}

Agent variables

Query variables

API description

Query the list of agent variables for the specified device. Variables starting with custom. are custom variables (configured on the Tuya Developer Platform).

API endpoint

action: aiAgent.listChatDeviceAgentVariable

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***"
}

Response parameters

Parameter name	Type	Description
result	List	The list of variables.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
variable_key	String	The key of the specified variable.
variable_value	String	The value of the specified variable.

Sample response

{
  "result": [
    {
      "variable_key": "sys.memoryInterests",
      "variable_value": "Obsessed with the universe and the stars, studying all kinds of astronomical knowledge"
    },
    {
      "variable_key": "sys.roleSupplementDesc",
      "variable_value": ""
    },
    {
      "variable_key": "sys.roleIntroduce",
      "variable_value": "You are an astronomer"
    },
    {
      "variable_key": "sys.memoryAge",
      "variable_value": "99 years old"
    },
    {
      "variable_key": "sys.memoryBirthday",
      "variable_value": "July 7"
    },
    {
      "variable_key": "sys.memoryHistoryChatSummary",
      "variable_value": "User asked ***"
    },
    {
      "variable_key": "sys.roleName",
      "variable_value": "Test***"
    },
    {
      "variable_key": "sys.memoryUserFullName",
      "variable_value": ""
    },
    {
      "variable_key": "sys.roleRemark",
      "variable_value": "Astronomer"
    },
    {
      "variable_key": "custom.roleName",
      "variable_value": "Astronomer"
    },
    {
      "variable_key": "custom.familyName",
      "variable_value": "Test**"
    },
    {
      "variable_key": "custom.userName",
      "variable_value": "James"
    },
    {
      "variable_key": "custom.userId",
      "variable_value": "12345***"
    }
  ],
  "success": true,
  "t": 1753790540058
}

Update variables

API description

Update the list of agent variables for the specified device. Variables starting with custom. are custom variables (configured on the Tuya Developer Platform). Variables starting with custom. have three scopes: role, home account/environment, and individual user. There are two read-write attributes: read-only and read and write.

API endpoint

action: aiAgent.updateChatDeviceAgentVariable

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
variable_map	Map	The mapping relationship of variables. key: The variable name. value: The value to be updated.	Yes
role_id	String	The role ID. This value is required when the effective scope of the custom variable to be updated is Role. If this value is not passed, the currently bound role will be updated by default.	No
bind_role_type	String	The type of role to bind. Valid values: 0: Custom role. 1: Template-based role. 2: Single role. That is, no role is available, and data is in the agent dimension. This value is required when role_id is passed.	No

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "variable_map": {
    "custom.familyName": "testFamilyName"
  }
}

Response parameters

Parameter name	Type	Description
result	List	The list of updated variables.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
variable_key	String	The key of the specified variable.
variable_value	String	The value of the specified variable.

Sample response

{
  "result": [
    {
      "variable_key": "sys.memoryInterests",
      "variable_value": "Play basketball, play football, write code, read, swim"
    },
    {
      "variable_key": "sys.roleSupplementDesc",
      "variable_value": ""
    },
    {
      "variable_key": "sys.roleIntroduce",
      "variable_value": "A***"
    },
    {
      "variable_key": "sys.memoryAge",
      "variable_value": "200 years old"
    },
    {
      "variable_key": "sys.memoryBirthday",
      "variable_value": "July 7"
    },
    {
      "variable_key": "sys.memoryHistoryChatSummary",
      "variable_value": "User asked ***"
    },
    {
      "variable_key": "sys.roleName",
      "variable_value": "Test role name"
    },
    {
      "variable_key": "sys.memoryUserFullName",
      "variable_value": "Tuyaya"
    },
    {
      "variable_key": "sys.roleRemark",
      "variable_value": "James remarks"
    }
  ],
  "success": true,
  "t": 1753175763882
}

Voice tones

Get voice tones

API description

Get the list of voice tones.

API endpoint

action: aiAgent.listChatDeviceTimbreMarket

Request parameters

Parameter name	Type	Description	Required
device_id	String	The ID of the specified device.	Yes
lang	String	The language.	Yes
page_no	Integer	The page number.	Yes
page_size	Integer	The number of items returned per page. Maximum value: 20.	Yes

Sample request

{
  "device_id": "6c3585ebfe301b40a8u***",
  "lang": "en",
  "page_no": 1,
  "page_size": 20
}

Response parameters

Parameter name	Type	Description
result	Object	The returned list of voice tones.
success	Boolean	Indicates whether the operation is successful.
t	Long	The timestamp.

Description of the result object

Parameter name	Type	Description
total	Integer	The total number.
list	List	The details of voice tones.

Description of the list object

Parameter name	Type	Description
demoUrl	String	The URL of the sample voice tone.
voiceId	String	The ID of the specified voice tone.
voiceName	String	The name of the specified voice tone.
descTags	List	The list of description tags.
supportLangs	List	The list of supported languages.
speed	Integer	The speech speed.

Sample response

{
  "result": {
    "total": 1,
    "list": [
      {
        "demoUrl": "https://images.tuyacn.com/***/timbre/timbre_2_***.mp3",
        "voiceId": "2*",
        "voiceName": "Refreshed Sisi",
        "descTags": ["Female", "Youth", "Chinese", "English"],
        "supportLangs": ["zh", "en"],
        "speed": 30
      }
    ]
  },
  "success": true,
  "t": 1753164054222
}