### Voiceprint API Authentication URL Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Example of a fully constructed URL with authorization parameters for the Voiceprint Recognition API.

```http
https://api.xf-yun.com/v1/private/s782b4996?authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iMWp3UWJJQUttUUU3SndJSDBJRHhpQzFwZWpybE4rVnBIWERXT0ZWeTVOTT0i&host=api.xf-yun.com&date=Fri%2C+23+Apr+2021+02%3A35%3A47+GMT
```

--------------------------------

### Voice Recognition Demo Links

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

Links to demonstration projects for voice recognition using the Xfyun platform. These examples are provided in Java and Python to help developers integrate the service.

```text
声纹识别demo java语言 (opens new window)
声纹识别demo python语言 (opens new window)
```

--------------------------------

### Authentication Error Response Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

An example of an HTTP 403 Forbidden response returned when a clock skew or authentication issue occurs during the request.

```http
HTTP/1.1 403 Forbidden
Date: Mon, 30 Nov 2020 02:34:33 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}
```

--------------------------------

### 1:N Feature Comparison Request Example (JSON)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

This JSON object illustrates the request payload for a 1:N feature comparison. It contains header information, service-specific parameters for the 'searchFea' function, and the payload with base64 encoded audio data.

```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "searchFea",
      "groupId": "iFLYTEK_examples_groupId",
      "topK": 2,
      "searchFeaRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1RTU0UAAAAPAAA..."
    }
  }
}
```

--------------------------------

### Query Feature List Response Example (JSON)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This JSON object shows the response after querying for a list of voice features. It contains a header indicating the success of the session and a payload with the 'queryFeatureListRes'. The 'text' field within the payload is Base64 encoded and decodes to a JSON array containing feature information.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000eebfc@hu178fd7c11f20212882"
  },
  "payload": {
    "queryFeatureListRes": {
      "text": "W3siZmVhdHVy..."
    }
  }
}
```

```json
[
  {
    "featureInfo": "iFLYTEK_examples_featureInfo",
    "featureId": "iFLYTEK_examples_featureId"
  }
]
```

--------------------------------

### Update Audio Feature Response Example (JSON)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This JSON object represents the response received after updating audio features. It includes a header for status and a payload containing the update result. The 'text' field in the payload is Base64 encoded and contains a success message upon successful update.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000d96a6@hu17a5ad256e70212882"
  },
  "payload": {
    "updateFeatureRes": {
      "status": "3",
      "text": "eyJtc2ciOiJzdWNjZXNzIn0="
    }
  }
}
```

```json
{
  "msg": "success"
}
```

--------------------------------

### HTTP 403 Forbidden Response Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This snippet shows an example of an HTTP 403 Forbidden response, typically returned when there are issues with time synchronization or signature verification. It includes headers and a JSON body indicating the error.

```http
HTTP/1.1 403 Forbidden
Date: Mon, 30 Nov 2020 02:34:33 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}

```

--------------------------------

### 1:1 Feature Comparison Response Example (JSON)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

This JSON object represents the response structure for a 1:1 feature comparison request. It includes a header for status and a payload containing the base64 encoded comparison results. The decoded 'text' field provides the similarity score and feature details.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e1142@hu178fd98935d0212882"
  },
  "payload": {
    "searchScoreFeaRes": {
      "text": "eyJhZ2UiOiJja..."
    }
  }
}
```

```json
{
  "score": 1,
  "featureInfo": "iFLYTEK_examples_featureInfo",
  "featureId": "iFLYTEK_examples_featureId"
}
```

--------------------------------

### 1:N Feature Comparison Response Example (JSON)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

This JSON object shows the response structure for a 1:N feature comparison. The header indicates the status, and the payload contains base64 encoded results. The decoded 'text' field provides a list of scores, feature information, and feature IDs for potential matches.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e3672@hu178fdb6c69d0210882"
  },
  "payload": {
    "searchFeaRes": {
      "text": "eyJhZ2UiOiJ5b..."
    }
  }
}
```

