文档

移动端SDK说明

更新时间:

本文为您介绍传入录音文件,完成音频文件识别并返回结果的流程说明。

使用须知

  • 输入格式:WAV/MP3/AAC。

  • 时长限制:识别语音文件大小不能超过100 MB。

  • 设置多语言识别:在管控台编辑项目中进行模型选择,详情请参见管理项目

服务地址

访问类型

说明

URL

Host

外网访问

所有服务器均可使用外网访问URL。

  • 上海:https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer

  • 北京:https://nls-gateway-cn-beijing.aliyuncs.com/stream/v1/FlashRecognizer

  • 深圳:https://nls-gateway-cn-shenzhen.aliyuncs.com/stream/v1/FlashRecognizer

  • 上海:nls-gateway-cn-shanghai.aliyuncs.com

  • 北京:nls-gateway-cn-beijing.aliyuncs.com

  • 深圳:nls-gateway-cn-shenzhen.aliyuncs.com

阿里云上海ECS内网访问

使用阿里云上海、北京、深圳ECS(即ECS地域为华东2(上海)、华北2(北京)、华南1(深圳)),可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。

说明
  • 使用内网访问方式,将不会产生ECS实例的公网流量费用。

  • 关于ECS的网络类型请参见网络类型

  • 上海:http://nls-gateway-cn-shanghai-internal.aliyuncs.com/stream/v1/FlashRecognizer

  • 北京:http://nls-gateway-cn-beijing-internal.aliyuncs.com/stream/v1/FlashRecognizer

  • 深圳:http://nls-gateway-cn-shenzhen-internal.aliyuncs.com/stream/v1/FlashRecognizer

  • 上海:nls-gateway-cn-shanghai-internal.aliyuncs.com

  • 北京:nls-gateway-cn-beijing-internal.aliyuncs.com

  • 深圳:nls-gateway-cn-shenzhen-internal.aliyuncs.com

说明

以下将以使用外网访问URL的方式进行介绍。如果您使用阿里云上海ECS,并需要通过内网访问URL,则使用HTTP协议,并替换外网访问的URL和Host。

交互流程

下图展示iOS SDK和Android SDK的交互流程。

