中文识别大模型

中文识别大模型接口文档
=========

1\.  接口协议描述
----------

中文语音大模型识别能力，将中文短音频(≤60秒)精准识别成文字，实时返回文字结果，真实还原语音内容。

2\. 接口说明
--------

### 2.1. 请求方法和URL

```
ws(s)://iat.xf-yun.com/v1
```

注意：默认情况下，展示的URL为三地公共域名。如果该域名无法访问，可能是因为网络问题或其他原因，紧急情况请及时联系我们的技术支持团队。

### 2.2. 接口Demo

语音识别v2 demo Java语言

语音识别v2 demo Python语言

demo 覆盖部分语言，其他语言参照下方接口文档进行开发。

### 2.3. 接口要求

接口类型：流式 \[ws(s)\]

接口鉴权：使用签名机制进行鉴权，签名详情参照 “[接口鉴权](https://docs.iflyaicloud.com/aipaas-doc/docs/api%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83.html)”

3\. 请求
------

### 3.1. 请求协议示例

```
{
    "header": {
        "app_id": "123456",
        "uid": "39769795890",
        "did": "SR082321940000200",
        "imei": "8664020318693660",
        "imsi": "4600264952729100",
        "mac": "6c:92:bf:65:c6:14",
        "net_type": "wifi",
        "net_isp": "CMCC",
        "request_id": null,
        "res_id": "",
        "status": 0
    },
    "parameter": {
        "iat": {
            "domain": "slm",
            "language": "zh_cn",
            "accent": "mandarin",
            "eos": 600,
            "vinfo": 0,
            "result": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "json"
            }
        }
    },
    "payload": {
        "audio": {
            "encoding": "speex-wb",
            "sample_rate": 16000,
            "channels": 1,
            "bit_depth": 16,
            "status": 0,
            "seq": 0,
            "audio": "",
            "frame_size": 0
        }
    }
}
```

**协议结构说明**

| 字段      | 含义         | 类型   | 说明                                                         |
| --------- | ------------ | ------ | ------------------------------------------------------------ |
| header    | 协议头部     | Object | 协议头部，用于描述平台特性的参数，详见 3.2.1 平台参数。      |
| parameter | 能力参数     | Object | AI 特性参数，用于控制 AI 引擎特性的开关。                    |
| iat       | 服务别名     | Object |                                                              |
| result    | 响应数据控制 | Object | 数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系。 |
| payload   | 输入数据段   | Object | 数据段，携带请求的数据。                                     |
| audio     | 输入数据     | Object | 输入数据，详见 3.2.3 请求数据。                              |

### 3.2. 请求参数

#### 3.2.1. 平台参数

| 字段        | 含义                                                      | 类型   | 限制                    | 是否必传 |
| ----------- | --------------------------------------------------------- | ------ | ----------------------- | -------- |
| app\_id     | 在平台申请的app id信息                                    | string | "maxLength":50          | 是       |
| uid         | 请求用户服务返回的uid，用户及设备级别个性化功能依赖此参数 | string | "maxLength":50          | 否       |
| did         | 请求方确保唯一的设备标志，设备级别个性化功能依赖此参数    | string | "maxLength":50          | 否       |
| imei        | 设备imei信息                                              | string | "maxLength":50          | 否       |
| imsi        | 设备imsi信息                                              | string | "maxLength":50          | 否       |
| mac         | 设备mac信息                                               | string | "maxLength":50          | 否       |
| net\_type   | 网络类型，可选值为wifi、2G、3G、4G、5G                    | string | wifi、2G、3G、4G、5G    | 否       |
| net\_isp    | 运营商信息，可选值为CMCC、CUCC、CTCC、other               | string | CMCC、CUCC、CTCC、other | 否       |
| request\_id | 客户端请求的会话唯一标识                                  | string | "maxLength":64          | 否       |
| res\_id     | 个性化资源ID                                              | string | "maxLength":1024        | 否       |
| status      | 请求状态，可选值为：0-开始、1-继续、2-结束                | int    | 0、1、2                 | 是       |

#### 3.2.2. 服务特性参数

**特性参数**

| 能力特性名称    | 特性标识                                  | 数据类型 |
| --------------- | ----------------------------------------- | -------- |
| 听写-中文大模型 | domain=slm language=zh_cn accent=mandarin | string   |

**功能参数**

不同特性参数对应功能参数可能会有差异，请根据具体接入特性对应传参

domain=slm language=zh_cn accent=mandarin

| 功能标识 | 功能描述 | 数据类型 | 取值范围 | 必填 | 默认值 |
| :------- | :----------------------------------------------------------- | :------- | :---------------------------------- | :--- | :----- |
| vgap | 子句间隔：用于判定音频是否被切分为一个独立的句子，相邻两段语音之间的间隔超过给定值，上一段语音会被判定为一个独立子句 | int | 最小值:300, 最大值:1000 | 否 | 300 |
| eos | 尾静音截断：引擎判定结束的时间，连续检测给定时间长度的音频，均为静音，则引擎停止识别 | int | 最小值:600, 最大值:60000 | 否 | 600 |
| vinfo | 句子级别帧对齐:给出一次会话中，子句的vad边界信息 | int | 0:不返回vad信息, 1:返回vad信息 | 否 | 0 |
| dwa | 流式识别PGS：流式识别功能，打开后，会话过程中实时给出语音识别的结果，而不是子句结束时才给结果 | string | 最小长度:0, 最大长度:10 | 否 | |
| proc | 后处理功能关闭开关：关闭后处理的所有功能，仅做简单的json格式转换等格式处理操作 | int | 0:关闭, 1:开启 | 否 | 0 |
| ptt | 标点预测：在语音识别结果中增加标点符号 | int | 0:关闭, 1:开启 | 否 | 0 |
| smth | 顺滑功能：将语音识别结果中的顺滑词（语气词、叠词）进行标记，业务侧通过标记过滤语气词最终展现识别结果 | int | 0:关闭, 1:开启 | 否 | 0 |
| nunum | 数字规整：将语音识别结果中的原始文字串转为相应的阿拉伯数字或者符号 | int | 0:关闭, 1:开启 | 否 | 0 |
| rlang | 字体 zh-cn :简体中文 zh-hk :繁体香港 默认简体中文，受限功能，未授权AppId无法使用，如果开启后没有效果，可能是没有权限，需要提交工单申请 (itsm.iflytek.com --->AI工程院AICloud研发部--【01】线上问题及授权管理- 云AI能力授权申请). | string | zh-cn :简体中文 zh-hk :繁体香港 | 否 | |

**响应数据参数**

result 段的参数（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围         | 默认值 | 说明           | 必填 |
| -------- | ------------ | -------- | ---------------- | ------ | -------------- | ---- |
| encoding | 文本编码     | string   | utf8, gb2312     | utf8   | 取值范围可枚举 | 否   |
| compress | 文本压缩格式 | string   | raw, gzip        | raw    | 取值范围可枚举 | 否   |
| format   | 文本格式     | string   | plain, json, xml | json   | 取值范围可枚举 | 否   |

#### 3.2.3. 请求数据

audio（默认请求）

| 字段         | 含义     | 数据类型 | 取值范围                                       | 默认值   | 说明                                        | 必填 |
| ------------ | -------- | -------- | ---------------------------------------------- | -------- | ------------------------------------------- | ---- |
| encoding     | 音频编码 | string   | lame, speex, opus, opus-wb, speex-wb, raw, ico | speex-wb | 取值范围可枚举                              | 否   |
| sample\_rate | 采样率   | int      | 16000, 8000                                    | 16000    | 音频采样率，可枚举                          | 否   |
| channels     | 声道数   | int      | 1, 2                                           | 1        | 声道数，可枚举                              | 否   |
| bit\_depth   | 位深     | int      | 16, 8                                          | 16       | 单位bit，可枚举                             | 否   |
| status       | 数据状态 | int      | 0:开始, 1:继续, 2:结束                         | 0        | 取值范围为：0（开始）、1（继续）、2（结束） | 否   |
| seq          | 数据序号 | int      | 最小值:0, 最大值:9999999                       | 0        | 标明数据为第几块                            | 否   |
| audio        | 音频数据 | string   | 最小尺寸:0B, 最大尺寸:10485760B                |          | 推荐按照1280字节40ms间隔发送音频数据，对于压缩格式根据压缩率不同控制发包大小，过快的发包会影响引擎性能。                             | 是   |
| frame\_size  | 帧大小   | int      | 最小值:0, 最大值:1024                          | 0        | 帧大小，默认0                               | 否   |

4\. 响应
------

### 4.1. 响应协议示例

```
{
    "header": {
        "code": "0",
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "result": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "json",
            "status": 0,
            "seq": 0,
            "text": ""
        }
    }
}
```

**协议结构说明**

| 字段    | 含义       | 类型   | 说明                                                    |
| ------- | ---------- | ------ | ------------------------------------------------------- |
| header  | 协议头部   | Object | 协议头部，用于描述平台特性的参数，详见 4.2.1 平台参数。 |
| payload | 响应数据块 | Object | 数据段，携带响应的数据。                                |
| result  | 响应数据块 | Object | 输出数据，详见 4.2.2 响应数据参数。                     |

### 4.2. 响应参数

#### 4.2.1. 平台参数

| 字段    | 含义                            | 类型   | 是否必选 |
| ------- | ------------------------------- | ------ | -------- |
| code    | 返回码，0表示成功，其它表示异常 | int    | 是       |
| message | 错误描述                        | string | 是       |
| sid     | 本次会话的id                    | string | 是       |

#### 4.2.2. 响应数据参数

result（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围                     | 默认值 | 说明                                        | 必填 |
| -------- | ------------ | -------- | ---------------------------- | ------ | ------------------------------------------- | ---- |
| encoding | 文本编码     | string   | utf8, gb2312                 | utf8   | 取值范围可枚举                              | 否   |
| compress | 文本压缩格式 | string   | raw, gzip                    | raw    | 取值范围可枚举                              | 否   |
| format   | 文本格式     | string   | plain, json, xml             | json   | 取值范围可枚举                              | 否   |
| status   | 数据状态     | int      | 0:开始, 1:继续, 2:结束       | 0      | 取值范围为：0（开始）、1（继续）、2（结束） | 否   |
| seq      | 数据序号     | int      | 最小值:0, 最大值:9999999     | 0      |                                             | 是   |
| text     | 文本数据     | string   | 最小长度:0, 最大长度:1000000 |        |                                             | 是   |

### 4.3. 响应数据解析

result.text

**示例：**

```
{
    "bg": null,
    "ed": null,
    "ls": null,
    "sn": null,
    "pgs": null,
    "rst": null,
    "rg": [
        {}
    ],
    "ws": [
        {
            "wb": null,
            "wc": null,
            "we": null,
            "wp": null,
            "cw": [
                {
                    "sc": null,
                    "ph": null,
                    "w": null
                }
            ]
        }
    ]
}
```

**解析：**

|      | 字段 | 含义 | 数据类型 | 取值范围     | 默认值 | 说明                                                         |
| ---- | ---- | ---- | -------- | ------------ | ------ | ------------------------------------------------------------ |
|      | bg   |      | float    | \--          | 140    | 本次识别结果的语音开始端点，以ms为单位                       |
|      | ed   |      | float    | \--          | 2280   | 本次识别结果的语音结束端点，以ms为单位                       |
|      | ls   |      | boolean  | true: false: | false  | 本次结果是否为最后一块结果                                   |
|      | sn   |      | float    | \--          | 1      | 本次识别结果在总体识别结果中的序号                           |
|      | pgs  |      | string   | \--          | rpl    | 流式识别场景下，本次识别结果操作方式，rpl 为替换前一次识别结果，apd为替换前一次识别结果 |
|      | rst  |      | string   | \--          | rlt    | 流式识别场景下，本地识别结果的类型，rlt为子句最终结果，pgs 为子句过程的流式结果 |
|      | rg   |      | array    | \--          | \[\]   | 流式识别场景下，结果标识字段，字段为2维数组，第一个值为 sn 的值，第二个为替换子句的终止sn号 |
|      | ws   |      | array    | \--          | \[\]   | 本次识别结果的内容，是一个多维数组，每个值表示一个槽         |

5\. 错误码列表
---------

错误码示例：

```
{
    "code":10003, // 平台通用错误码，详细信息请参照 5.1 平台通用错误码
    "message":"WrapperInitErr;errno=101", // errno 为引擎错误码
    "sid":"ocr00088c7d@dx170194697e9a11d902"
}
```

### 5.1. 平台通用错误码

| 错误码        | 错误描述                                     | 说明                                         | 处理策略                                                     |
| ------------- | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| 10009         | input invalid data                           | 输入数据非法                                 | 检查输入数据                                                 |
| 10010         | service license not enough                   | 没有授权许可或授权数已满                     | 提交工单                                                     |
| 10019         | service read buffer timeout, session timeout | session超时                                  | 检查是否数据发送完毕但未关闭连接                             |
| 10043         | Syscall AudioCodingDecode error              | 音频解码失败                                 | 检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致 |
| 10114         | session timeout                              | session 超时                                 | 会话时间超时，检查是否发送数据时间超过了60s                  |
| 10139         | invalid param                                | 参数错误                                     | 检查参数是否正确                                             |
| 10160         | parse request json error                     | 请求数据格式非法                             | 检查请求数据是否是合法的json                                 |
| 10161         | parse base64 string error                    | base64解码失败                               | 检查发送的数据是否使用base64编码了                           |
| 10163         | param validate error:...                     | 参数校验失败                                 | 具体原因见详细的描述                                         |
| 10200         | read data timeout                            | 读取数据超时                                 | 检查是否累计10s未发送数据并且未关闭连接                      |
| 10222         | context deadline exceeded                    | 1.上传的数据超过了接口上限； 2.SSL证书无效； | 1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit； |
| 10223         | RemoteLB: can't find valued addr             | lb 找不到节点                                | 提交工单                                                     |
| 10313         | invalid appid                                | appid和apikey不匹配                          | 检查appid是否合法                                            |
| 10317         | invalid version                              | 版本非法                                     | 请到控制台提交工单联系技术人员                               |
| 10700         | not authority                                | 引擎异常                                     | 按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。 |
| 11200         | auth no license                              | 功能未授权                                   | 请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。 |
| 11201         | auth no enough license                       | 该APPID的每日交互次数超过限制                | 根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。 |
| 11503         | server error :atmos return an error data     | 服务内部响应数据错误                         | 提交工单                                                     |
| 11502         | server error: too many datas in resp         | 服务配置错误                                 | 提交工单                                                     |
| 100001~100010 | WrapperInitErr                               | 调用引擎时出现错误                           | 请根据message中包含的errno前往 5.2引擎错误码 查看对应的说明及处理策略 |