```json
{
  "scoreList": [
    {
      "score": 1,
      "featureInfo": "iFLYTEK_examples_featureInfo1",
      "featureId": "iFLYTEK_examples_featureId1"
    },
    {
      "score": 0.85,
      "featureInfo": "iFLYTEK_examples_featureInfo",
      "featureId": "iFLYTEK_examples_featureId"
    }
  ]
}
```

--------------------------------

### Create Voiceprint Feature Library Response Body Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This JSON structure represents the response received after attempting to create a voiceprint feature library. It contains a header with status code and message, and a payload with the base64 encoded result of the createGroup operation.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e55f5@hu178fca72b160210882"
  },
  "payload": {
    "createGroupRes": {
      "text": "eyJncm91cEl..."
    }
  }
}

```

--------------------------------

### Create Voiceprint Feature Library Request Body Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This JSON payload is used in the HTTP request body to create a voiceprint feature library. It includes header parameters like app_id and status, and parameter details for the 'createGroup' function, specifying group ID, name, info, and desired response format.

```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "createGroup",
      "groupId": "iFLYTEK_examples_groupId",
      "groupName": "iFLYTEK_examples_groupName",
      "groupInfo": "iFLYTEK_examples_groupInfo",
      "createGroupRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  }
}

```

--------------------------------

### API Response Handling

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Example of a successful API response and the decoded text payload. The response text field is Base64 encoded and must be decoded to retrieve the operation result.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e75d9@hu178fdf66e290210882"
  },
  "payload": {
    "deleteFeatureRes": {
      "text": "eyJtc2ciOiJzdWNjZXNzIn0="
    }
  }
}
```

```json
{
  "msg": "success"
}
```

--------------------------------

### Decoded Response Text Example

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

The JSON structure obtained after Base64 decoding the 'text' field from the API response payload.

```json
{
  "groupName": "iFLYTEK_examples_groupName",
  "groupId": "iFLYTEK_examples_groupId",
  "groupInfo": "iFLYTEK_examples_groupInfo"
}
```

--------------------------------

### Perform 1:1 Feature Comparison Request

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Request structure for comparing a provided audio sample against a stored feature ID. Includes audio resource parameters and comparison configuration.

```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "searchScoreFea",
      "groupId": "iFLYTEK_examples_groupId",
      "dstFeatureId": "iFLYTEK_examples_featureId",
      "searchScoreFeaRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1RTU0UAA..."
    }
  }
}
```

--------------------------------

### Update Voice Feature Response

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Example response structure for updating a voice feature. The 'text' field contains a Base64 encoded JSON string indicating the success status of the operation.

```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000d96a6@hu17a5ad256e70212882"
  },
  "payload": {
    "updateFeatureRes": {
      "status": "3",
      "text": "eyJtc2ciOiJzdWNjZXNzIn0="
    }
  }
}
```

--------------------------------

### Feature Comparison (1:1)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

Performs a 1:1 comparison between two audio features.