image
  1. 鉴权和初始化

    客户端与服务端建立连接时,使用Access Token进行鉴权。关于Token获取请参见获取Token概述

    初始化参数表

    参数

    类型

    是否必选

    说明

    url

    String

    语音服务URL地址。

    app_key

    String

    管控台创建项目的appkey。

    token

    String

    请确保该Token可以使用并在有效期内。

    说明

    Token可以在初始化时设置,也可通过参数设置进行更新。

    device_id

    String

    设备标识,唯一表示一台设备(如Mac地址/SN/UniquePsuedoID)。

  2. 开始文件识别

    客户端发起文件识别请求时,需要通过接口传入JSON格式的params参数。

    参数

    类型

    是否必选

    说明

    file_path

    String

    需要进行识别的文件绝对路径。

    direct_ip

    String

    您可自行完成服务地址DNS解析,传入IP地址进行访问。

    nls_config

    JsonObject

    服务细节参数配置。

    其中,nls_config字段用于设置服务的具体配置参数,多与识别效果相关。

    参数

    类型

    是否必选

    说明

    format

    String

    音频编码格式,支持WAV/MP3/AAC格式。

    sample_rate

    Integer

    识别模型使用的采样率,一般不设置,在管控台进行配置。

    enable_inverse_text_normalization

    Boolean

    ITN(逆文本inverse text normalization)中文数字转换阿拉伯数字。设置为True时,中文数字将转为阿拉伯数字输出,默认值:False。

    max_end_silence

    Integer

    允许的最大结束静音,默认值450,单位是毫秒。

    customization_id

    String

    通过POP API创建的定制模型id,默认不添加。

    vocabulary_id

    String

    创建的泛热词表ID,默认不添加。

    enable_word_level_result

    Boolean

    是否开启词信息返回,默认false。

    first_channel_only

    Boolean

    是否开启只处理第一个声道,默认false。

  3. 获取识别结果

    启动任务后一段时间(根据文件长度和网络情况而定)将收到EVENT_FILE_TRANS_RESULT事件,即完整转写结果,示例如下。

    {
        "task_id":"e76f979b33d9443eb6fbf770315a****",
        "status":20000000,
        "message":"SUCCESS",
        "flash_result":{
            "duration":299,  //音频时长
            "completed":true, 
            "sentences":[
                {
                    "text":"啊,",  //句子级别的识别结果
                    "begin_time":3700,  //句子的开始时间,单位:毫秒
                    "end_time":3940,  //句子的结束时间,单位:毫秒
                    "channel_id":0,  //多个声道的音频文件会区分返回识别结果,声道id从0计数
                    "words":[
                        {
                            "text":"啊",  //当前句子包含的词信息
                            "begin_time":3700,  //当前词开始时间,单位:毫秒
                            "end_time":3940,  //当前词结束时间,单位:毫秒
                            "punc":","  //当前词尾的标点信息,没有标点则为空
                        }
                    ]
                },
                {
                    "text":"我在哪呀了。",
                    "begin_time":3940,
                    "end_time":4720,
                    "channel_id":0,
                    "words":[
                        {
                            "text":"我",
                            "begin_time":3940, 
                            "end_time":4040,
                            "punc":","
                        },
                        {
                            "text":"在哪",
                            "begin_time":4040,
                            "end_time":4340,
                            "punc":","
                        },
                        {
                            "text":"呀了",
                            "begin_time":4340,
                            "end_time":4720,
                            "punc":","
                        }
                    ]
                }
            ]
        }
    }

    响应消息为JSON格式,包含如下字段。

    字段

    说明

    task_id

    任务ID,任务唯一标识。

    status

    状态码

    message

    状态消息

    flash_result

    识别结果对象

    其中,flash_result对象包括如下字段。

    字段

    说明

    sentences

    句子级别的识别结果,是一个对象数组。

    其中,sentences数组对象包含如下字段。

    字段

    说明

    text

    识别结果。

    begin_time

    识别结果的语音起点在音频流的时间偏移,单位毫秒。

    end_time

    识别结果的语音尾点在音频流的时间偏移,单位毫秒。

错误码

通用错误码

状态码

状态消息

原因

解决方案

40000000

默认的客户端错误码,对应了多个错误消息。

用户使用了不合理的参数或者调用逻辑。

请参考官网文档示例代码进行对比测试验证。

40000001

The token 'xxx' has expired;

The token 'xxx' is invalid

用户使用了不合理的参数或者调用逻辑。通用客户端错误码,通常是涉及Token相关的不正确使用,例如Token过期或者非法。

请参考官网文档示例代码进行对比测试验证。

40000002

Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!

无效或者错误的报文消息。

请参考官网文档示例代码进行对比测试验证。

40000003

PARAMETER_INVALID;

Failed to decode url params

用户传递的参数有误,一般常见于RESTful接口调用。

请参考官网文档示例代码进行对比测试验证。

40000005

Gateway:TOO_MANY_REQUESTS:Too many requests!

并发请求过多。

如果是试用版调用,建议您升级为商用版本以增大并发。

如果已是商用版,可购买并发资源包,扩充您的并发额度。

40000009

Invalid wav header!

错误的消息头。

如果您发送的是WAV语音文件,且设置formatwav,请注意检查该语音文件的WAV头是否正确,否则可能会被服务端拒绝。

40000009

Too large wav header!

传输的语音WAV头不合法。

建议使用PCM、OPUS等格式发送音频流,如果是WAV,建议关注语音文件的WAV头信息是否为正确的数据长度大小。

40000010

Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!

试用期已结束,并且未开通商用版、或账号欠费。

请登录控制台确认服务开通状态以及账户余额。

40010001

Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal

不支持的接口或参数。

请检查调用时传递的参数内容是否和官网文档要求的一致,并结合错误信息对比排查,设置为正确的参数。

比如您是否通过curl命令执行RESTful接口请求, 拼接的URL是否合法。

40010003

Gateway:DIRECTIVE_INVALID:[xxx]

客户端侧通用错误码。

表示客户端传递了不正确的参数或指令,在不同的接口上有对应的详细报错信息,请参考对应文档进行正确设置。

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

在请求处理完成前客户端主动结束。

