Query Custom Roles

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

Based on the device ID, query the list of custom roles of the AI agent.

API address

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

Request parameter

Parameter name	Type	IN	Required	Description
device_id	String	path	true	The ID of the specified device.
page_no	Integer	query	true	The page number.
page_size	Integer	query	true	The number of items returned per page.

Return parameter

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.

Request example

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

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

Return example

{
    "result": {
        "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": "zh",
                "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": "Chinese",
                "use_timbre_name": "My Voice Tone"
            }
        ],
        "total": 2
    },
    "t": 1753693705434,
    "success": true
}

Error code

For more information, see error code.