```APIDOC
## POST /websites/xfyun_cn_doc_voiceservice_isv/searchScoreFea

### Description
Compares two audio features in a 1:1 manner to determine similarity.

### Method
POST

### Endpoint
/websites/xfyun_cn_doc_voiceservice_isv/searchScoreFea

### Parameters
#### Request Body
- **header** (object) - Required - Platform parameters.
  - **header.app_id** (string) - Required - Your application ID.
  - **header.status** (int) - Required - Request status (3 for one-time transmission).
- **parameter** (object) - Required - Service feature parameters.
  - **parameter.s782b4996** (object) - Required - Function parameters.
    - **parameter.s782b4996.func** (string) - Required - Specific capability (value: "searchScoreFea").
    - **parameter.s782b4996.groupId** (string) - Required - Group identifier for features (max 32 characters).
    - **parameter.s782b4996.dstFeatureId** (string) - Required - Identifier of the feature to compare against (0-32 characters).
    - **parameter.s782b4996.searchScoreFeaRes** (object) - Required - Desired response format.
      - **parameter.s782b4996.searchScoreFeaRes.encoding** (string) - Required - Encoding format (fixed: "utf8").
      - **parameter.s782b4996.searchScoreFeaRes.compress** (string) - Required - Compression format (fixed: "raw").
      - **parameter.s782b4996.searchScoreFeaRes.format** (string) - Required - Text format (fixed: "json").
- **payload** (object) - Required - Request data.
  - **payload.resource** (object) - Required - Audio related parameters.
    - **payload.resource.encoding** (string) - Required - Audio encoding (fixed: "lame").
    - **payload.resource.sample_rate** (int) - Required - Audio sample rate (16000).
    - **payload.resource.channels** (int) - Optional - Audio channels (1 for mono).
    - **payload.resource.bit_depth** (int) - Optional - Audio bit depth (16).
    - **payload.resource.status** (int) - Required - Audio data status (3 for one-time transmission).
    - **payload.resource.audio** (string) - Required - Base64 encoded audio data (1B to 4M).

### Request Example
```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "searchScoreFea",
      "groupId": "iFLYTEK_examples_groupId",
      "dstFeatureId": "iFLYTEK_examples_featureId",
      "searchScoreFeaRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1RTU0UAA..."
    }
  }
}
```

### Response
#### Success Response (200)
- **header** (object) - Platform parameters.
  - **header.code** (int) - Session call status (0 for success).
  - **header.message** (string) - Description of the status.
  - **header.sid** (string) - Session unique identifier.
- **payload** (object) - Data segment.
  - **payload.searchScoreFeaRes** (object) - Response data block.
    - **payload.searchScoreFeaRes.text** (string) - Base64 encoded response data.

**Decoded payload.searchScoreFeaRes.text:**
- **score** (float) - The similarity score between the features.

#### Response Example
```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000eebfc@hu178fd7c11f20212882"
  },
  "payload": {
    "searchScoreFeaRes": {
      "text": "eyJzY29yZSI6IDAuOTUgfQ=="
    }
  }
}
```
```

--------------------------------

### Feature Matching (1:1)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Performs a 1:1 comparison between a given audio and a stored feature.

