Identity recognition

Updated at:

This topic describes the identity recognition feature. Identity recognition identifies the speakers in a conversation. You can specify the conversation scenario to quickly identify the roles of the speakers. This information can help you with product iteration, marketing strategy development, and other tasks.

Request parameters

Parameter

Type

Required

Description

IdentityRecognitionEnabled

boolean

No

The switch for the identity recognition feature. The default value is false.

IdentityRecognition

object

No

The identity recognition parameter object.

IdentityRecognition.SceneIntroduction

string

No

A description of the scenario for identity recognition.

IdentityRecognition.IdentityContents

list[]

Yes

A list of content for identity recognition. The list includes identity names and descriptions.

IdentityRecognition.IdentityContents[i].Name

string

Yes

The identity name.

IdentityRecognition.IdentityContents[i].Description

string

Yes

The identity description.

For descriptions of other request parameters, see the document for your scenario:

Note
  • Before using the identity recognition feature, enable speaker diarization. Otherwise, the conversation is assumed to have only one speaker.

  • The maximum length of IdentityRecognition.IdentityContents is 5.

Example settings

You can specify the conversation scenario to improve recognition accuracy. Examples include online education phone sales, offline car dealership sales, and real estate agent sales.

Use the "Name" field to specify the identity and the "Description" field to provide a description of that identity. The description must be clear and direct. Do not add regular expressions or complex list structures, because this can cause conflicts with the prompts included in the service.

{
    "Input":{
        ...
    },
    "Parameters": {
        "IdentityRecognitionEnabled": true,
        "IdentityRecognition": {
            "SceneIntroduction": "Offline car dealership sales scenario",
            "IdentityContents": [
                {
                    "Name": "Sales",
                    "Description": "Introduces different vehicle configurations, performance, technology, comfort, and convenience features"
                },
                {
                    "Name": "Customer",
                    "Description": "Asks questions about the vehicle and shares user experience"
                }
            ]
        }
    }
}

Recommendations:

  • For the "Name" field, avoid using similar identities, such as "Sales" and "Shopping Guide", in the same identity recognition task.

  • Descriptions should be distinct. Do not use repetitive or similar descriptions for different identities.

Code examples

#!/usr/bin/env python
# coding=utf-8

import os
import json
import datetime
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest
from aliyunsdkcore.auth.credentials import AccessKeyCredential


def create_common_request(domain, version, protocolType, method, uri):
    request = CommonRequest()
    request.set_accept_format('json')
    request.set_domain(domain)
    request.set_version(version)
    request.set_protocol_type(protocolType)
    request.set_method(method)
    request.set_uri_pattern(uri)
    request.add_header('Content-Type', 'application/json')
    return request


def init_parameters():
    root = dict()
    root['AppKey'] = 'Enter the AppKey that you created in the Tingwu console'

    # Basic request parameters
    input = dict()
    input['SourceLanguage'] = 'cn'
    input['TaskKey'] = 'task' + datetime.datetime.now().strftime('%Y%m%d%H%M%S')
    input['FileUrl'] = 'Enter the URL of the audio file to test'
    root['Input'] = input

    # AI-related parameters. Set them as needed.
    parameters = dict()
    # Identity recognition
    parameters['IdentityRecognitionEnabled'] = True
    identity_recognition = {
        "SceneIntroduction": "Offline car dealership sales scenario",
        "IdentityContents": [
            {
                "Name": "Sales",
                "Description": "Introduces different vehicle configurations, performance, technology, comfort, and convenience features"
            },
            {
                "Name": "Customer",
                "Description": "Asks questions about the vehicle and shares user experience"
            }
        ]
    }
    parameters['IdentityRecognition'] = identity_recognition
    root['Parameters'] = parameters
    return root


body = init_parameters()
print(body)