无,或者请在服务端响应完成后再关闭链接。

40010005

Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!

客户端发送了当前不支持的消息指令。

请参考官网文档示例代码进行对比测试验证。

40020105

Meta:APPKEY_NOT_EXIST:Appkey not exist!

使用了不存在的Appkey。

请确认是否使用了不存在的Appkey,Appkey可以通过登录控制台后查看项目配置。

40020106

Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!

调用时传递的Appkey和Token并非同一个账号UID所创建,导致不匹配。

请检查是否存在两个账号混用的情况,避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。

403

Forbidden

使用的Token无效,例如Token不存在或者已过期。

请设置正确的Token。Token存在有效期限制,请及时在过期前获取新的Token。

41000003

MetaInfo doesn't have end point info

无法获取该Appkey的路由信息。

请检查是否存在两个账号混用的情况,避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。

41010101

UNSUPPORTED_SAMPLE_RATE

不支持的采样率格式。

当前实时语音识别只支持8000 Hz和16000 Hz两种采样率格式的音频。

41040201

Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!

获取客户端发送的数据超时失败。

客户端在调用实时语音识别时请保持实时速率发送,发送完成后及时关闭链接。

50000000

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常,通常为偶发出现。

一般重试调用即可恢复。

50000001

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常,通常为偶发出现。

一般重试调用即可恢复。

52010001

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常,通常为偶发出现。

一般重试调用即可恢复。

一句话识别错误码

状态码

状态消息

原因

解决方案

40000000

Gateway:CLIENT_ERROR:Empty audio data!

没有音频数据。

建议参考公共云示例代码,请求时发送音频数据。

40000004

Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time

请求建立链接后,长时间没有发送任何数据,超过10s后服务端会返回此错误信息。

请在建立链接后和服务端保持交互,比如持续发送语音流,您可以在采集音频的同时进行发送, 发送结束后及时关闭链接。

40010002

Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!

发送了服务端不支持的消息指令。

请参考官网文档示例代码进行对比测试验证。

40010003

Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)

热词数量设置过多。

请参考API进行正确设置。

41010104

TOO_LONG_SPEECH

发送的语音时长超过限制,仅在一句话识别接口上出现。

一句话语音识别支持60s以内的音频,如果超过60s,建议调用实时语音识别接口。

41010105

SILENT_SPEECH

纯静音数据或噪音数据,导致无法检测出任何有效语音。

无。