```APIDOC
## POST /websites/xfyun_cn_doc_voiceservice_isv/searchScoreFea

### Description
Performs a 1:1 feature matching between an audio resource and a specified feature ID.

### Method
POST

### Endpoint
/websites/xfyun_cn_doc_voiceservice_isv/searchScoreFea

### Parameters
#### Request Body
- **header** (object) - Required - Platform parameters.
  - **header.app_id** (string) - Required - App ID obtained from the platform.
  - **header.status** (int) - Required - Request status, typically 3 (one-time transfer).
- **parameter** (object) - Required - Service feature parameters.
  - **parameter.s782b4996** (object) - Required - Function parameters.
    - **parameter.s782b4996.func** (string) - Required - Specifies the voiceprint capability, set to "searchScoreFea".
    - **parameter.s782b4996.groupId** (string) - Required - Identifier for the group containing the feature to compare. Supports alphanumeric characters and underscores, max length 32.
    - **parameter.s782b4996.dstFeatureId** (string) - Required - Identifier of the feature to compare against. Min length 0, max length 32.
    - **parameter.s782b4996.searchScoreFeaRes** (object) - Required - Format of the expected response.
      - **parameter.s782b4996.searchScoreFeaRes.encoding** (string) - Required - Encoding format (fixed: "utf8").
      - **parameter.s782b4996.searchScoreFeaRes.compress** (string) - Required - Compression format (fixed: "raw").
      - **parameter.s782b4996.searchScoreFeaRes.format** (string) - Required - Text format (fixed: "json").
- **payload** (object) - Required - Data payload for the request.
  - **payload.resource** (object) - Required - Audio resource parameters.
    - **payload.resource.encoding** (string) - Required - Audio encoding (fixed: "lame").
    - **payload.resource.sample_rate** (int) - Required - Audio sample rate (e.g., 16000).
    - **payload.resource.channels** (int) - Optional - Number of audio channels (e.g., 1 for mono).
    - **payload.resource.bit_depth** (int) - Optional - Audio bit depth (e.g., 16).
    - **payload.resource.status** (int) - Required - Audio data status, typically 3 (one-time transfer).
    - **payload.resource.audio** (string) - Required - Base64 encoded audio data. Min length 1B, max length 4M.

### Request Example
```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "searchScoreFea",
      "groupId": "iFLYTEK_examples_groupId",
      "dstFeatureId": "iFLYTEK_examples_featureId",
      "searchScoreFeaRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1RTU0UAA..."
    }
  }
}
```

### Response
#### Success Response (200)
- **header** (object) - Platform parameters.
  - **header.code** (int) - 0 indicates successful session call; service success depends on the 'text' field.
  - **header.message** (string) - Description message.
  - **header.sid** (string) - Unique session identifier.
- **payload** (object) - Data segment carrying response data.
  - **payload.searchScoreFeaRes** (object) - Response data block.
    - **payload.searchScoreFeaRes.text** (string) - Base64 encoded response data.

#### Response Example
```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000eebfc@hu178fd7c11f20212882"
  },
  "payload": {
    "searchScoreFeaRes": {
      "text": "eyJzY29yZSI6MC45ODc2NSwiZmVhdHVyZUlkIjoi..."
    }
  }
}
```
**Decoded text field example:**
```json
{
  "score": 0.98765,
  "featureId": "iFLYTEK_examples_featureId"
}
```
```

--------------------------------

### POST /v1/private/s782b4996

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

声纹识别核心业务接口，用于执行声纹特征库管理、特征添加及比对操作。

```APIDOC
## POST /v1/private/s782b4996

### Description
该接口是声纹识别的核心入口，支持创建声纹库、添加音频特征、进行 1:1 比对及 1:N 检索。所有请求必须通过 HMAC-SHA256 签名鉴权。

### Method
POST

### Endpoint
https://api.xf-yun.com/v1/private/s782b4996

### Parameters
#### Query Parameters
- **host** (string) - Required - 请求主机，固定为 api.xf-yun.com
- **date** (string) - Required - RFC1123 格式时间戳，如 "Fri, 23 Apr 2021 02:35:47 GMT"
- **authorization** (string) - Required - 基于 HMAC-SHA256 计算并进行 Base64 编码的签名字符串

#### Request Body
- **audio** (string) - Required - Base64 编码后的音频数据（采样率16k、位长16bit、单声道mp3，建议3-5秒）
- **operation** (string) - Required - 执行的操作类型（如：create_group, add_feature, compare_1v1, compare_1vn 等）

### Request Example
{
  "operation": "compare_1v1",
  "audio": "base64_encoded_audio_data"
}

### Response
#### Success Response (200)
- **code** (integer) - 状态码，0 表示成功
- **message** (string) - 响应描述
- **data** (object) - 包含比对结果或操作详情的 JSON 对象

#### Response Example
{
  "code": 0,
  "message": "success",
  "data": {
    "score": 0.95,
    "result": "match"
  }
}
```

--------------------------------

### POST /searchFea (1:N Feature Comparison)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Performs a 1:N voice feature comparison by sending audio data to search against a specified group of voice features.

