Create Custom Role Based on Templates

Last Updated on : 2026-02-26 09:15:25download

Based on the device ID, create a custom role for the AI agent on top of templates.

API address

POST: /v1.0/cloud/agent/ai/chat/b/devices/{device_id}/custom-roles/from-template

Request parameter

Parameter name	Type	IN	Required	Description
device_id	String	path	true	The ID of the specified device.

Description of body

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

Return parameter

Parameter name	Type	Description
result	boolean	Indicates whether the operation is successful.

Request example

POST: /v1.0/cloud/agent/ai/chat/b/devices/{device_id}/custom-roles/from-template

{
  "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": "zh",
  "use_llm_id": "8*",
  "use_timbre_id": "6*",
  "speed": "30",
  "need_bind": true
}

Return example

{
    "tid": "6fa034fc1a6d11f0a8212220de940dcb",
    "result": true,
    "t": 1744771778112,
    "success": true
}

Error code

For more information, see error code.