一句话识别/实时语音识别/录音文件识别极速版

  • 配置或参数错误

    状态码

    状态消息

    原因

    解决方案

    240999

    DEFAULT_ERROR

    内部默认错误。

    内部未明确错误。

    240001

    NUI_CONFIG_INVALID

    配置文件错误。

    配置文件错误,请确认传入的资源路径内是否有资源文件。如果是Android平台,请参考代码样例主动使用copyAssets接口。

    240002

    ILLEGAL_PARAM

    非法参数。

    请确认传入的格式是否正确,包括字段类型、值范围限制。

    240003

    ILLEGAL_INIT_PARAM

    初始化参数非法。

    请确认初始化参数格式是否错误或缺少必须字段。

    240004

    NECESSARY_PARAM_LACK

    缺少必须参数。

    请确认接口调用时的必须参数。

    240005

    NULL_PARAM_ERROR

    参数为空。

    确认参数是否为空。

    240006

    NULL_LISTENER_ERROR

    未定义事件回调。

    确认回调事件是否正确赋值。

    240007

    NULL_DIALOG_ERROR

    无有效对话实例,一般在内部状态错误时发生。

    请确认接口调用前是否为正确状态,可使用cancel接口恢复idle状态。

    240008

    NULL_ENGINE_ERROR

    无有效引擎实例,请检查是否初始化成功。

    请确认是否初始化成功。

    240009

    ILLEGAL_DATA

    传入音频数据地址或长度非法。

    请确认传入的数据长度值。

  • SDK状态错误

    状态码

    状态消息

    原因

    解决方案

    240010

    ILLEGAL_REENTRANT

    退出后调用SDK接口。

    不影响功能时可忽略。

    240011

    SDK_NOT_INIT

    SDK未正确初始化。

    确认初始化返回值正确再进行其他接口使用。

    240012

    SDK_ALREADY_INIT

    重复调用SDK初始化接口。

    确认初始化调用逻辑。

    240013

    DIALOG_INVALID_STATE

    内部对话状态错误。

    请阅读SDK流程图,确认是否在错误状态下调用接口。

    240014

    STATE_INVALID

    SDK内部状态错误。

    请阅读SDK流程图,确认是否在错误状态下调用接口。

    240015

    ILLEGAL_FUNC_CALL

    该模式无法调用接口。

    请确认接口调用是否合理。

  • 系统调用错误

    状态码

    状态消息

    原因

    解决方案

    240020

    MEM_ALLOC_ERROR

    内存分配错误。

    检查内存是否不足。

    240021

    FILE_ACCESS_FAIL

    文件访问错误。

    检查文件是否提供读写权限。

    240022

    CREATE_DIR_ERROR

    创建目录错误。

    检查是否有写权限。

  • SDK内部调用错误

    状态码

    状态消息

    原因

    解决方案

    240030

    CREATE_NUI_ERROR

    引擎创建失败。

    创建实例失败,一般为系统资源不足。

    240031

    TEXT_DIALOG_START_FAIL

    发起文本理解失败。

    文本转语义理解失败,检查网络连接或URL以及Token等信息是否有效。

    240032

    TEXT_CANCEL_START_FAIL

    取消文本理解失败。

    可忽略。

    240033

    WUW_DUPLICATE

    动态唤醒词重复。

    可忽略。

  • 本地引擎调用错误

    状态码

    状态消息

    原因

    解决方案

    240040

    CEI_INIT_FAIL

    本地引擎初始化失败。

    请确认本地引擎的模型是否有效、目录是否可读写。

  • 音频错误

    状态码

    状态消息

    原因

    解决方案

    240051

    UPDATE_AUDIO_ERROR

    推送音频错误,一般为输入音频长度大于所需音频。

    确认推送的音频长度是否非法。

    240052

    MIC_ERROR

    连续2s未获取到音频。

    请确认在音频数据回调中是否正确提供所需长度的音频。

  • 网络错误

    状态码

    状态消息

    原因

    解决方案

    240060

    CREATE_DA_REQUEST_ERROR

    创建对话助手实例失败

    可忽略。

    240061

    START_DA_REQUEST_ERROR

    发起对话助手请求失败

    可忽略。

    240062

    DEFAULT_NLS_ERROR

    服务端发生错误。

    说明

    该错误同时包含服务端返回错误内容。

    请参考服务端错误码进一步定位。

    240063

    SSL_ERROR

    创建SSL实例错误。

    偶现请忽略。

    240064

    SSL_CONNECT_FAILED

    SSL连接失败。

    连接异常,请检查服务URL或者本地网络连接是否正常。

    240065

    HTTP_CONNECT_FAILED

    HTTP连接失败。

    服务连接错误,可通过日志文件查看HTTP返回值确认原因。

    240066

    DNS_FAILED

    DNS解析失败。

    请检查本地网络是否正常、DNS服务是否正常。

    240067

    CONNECT_FAILED

    Socket连接失败。

    检查网络连接。

    240068

    SERVER_NOT_ACCESS

    服务端无法访问。

    请检查Token是否过期或者URL是否正确。

    240069

    SOCKET_CLOSED

    Socket已关闭。

    偶现请忽略。

    240070

    AUTH_FAILED

    鉴权失败。

    请检查是否提供正确的ak_secret,ak_id,app_key,sdk_code和device_id等信息,以及确认是否开通足够配额。

    240071

    HTTPDNS_FAILED

    使用客户端传入的IP连接失败。

    如果使用直接传入IP进行访问,请确认IP是否可访问。

    240072

    HTTP_SEND_FAILED

    文件转写HTTP发送失败。

    确认网络连接是否正常。

    240073

    HTTP_RECEIVE_FAILED

    文件转写HTTP接收失败。

    确认网络连接是否正常。

    240074

    HTTP_RESPONSE_ERROR

    文件转写接收内容解析失败

    服务端返回内容错误。

    240075

    HTTP_SERVER_ERROR

    文件转写服务错误。

    请参考服务端错误码进一步定位。

  • 本页导读 (1)