```APIDOC
## POST /searchFea

### Description
Performs a 1:N voice feature comparison. The service compares the provided audio against a group of stored features and returns the top K matches.

### Method
POST

### Endpoint
/searchFea

### Parameters
#### Request Body
- **header** (object) - Required - Platform parameters including app_id and status.
- **parameter** (object) - Required - Service-specific parameters including func (searchFea), groupId, and topK.
- **payload** (object) - Required - Audio data including encoding, sample_rate, and base64 encoded audio string.

### Request Example
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "searchFea",
      "groupId": "iFLYTEK_examples_groupId",
      "topK": 2,
      "searchFeaRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1RTU0UAAAAPAAA..."
    }
  }
}

### Response
#### Success Response (200)
- **header** (object) - Contains session ID and status code.
- **payload.searchFeaRes.text** (string) - Base64 encoded JSON string containing the scoreList.

#### Response Example
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e3672@hu178fdb6c69d0210882"
  },
  "payload": {
    "searchFeaRes": {
      "text": "eyJhZ2UiOiJ5b..."
    }
  }
}
```

--------------------------------

### Query Feature List

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Retrieves a list of available audio features. Note that the results may be limited.

```APIDOC
## POST /websites/xfyun_cn_doc_voiceservice_isv/queryFeatureList

### Description
Queries and retrieves a list of audio features. Results may be limited.

### Method
POST

### Endpoint
/websites/xfyun_cn_doc_voiceservice_isv/queryFeatureList

### Parameters
#### Request Body
- **header** (object) - Required - Platform parameters.
  - **header.app_id** (string) - Required - App ID obtained from the platform.
  - **header.status** (int) - Required - Request status, typically 3 (one-time transfer).
- **parameter** (object) - Required - Service feature parameters.
  - **parameter.s782b4996** (object) - Required - Function parameters.
    - **parameter.s782b4996.func** (string) - Required - Specifies the voiceprint capability, set to "queryFeatureList".
    - **parameter.s782b4996.groupId** (string) - Required - Identifier for the group to query features from. Supports alphanumeric characters and underscores, max length 32.
    - **parameter.s782b4996.queryFeatureListRes** (object) - Required - Format of the expected response.
      - **parameter.s782b4996.queryFeatureListRes.encoding** (string) - Required - Encoding format (fixed: "utf8").
      - **parameter.s782b4996.queryFeatureListRes.compress** (string) - Required - Compression format (fixed: "raw").
      - **parameter.s782b4996.queryFeatureListRes.format** (string) - Required - Text format (fixed: "json").

### Request Example
```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "queryFeatureList",
      "groupId": "iFLYTEK_examples_groupId",
      "queryFeatureListRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **header** (object) - Platform parameters.
  - **header.code** (int) - 0 indicates successful session call; service success depends on the 'text' field.
  - **header.message** (string) - Description message.
  - **header.sid** (string) - Unique session identifier.
- **payload** (object) - Data segment carrying response data.
  - **payload.queryFeatureListRes** (object) - Response data block.
    - **payload.queryFeatureListRes.text** (string) - Base64 encoded response data.

#### Response Example
```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000eebfc@hu178fd7c11f20212882"
  },
  "payload": {
    "queryFeatureListRes": {
      "text": "W3siZmVhdHVy..."
    }
  }
}
```
**Decoded text field example:**
```json
[
  {
    "featureInfo": "iFLYTEK_examples_featureInfo",
    "featureId": "iFLYTEK_examples_featureId"
  }
]
```
```

--------------------------------

### POST /createGroup

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Endpoint to create a new voiceprint feature library group.

```APIDOC
## POST /createGroup

### Description
Creates a new voiceprint feature library group using the specified group ID, name, and description.

### Method
POST

### Request Body
- **header** (object) - Required - Platform parameters (app_id, status)
- **parameter** (object) - Required - Service parameters
- **parameter.s782b4996.func** (string) - Required - Set to 'createGroup'
- **parameter.s782b4996.groupId** (string) - Required - Unique group identifier

### Request Example
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "createGroup",
      "groupId": "iFLYTEK_examples_groupId",
      "groupName": "iFLYTEK_examples_groupName",
      "groupInfo": "iFLYTEK_examples_groupInfo",
      "createGroupRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  }
}

