Query Bound Roles

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

Based on the device ID, query the roles that the agent has been bound with.

API address

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

Request parameter

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

Return parameter

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

Description of result

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 (There is no role, and data is at the agent level)
role_desc	String	The description of the specified role.
template_id	String	The template ID associated with the role. This value might be available only 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.
workflow	String	The type of workflow.

Request example

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

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

Return example

{
    "result": {
        "use_llm_id": "8*",
        "workflow": "asr-llm-tts",
        "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": "zh",
        "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": "Chinese",
        "use_timbre_name": "My Voice Tone"
    },
    "t": 1753696939321,
    "success": true
}

Error code

For more information, see error code.