# TODO: Set your AccessKeyId and AccessKeySecret using environment variables.
credentials = AccessKeyCredential(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'])
client = AcsClient(region_id='cn-beijing', credential=credentials)

request = create_common_request('tingwu.cn-beijing.aliyuncs.com', '2023-09-30', 'https', 'PUT', '/openapi/tingwu/v2/tasks')
request.add_query_param('type', 'offline')

request.set_content(json.dumps(body).encode('utf-8'))
response = client.do_action_with_exception(request)
print("response: \n" + json.dumps(json.loads(response), indent=4, ensure_ascii=False))
package com.alibaba.tingwu.client.demo.aitest;

import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;
import org.junit.Test;

/**
 * @author tingwu2023
 */
public class IdentityRecognitionTest {

    @Test
    public void testIdentityRecognition() throws ClientException {
        CommonRequest request = createCommonRequest("tingwu.cn-beijing.aliyuncs.com", "2023-09-30", ProtocolType.HTTPS, MethodType.PUT, "/openapi/tingwu/v2/tasks");
        request.putQueryParameter("type", "offline");

        JSONObject root = new JSONObject();
        root.put("AppKey", "Enter the AppKey that you created in the Tingwu console");

        JSONObject input = new JSONObject();
        input.fluentPut("FileUrl", "Enter the URL of the audio file to test")
                .fluentPut("SourceLanguage", "cn")
                .fluentPut("TaskKey", "task" + System.currentTimeMillis());
        root.put("Input", input);

        JSONObject parameters = new JSONObject();
        parameters.put("IdentityRecognitionEnabled", true);
        JSONObject identityRecognition = new JSONObject();
        identityRecognition.fluentPut("SceneIntroduction", "Offline car dealership sales scenario")
            .fluentPut("IdentityContents", new JSONArray()
            .fluentAdd(new JSONObject().fluentPut("Name", "Sales").fluentPut("Description", "Introduces different vehicle configurations, performance, technology, comfort, and convenience features"))
            .fluentAdd(new JSONObject().fluentPut("Name", "Customer").fluentPut("Description", "Asks questions about the vehicle and shares user experience"))
        );
        parameters.put("IdentityRecognition", identityRecognition);
        root.put("Parameters", parameters);
        System.out.println(root.toJSONString());
        request.setHttpContent(root.toJSONString().getBytes(), "utf-8", FormatType.JSON);

        // TODO: Set your AccessKeyId and AccessKeySecret using environment variables.
        DefaultProfile profile = DefaultProfile.getProfile("cn-beijing", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        CommonResponse response = client.getCommonResponse(request);
        System.out.println(response.getData());
    }

    public static CommonRequest createCommonRequest(String domain, String version, ProtocolType protocolType, MethodType method, String uri) {
        // Create an API request and set parameters.
        CommonRequest request = new CommonRequest();
        request.setSysDomain(domain);
        request.setSysVersion(version);
        request.setSysProtocol(protocolType);
        request.setSysMethod(method);
        request.setSysUriPattern(uri);
        request.setHttpContentType(FormatType.JSON);
        return request;
    }
}

Example output

{
    "Message": "success", 
    "Code": "0", 
    "Data": {
        "Result": {
            "Transcription": "https://speech-swap-hangzhou.oss-cn-hangzhou.aliyuncs.com/tingwu/output/1503864348104017/05c45066fc6d496dae9b583426fdaae8/05c45066fc6d496dae9b583426fdaae8_Transcription_20231028230430.json", 
            "IdentityRecognition":"https://speech-swap-hangzhou.oss-cn-hangzhou.aliyuncs.com/tingwu/output/1662764528407695/10cac845e6464a2d9aac6017bc8c8563/10cac845e6464a2d9aac6017bc8c8563_IdentityRecognition_20250331141840.json"
        }, 
        "TaskId": "10cac845e6464a2d9aac601*********", 
        "TaskStatus": "COMPLETED"
    }, 
    "RequestId": "B95BC4D9-AB53-1FBA-97B9-C8A6********"
}

The value of the IdentityRecognition field is the HTTPS URL to download the identity recognition results.

Protocol parsing

The content at the identity recognition URL is a JSON-formatted message. The following code shows an example.

{
    "TaskId": "10cac845e6464a2d9aac601*********",
    "IdentityRecognition": {
        "IdentityResults":[
          {"SpeakerId":"1","Identity":"Sales"},
          {"SpeakerId":"2","Identity":"Customer"}
        ]
    }
}

The fields are described as follows.

Parameter

Type

Description

TaskId

string

The TaskId generated when the task was created.

IdentityRecognition

Object

The identity recognition result object. It contains a list of identity recognition results.

IdentityRecognition.IdentityResults

List

A list of identity recognition results.

IdentityRecognition.IdentityResults[i].SpeakerId

string

The speaker ID. This corresponds to the speakerId from the speaker diarization result in the speech-to-text transcription.

IdentityRecognition.IdentityResults[i].Identity

string

The name of the identity recognition result. This corresponds to the IdentityRecognition.IdentityContents[i].Name input parameter.