### Response
#### Success Response (200)
- **header.code** (int) - 0 indicates successful session call
- **payload.createGroupRes.text** (string) - Base64 encoded response data

#### Response Example
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e55f5@hu178fca72b160210882"
  },
  "payload": {
    "createGroupRes": {
      "text": "eyJncm91cEl..."
    }
  }
}
```

--------------------------------

### Authentication and Authorization

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

Detailed explanation of the signature-based authentication mechanism required for API calls.

```APIDOC
## Authentication and Authorization

### Authentication Method
Requests must be signed. The server verifies the request's legality using this signature. Signature-related parameters are appended to the request URL.

**Important**: The values of `url`, `APISecret`, `APIKey`, and `date` affect the authentication result. Use the example values for debugging.

### Authentication Parameters
- **host** (string, Required): The request host (e.g., `api.xf-yun.com`).
- **date** (string, Required): Current timestamp in RFC1123 format (e.g., `Fri, 23 Apr 2021 02:35:47 GMT`). Must be UTC+0 or GMT. The server checks for clock skew (max 300 seconds deviation).
- **authorization** (string, Required): Base64 encoded signature information.

### Authorization Parameter Generation
1. **Obtain API Key and API Secret**: Get these from the iFlytek Open Platform console.
2. **Construct `authorization_origin`**:
   ```
   api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"
   ```
   - `api_key`: Your obtained API Key.
   - `algorithm`: Encryption algorithm (only `hmac-sha256` supported).
   - `headers`: Fixed parameter names participating in the signature (`host`, `date`, `request-line`).
   - `signature`: Base64 encoded result of signing.

3. **Construct `signature_origin`**: Concatenate `host`, `date`, and `request-line` with specific formatting:
   ```
host: $host
date: $date
$request-line
   ```
   Example `request-line`: `POST /v1/private/s782b4996 HTTP/1.1`

4. **Generate `signature_sha`**: Sign `signature_origin` using `hmac-sha256` with your `APISecret`.
   ```
signature_sha = hmac-sha256(signature_origin, $apiSecret)
   ```

5. **Generate `signature`**: Base64 encode `signature_sha`.
   ```
signature = base64(signature_sha)
   ```
   Example signature: `1jwQbIAKmQE7JwIH0IDxiC1pejrlN+VpHXDWOFVy5NM=`

6. **Assemble `authorization_origin`**: Use the generated `signature` and other parameters as shown in step 2.

7. **Generate `authorization`**: Base64 encode `authorization_origin`.
   Example result: `YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iMWp3UWJJQUttUUU3SndJSDBJRHhpQzFwZWpybE4rVnBIWERXT0ZWeTVOTT0i`

### Example Request URL with Authentication:
```
https://api.xf-yun.com/v1/private/s782b4996?authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iMWp3UWJJQUttUUU3SndJSDBJRHhpQzFwZWpybE4rVnBIWERXT0ZWeTVOTT0i&host=api.xf-yun.com&date=Fri%2C+23+Apr+2021+02%3A35%3A47+GMT
```
```

--------------------------------

### Authentication and Error Handling

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

Details on authentication failures, HTTP status codes, error messages, and resolution steps.

```APIDOC
## Authentication and Error Handling

### Description
This section describes the authentication process and potential errors that may occur. Different HTTP status codes are returned based on the type of authentication failure, along with descriptive error messages and suggested solutions.

### Error Codes

| HTTP Code | Description | Error Message | Resolution |
|---|---|---|---|
| 401 | Missing authorization parameter | {"message":"Unauthorized"} | Check for the presence of the `authorization` parameter. Refer to the detailed rules for generating the `authorization` parameter. |
| 401 | Signature parameter parsing failed | {“message”:”HMAC signature cannot be verified”} | Verify that all signature parameters are present and correct. Ensure the copied `api_key` is accurate. |
| 401 | Signature verification failed | {“message”:”HMAC signature does not match”} | Signature verification failed due to various reasons:
1. Check if `api_key` and `api_secret` are correct.
2. Ensure parameters used for signature calculation (host, date, request-line) are concatenated according to the protocol.
3. Verify the Base64 length of the `signature` is normal (typically 44 bytes). |
| 403 | Clock skew validation failed | {“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”} | Check if the server time is standard. A difference of more than 5 minutes will result in this error. |

