Query Custom Role Details

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

Based on the device ID and role ID, query the details of the specified custom role for the AI agent.

API address

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

Request parameter

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

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

Request example

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

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

Return example

{
    "result": {
        "use_llm_id": "8*",
        "use_timbre_id": "clone_45701***",
        "role_introduce": "Introduction ***",
        "use_timbre_tags": [
            "Chinese"
        ],
        "speed": "50.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***",
        "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": 1753694295702,
    "success": true
}

Error code

For more information, see error code.