Create Custom Role

Last Updated on : 2026-02-26 09:16:43download

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

API address

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

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
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, determined by the voice tone. It can be left unspecified.

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-role

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

Return example

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

Error code

For more information, see error code.