### Clock Skew Validation Example

```http
HTTP/1.1 403 Forbidden
Date: Mon, 30 Nov 2020 02:34:33 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}
```
```

--------------------------------

### Voiceprint Recognition API Overview

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

Overview of the Voiceprint Recognition API, its core functionalities, and the typical workflow for its usage.

```APIDOC
## Voiceprint Recognition API

### Description
Voiceprint Recognition (声纹识别) is a technology that extracts speaker characteristics and content information to automatically verify a speaker's identity. It allows for 1:1 verification against a known voiceprint or 1:N retrieval within a database of voiceprints.

### Core Capabilities
1. Create Voiceprint Feature Library (Required)
2. Add Audio Features (Required)
3. Feature Comparison 1:1 (Required)
4. Feature Comparison 1:N (Required)
5. Query Feature List (Optional)
6. Update Audio Features (Optional)
7. Delete Specific Features (Optional)
8. Delete Voiceprint Feature Library (Optional)

### API Requirements
- **Transmission Method**: HTTP/HTTPS (HTTPS recommended for security)
- **Request Address**: `https://api.xf-yun.com/v1/private/s782b4996` (Use domain, not IP)
- **Request Line**: `POST /v1/private/s782b4996 HTTP/1.1`
- **API Authentication**: Signature mechanism (details below)
- **Character Encoding**: UTF-8
- **Response Format**: JSON
- **Development Language**: Any language capable of making HTTP requests
- **Applicable Scope**: Any operating system (not suitable for browsers due to no CORS support)
- **Audio Format**: MP3 with 16kHz sampling rate, 16-bit depth, mono channel
- **Audio Size**: Base64 encoded size not exceeding 4MB. Audio content should be clear with effective frames > 0.5s (3-5 seconds recommended).

### API Call Flow
1. Calculate signature using API Key and API Secret via hmac-sha256, append signature and other parameters to the request URL.
2. Place request parameters and audio data in the HTTP Request Body as a POST form submission.
3. Send the HTTP request to the server and receive the response.
```

--------------------------------

### Authorization Header Format

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

The format of the authorization string before base64 encoding, containing the API key, algorithm, headers, and signature.

```text
api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"
```

--------------------------------

### Add Audio Feature Request - JSON

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

This JSON structure defines the request body for adding audio features. It includes parameters for authentication, feature identification, and audio data encoding. The 'func' parameter must be set to 'createFeature'.

```json
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "createFeature",
      "groupId": "iFLYTEK_examples_groupId",
      "featureId": "iFLYTEK_examples_featureId",
      "featureInfo": "iFLYTEK_examples_featureInfo",
      "createFeatureRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1..."
    }
  }
}
```

--------------------------------

### Feature Comparison (1:1)

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html

This endpoint performs a 1:1 feature comparison, returning a similarity score between two voice features.

```APIDOC
## POST /websites/xfyun_cn_doc_voiceservice_isv/feature_comparison_1_1

### Description
Performs a 1:1 voice feature comparison to determine similarity.

### Method
POST

### Endpoint
/websites/xfyun_cn_doc_voiceservice_isv/feature_comparison_1_1

### Parameters
#### Request Body
- **header** (object) - Required - Platform parameters.
  - **header.sid** (string) - Required - Session unique identifier.
  - **header.code** (int) - Required - Session call status code. 0 indicates success.
  - **header.message** (string) - Required - Description message.
- **payload** (object) - Required - Data segment.
  - **payload.searchScoreFeaRes** (object) - Required - Response data block.
    - **payload.searchScoreFeaRes.text** (string) - Required - Base64 encoded response data.

### Request Example
```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e1142@hu178fd98935d0212882"
  },
  "payload": {
    "searchScoreFeaRes": {
      "text": "eyJhZ2UiOiJja..."
    }
  }
}
```

### Response
#### Success Response (200)
- **header** (object) - Platform parameters.
  - **header.sid** (string) - Session unique identifier.
  - **header.code** (int) - Session call status code. 0 indicates success.
  - **header.message** (string) - Description message.
- **payload** (object) - Data segment.
  - **payload.searchScoreFeaRes** (object) - Response data block.
    - **payload.searchScoreFeaRes.text** (string) - Base64 encoded response data. Decoded content includes:
      - **score** (float) - Similarity score (0-1).
      - **featureInfo** (string) - Description of the target feature.
      - **featureId** (string) - Unique identifier for the target feature.

#### Response Example
```json
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e1142@hu178fd98935d0212882"
  },
  "payload": {
    "searchScoreFeaRes": {
      "text": "eyJhZ2UiOiJja..."
    }
  }
}
```

**Decoded text field example:**
```json
{
  "score": 1,
  "featureInfo": "iFLYTEK_examples_featureInfo",
  "featureId": "iFLYTEK_examples_featureId"
}
```
```

--------------------------------

### POST /createFeature

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Adds a new audio feature to a specified group. This endpoint processes the provided audio data to generate a unique feature identifier.

```APIDOC
## POST /createFeature

### Description
Adds a new audio feature to a specified group for voice recognition purposes.

### Method
POST

### Endpoint
/createFeature

### Request Body
- **header** (object) - Required - Platform parameters including app_id and status.
- **parameter.s782b4996.func** (string) - Required - Set to 'createFeature'.
- **parameter.s782b4996.groupId** (string) - Required - Group identifier (max 32 chars).
- **parameter.s782b4996.featureId** (string) - Required - Unique feature identifier.
- **payload.resource.audio** (string) - Required - Base64 encoded audio data.

### Request Example
{
  "header": {
    "app_id": "your_app_id",
    "status": 3
  },
  "parameter": {
    "s782b4996": {
      "func": "createFeature",
      "groupId": "iFLYTEK_examples_groupId",
      "featureId": "iFLYTEK_examples_featureId",
      "createFeatureRes": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "resource": {
      "encoding": "lame",
      "sample_rate": 16000,
      "status": 3,
      "audio": "SUQzBAAAAAAAI1..."
    }
  }
}

### Response
#### Success Response (200)
- **header.sid** (string) - Session unique identifier.
- **payload.createFeatureRes.text** (string) - Base64 encoded response containing the new featureId.

#### Response Example
{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000ec93e@hu178fd5902750212882"
  },
  "payload": {
    "createFeatureRes": {
      "text": "eyJmZWF0dXJl..."
    }
  }
}
```

--------------------------------

### Signature Origin String Construction

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

The raw string format used to generate the HMAC-SHA256 signature, combining host, date, and the request line.

```text
host: api.xf-yun.com
date: Fri, 23 Apr 2021 02:35:47 GMT
POST /v1/private/s782b4996 HTTP/1.1
```

--------------------------------

### Authentication Error Handling

Source: https://www.xfyun.cn/doc/voiceservice/isv/API.html#%E5%A3%B0%E7%BA%B9%E8%AF%86%E5%88%AB-api-%E6%96%87%E6%A1%A3

Details on HTTP status codes and error messages returned when authentication fails.

```APIDOC
## Authentication Error Handling

### Description
Provides guidance on troubleshooting authentication failures, including missing parameters, signature mismatches, and clock drift issues.

### Error Codes
- **401** - Unauthorized: Missing authorization parameter or signature verification failed.
- **403** - Forbidden: Clock drift check failed (ensure server time is synchronized within 5 minutes).

### Response Example
{
  "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}
```