全部产品

API使用

更新时间:2017-09-12 11:28:16   分享:   

接口调用方式

“录音文件识别”API包括两部分:POST方式的“请求调用接口”,GET方式的“结果查询接口”。

请求调用接口

  • 当采用轮询方式时,提交识别请求,获取id,供后续轮询使用。
  • 当采用回调方式时,提交识别请求和回调 url。识别完成后会把结果发送到回调地址。
    • 注意:回调结果请求内容为 JSON 字符串,格式与下面结果查询接口返回的 JSON 相同

大小限制

  • 文件大小需控制在128MB以下
  • 语音时长需控制在1小时内

URL说明

协议 URL 方法 参数
HTTPS https://nlsapi.aliyun.com/transcriptions POST JSON字符串

输入参数

“请求调用接口”的关键请求参数,以json格式放置于Https Body内,并作为数加验证的body参数进行加密。

  1. {
  2. "app_key": "***",
  3. "oss_link": "***",
  4. "auto_split":false,
  5. "vocabulary_id":"vocab_id",
  6. //valid_times是获取语音的指定时间段的识别内容,如果不需要,则不用填写
  7. "valid_times": [
  8. {
  9. "begin_time": 200,
  10. "end_time":2000,
  11. "channel_id": 0
  12. }
  13. ]
  14. }
  • 请求参数JSON字符串:
属性 值类型 是否必须 说明
app_key String 业务方或者业务场景的标记
oss_link String 音频文件存放的OSS地址,只支持HTTP
customization_id String 使用定制模型特性的模型id
auto_split Boolean 是否开启智能分轨 (只支持8k采样率单通道语音)
vocabulary_id String 使用热词特性的词表id
valid_times List< ValidTime > 有效时间段信息,用来排除一些不必要的时间段
enable_callback Boolean 是否启用回调功能,默认值为false
callback_url String 回调用户服务的地址,enable_callback=true时,本字段必填,url支持http和https
  • 有效时间段ValidTime描述:
属性 值类型 是否必须 说明
begin_time Int 有效时间段的起始点时间偏移(单位: ms)
end_time Int 有效时间段的结束点时间偏移(单位: ms)
channel_id Int 有效时间段的作用音轨序号(从0开始)

数加验证字符串:

数加验证字符串以json格式放置于Https headers内。数加验证过程可参见“官方服务API校验规范”。注意:语音使用的数加验证与官方略有差异,鉴权字段不需要加入urlpath。详细见下文「完整示例」-「语音服务数加鉴权代码」。

  1. {
  2. "Content-Type": "application/json",
  3. "Accept": "application/json",
  4. "date": gmtTime,
  5. "Authorization": authorization
  6. }

输出参数

  1. {
  2. "id": "***"
  3. }

参数说明:

  • 返回HTTP状态: 201 Created
  • 返回参数JSON字符串:
属性 值类型 是否必须 说明
id String 识别任务ID

结果查询接口

在提交完识别请求后,调用方将可以按照如下接口轮询结果。

时间限制

识别后72小时内可以查询识别结果,过期则查不到。

URL说明

协议 URL 方法 参数
HTTPS https://nlsapi.aliyun.com/transcriptions/< id > GET

输入参数

用户通过id调用“结果查询”接口可获取识别结果,在接口调用过程时,需要设置一定的查询时间间隔,可参考完整示例

  • 请求参数:

id为识别任务ID。

  • 数加验证字符串:

数加验证字符串以json格式放置于Https headers内。数加验证过程可参见“官方服务API校验规范”。注意:语音使用的数加验证与官方略有差异,鉴权字段不需要加入urlpath。详细见下文「完整示例」-「语音服务数加鉴权代码」。

  1. {
  2. "Content-Type": "application/json",
  3. "Accept": "application/json",
  4. "date": gmtTime,
  5. "Authorization": authorization
  6. }

输出参数

正常返回

  1. {
  2. "id": "***",
  3. "status": "SUCCEED",
  4. "result": [
  5. {
  6. "channel_id": 0,
  7. "begin_time": 700,
  8. "end_time": 3120,
  9. "emotion_value":7,
  10. "silence_duration":1,
  11. "speech_rate":304,
  12. "text": "你好,很高兴为您服务"
  13. }
  14. ......
  15. ]
  16. }

正在识别

  1. {
  2. "id":"2e2bf1fbe4d34dab8b9e36488d0fa1e2",
  3. "status":"RUNNING"
  4. }

异常返回

  1. {
  2. "error_message": "UNSUPPORTED_SAMPLE_RATE",
  3. "id": "***",
  4. "status": "FAILED",
  5. "status_code": 400
  6. }

参数说明:

  • 返回HTTP状态: 200 OK
  • 返回参数JSON字符串,回调POST的JSON字符串同结果相同:
属性 值类型 是否必须 说明
id String 转写任务ID
status String 该转写任务的当前状态, 三种取值:RUNNING, SUCCEED, FAILED
status_code Int 错误码。当status为FAILED时存在。
error_message String 对错误状态的进一步描述。当status为FAILED时存在
result List< SentenceResult > 转写的结果数据。当status为SUCCEED时存在
biz_duration Long 转写的音频文件总时长(ms)。当status为SUCCEED时存在
  • 错误码status_code描述:
状态码 说明
200 成功
400 无效的请求
401 需要鉴权信息
403 鉴权失败
404 不存在
408 请求超时
422 请求内容有误
429 超出最大并发
500 服务器内部出错
503 服务不可用
  • 单句结果SentenceResult描述:
属性 值类型 是否必须 说明
channel_id Int 该句所属音轨ID
begin_time Int 该句的起始时间偏移(单位: ms)
end_time Int 该句的结束时间偏移(单位: ms)
text String 该句的识别文本结果
emotion_value Int 情绪能量值1-10
silence_duration Int 提供静音时长(单位: s)
speech_rate String 提供一分钟语速的数值
  • 异常返回

不支持的采样率.采样率错误

{“error_message”:”UNSUPPORTED_SAMPLE_RATE”,”id”:”xxxxx”,”status”:”FAILED”,”status_code”:400}

文件下载失败

{“error_message”:”FILE_DOWNLOAD_FAILED”,”id”:”xxxxx”,”status”:”FAILED”,”status_code”:400}

完整示例

Java Demo 下载地址

  • 语音文件识别服务demo入口
  1. package com.alibaba.idst.nls;
  2. import com.alibaba.fastjson.JSON;
  3. import com.alibaba.idst.nls.response.HttpResponse;
  4. import com.alibaba.idst.nls.utils.*;
  5. /**
  6. * Created by shaosongsong on 16/5/18.
  7. */
  8. public class TranscriptionDemo {
  9. /**
  10. * 服务url
  11. * */
  12. private static String url = "https://nlsapi.aliyun.com/transcriptions";
  13. private static RequestBody body = new RequestBody();
  14. private static HttpUtil request = new HttpUtil();
  15. public static void main(String[] args) throws InterruptedException {
  16. String ak_id = ""; //数加管控台获得的accessId
  17. String ak_secret = ""; // 数加管控台获得的accessSecret
  18. body.setApp_key("nls-service-telephone8khz"); //简介页面给出的Appkey
  19. body.setFile_link("http://aliyun-nls.oss.aliyuncs.com/asr/fileASR/examples/nls-sample.wav");//离线文件识别的文件url,推荐使用oss存储文件。链接大小限制为128MB
  20. /*热词接口*/
  21. //使用热词需要指定Vocabulary_id字段,如何设置热词参考文档:[热词设置](~~49179~~)
  22. //body.setVocabulary_id("vocab_id");
  23. /*热词接口*/
  24. /* 获取完整识别结果,无需设置本参数!*/
  25. //valid_times是获取语音的指定时间段的识别内容,如果不需要,则不用填写
  26. //body.addValid_time(100,2000,0); //validtime 可选字段 设置的是语音文件中希望识别的内容,begintime,endtime以及channel
  27. //body.addValid_time(2000,10000,1); //validtime 默认不设置。可选字段 设置的是语音文件中希望识别的内容,begintime,endtime以及channel
  28. /* 获取完整识别结果,无需设置本参数!*/
  29. System.out.println("Recognize begin!");
  30. /*
  31. * 发送录音转写请求
  32. * **/
  33. String bodyString;
  34. bodyString = JSON.toJSONString(body,true);
  35. System.out.println("bodyString is:" + bodyString);
  36. HttpResponse httpResponse = request.sendPost(url,bodyString,ak_id,ak_secret);
  37. if (httpResponse.getStatus()==200) {
  38. System.out.println("post response is:" + httpResponse.getResult());
  39. }else {
  40. System.out.println("error msg: "+httpResponse.getMessage());
  41. }
  42. /*
  43. * 通过TaskId获取识别结果
  44. * **/
  45. if (httpResponse.getStatus() == 200) {
  46. String TaskId = JSON.parseObject(httpResponse.getResult()).getString("id");
  47. String status = "RUNNING";
  48. HttpResponse getResponse = null;
  49. while (status.equals("RUNNING")) {
  50. Thread.sleep(10000);
  51. getResponse = request.sendGet(url, TaskId, ak_id, ak_secret);
  52. if (getResponse.getStatus() == 200) {
  53. status = JSON.parseObject(getResponse.getResult()).getString("status");
  54. System.out.println("get response is:" + getResponse.getResult());
  55. }else {
  56. System.out.println("error msg: "+getResponse.getMessage());
  57. break;
  58. }
  59. }
  60. System.out.println("Recognize over!");
  61. }
  62. }
  63. }
  • RequestBody类,语音识别服务请求中数加鉴权所需的body参数,也是HTTPS请求的data部分。
  1. package com.alibaba.idst.nls.utils;
  2. import java.util.*;
  3. public class RequestBody {
  4. private String app_key = null; //appkey 应用的key
  5. private String oss_link = null; //语音文件存储地址
  6. private List<validTime> valid_times =null; //有效时间段ValidTime描述,可选字段
  7. private boolean auto_split = false;
  8. public class validTime{
  9. private int begin_time;
  10. private int end_time;
  11. private int channel_id;
  12. public int getBegin_time() {
  13. return begin_time;
  14. }
  15. public void setBegin_time(int begin_time) {
  16. this.begin_time = begin_time;
  17. }
  18. public int getEnd_time() {
  19. return end_time;
  20. }
  21. public void setEnd_time(int end_time) {
  22. this.end_time = end_time;
  23. }
  24. public int getChannel_id() {
  25. return channel_id;
  26. }
  27. public void setChannel_id(int channel_id) {
  28. this.channel_id = channel_id;
  29. }
  30. }
  31. public void setAutoSplit(boolean auto_split){
  32. auto_split = auto_split;
  33. }
  34. public void setApp_key(String appKey){
  35. app_key = appKey;
  36. }
  37. public void setOss_link(String fileLine){
  38. oss_link = fileLine;
  39. }
  40. public void addValid_time(int beginTime,int endTime,int channelId){
  41. if(valid_times == null){
  42. valid_times = new ArrayList<validTime>();
  43. }
  44. validTime valid_time = new validTime();
  45. valid_time.setBegin_time(beginTime);
  46. valid_time.setEnd_time(endTime);
  47. valid_time.setChannel_id(channelId);
  48. valid_times.add(valid_time);
  49. }
  50. public List<validTime> getValid_times() {
  51. return valid_times;
  52. }
  53. public String getOss_link() {
  54. return oss_link;
  55. }
  56. public String getApp_key() {
  57. return app_key;
  58. }
  59. }
  • 结果类。处理Http请求的返回结果。
  1. package com.alibaba.idst.nls.response;
  2. /**
  3. * Created by songsong.sss on 2017/1/18.
  4. */
  5. public class HttpResponse {
  6. private int status;
  7. private String result;
  8. private String message;
  9. public int getStatus() {
  10. return status;
  11. }
  12. public void setStatus(int status) {
  13. this.status = status;
  14. }
  15. public String getResult() {
  16. return result;
  17. }
  18. public void setResult(String result) {
  19. this.result = result;
  20. }
  21. public String getMessage() {
  22. return message;
  23. }
  24. public void setMessage(String message) {
  25. this.message = message;
  26. }
  27. }
  • 语音服务数加鉴权代码。HttpUtil类,实现数加鉴权过程,并将其作为HTTPS请求的header部分。实现POST方式的请求识别方法和GET方式的结果查询方法。
  1. package com.alibaba.idst.nls.utils;
  2. /**
  3. * Created by songsong.sss on 16/5/23.
  4. */
  5. import java.io.*;
  6. import java.net.HttpURLConnection;
  7. import java.net.URL;
  8. import java.security.MessageDigest;
  9. import java.text.SimpleDateFormat;
  10. import java.util.Date;
  11. import java.util.Locale;
  12. import javax.crypto.spec.SecretKeySpec;
  13. import com.alibaba.idst.nls.response.HttpResponse;
  14. import sun.misc.BASE64Encoder;
  15. import javax.crypto.Mac;
  16. import org.slf4j.Logger;
  17. import org.slf4j.LoggerFactory;
  18. @SuppressWarnings("restriction")
  19. public class HttpUtil {
  20. static Logger logger = LoggerFactory.getLogger(HttpUtil.class);
  21. /*
  22. * 计算MD5+BASE64
  23. */
  24. public static String MD5Base64(String s) throws UnsupportedEncodingException {
  25. if (s == null)
  26. return null;
  27. String encodeStr = "";
  28. //string 编码必须为utf-8
  29. byte[] utfBytes = s.getBytes("UTF-8");
  30. MessageDigest mdTemp;
  31. try {
  32. mdTemp = MessageDigest.getInstance("MD5");
  33. mdTemp.update(utfBytes);
  34. byte[] md5Bytes = mdTemp.digest();
  35. BASE64Encoder b64Encoder = new BASE64Encoder();
  36. encodeStr = b64Encoder.encode(md5Bytes);
  37. } catch (Exception e) {
  38. throw new Error("Failed to generate MD5 : " + e.getMessage());
  39. }
  40. return encodeStr;
  41. }
  42. /*
  43. * 计算 HMAC-SHA1
  44. */
  45. public static String HMACSha1(String data, String key) {
  46. String result;
  47. try {
  48. SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
  49. Mac mac = Mac.getInstance("HmacSHA1");
  50. mac.init(signingKey);
  51. byte[] rawHmac = mac.doFinal(data.getBytes());
  52. result = (new BASE64Encoder()).encode(rawHmac);
  53. } catch (Exception e) {
  54. throw new Error("Failed to generate HMAC : " + e.getMessage());
  55. }
  56. return result;
  57. }
  58. /*
  59. * 等同于javaScript中的 new Date().toUTCString();
  60. */
  61. public static String toGMTString(Date date) {
  62. SimpleDateFormat df = new SimpleDateFormat("E, dd MMM yyyy HH:mm:ss z", Locale.UK);
  63. df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));
  64. return df.format(date);
  65. }
  66. /*
  67. * 发送POST请求
  68. */
  69. public static HttpResponse sendPost(String url, String body, String ak_id, String ak_secret) {
  70. PrintWriter out = null;
  71. BufferedReader in = null;
  72. String result = "";
  73. HttpResponse response = new HttpResponse();
  74. try {
  75. URL realUrl = new URL(url);
  76. /*
  77. * http header 参数
  78. */
  79. String method = "POST";
  80. String accept = "application/json";
  81. String content_type = "application/json";
  82. String date = toGMTString(new Date());
  83. // 1.对body做MD5+BASE64加密
  84. String bodyMd5 = MD5Base64(body);
  85. String stringToSign = method + "\n" + accept + "\n" + bodyMd5 + "\n" + content_type + "\n" + date ;
  86. // 2.计算 HMAC-SHA1
  87. String signature = HMACSha1(stringToSign, ak_secret);
  88. // 3.得到 authorization header
  89. String authHeader = "Dataplus " + ak_id + ":" + signature;
  90. // 打开和URL之间的连接
  91. HttpURLConnection conn = (HttpURLConnection) realUrl.openConnection();
  92. // 设置通用的请求属性
  93. conn.setRequestProperty("accept", accept);
  94. conn.setRequestProperty("content-type", content_type);
  95. conn.setRequestProperty("date", date);
  96. conn.setRequestProperty("Authorization", authHeader);
  97. // 发送POST请求必须设置如下两行
  98. conn.setDoOutput(true);
  99. conn.setDoInput(true);
  100. // 获取URLConnection对象对应的输出流
  101. out = new PrintWriter(conn.getOutputStream());
  102. // 发送请求参数
  103. out.print(body);
  104. // flush输出流的缓冲
  105. out.flush();
  106. response.setStatus(conn.getResponseCode());
  107. // 定义BufferedReader输入流来读取URL的响应
  108. if (response.getStatus() ==200){
  109. in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
  110. }else {
  111. in = new BufferedReader(new InputStreamReader(conn.getErrorStream()));
  112. }
  113. String line;
  114. while ((line = in.readLine()) != null) {
  115. result += line;
  116. }
  117. if (response.getStatus() == 200){
  118. response.setResult(result);
  119. response.setMessage("OK");
  120. }else {
  121. response.setMessage(result);
  122. }
  123. System.out.println("post response status code: ["+response.getStatus()+"], response message : ["+response.getMessage()+"] ,result :["+response.getResult()+"]");
  124. } catch (Exception e) {
  125. System.out.println("发送 POST 请求出现异常!" + e);
  126. e.printStackTrace();
  127. }
  128. // 使用finally块来关闭输出流、输入流
  129. finally {
  130. try {
  131. if (out != null) {
  132. out.close();
  133. }
  134. if (in != null) {
  135. in.close();
  136. }
  137. } catch (IOException ex) {
  138. ex.printStackTrace();
  139. }
  140. }
  141. return response;
  142. }
  143. /*
  144. * GET请求
  145. */
  146. public static HttpResponse sendGet(String url, String task_id,String ak_id, String ak_secret) {
  147. String result = "";
  148. BufferedReader in = null;
  149. HttpResponse response = new HttpResponse();
  150. try {
  151. URL realUrl = new URL(url+"/"+task_id);
  152. /*
  153. * http header 参数
  154. */
  155. String method = "GET";
  156. String accept = "application/json";
  157. String content_type = "application/json";
  158. String path = realUrl.getFile();
  159. String date = toGMTString(new Date());
  160. // 1.对body做MD5+BASE64加密
  161. //String bodyMd5 = MD5Base64("");
  162. String stringToSign = method + "\n" + accept + "\n" + "" + "\n" + content_type + "\n" + date;
  163. // 2.计算 HMAC-SHA1
  164. String signature = HMACSha1(stringToSign, ak_secret);
  165. // 3.得到 authorization header
  166. String authHeader = "Dataplus " + ak_id + ":" + signature;
  167. // 打开和URL之间的连接
  168. HttpURLConnection connection = (HttpURLConnection) realUrl.openConnection();
  169. // 设置通用的请求属性
  170. connection.setRequestProperty("accept", accept);
  171. connection.setRequestProperty("content-type", content_type);
  172. connection.setRequestProperty("date", date);
  173. connection.setRequestProperty("Authorization", authHeader);
  174. // 建立实际的连接
  175. connection.connect();
  176. // 定义 BufferedReader输入流来读取URL的响应
  177. in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
  178. response.setStatus(connection.getResponseCode());
  179. // 定义BufferedReader输入流来读取URL的响应
  180. if (response.getStatus() ==200){
  181. in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
  182. }else {
  183. in = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
  184. }
  185. String line;
  186. while ((line = in.readLine()) != null) {
  187. result += line;
  188. }
  189. if (response.getStatus() == 200){
  190. response.setResult(result);
  191. response.setMessage("OK");
  192. }else {
  193. response.setMessage(result);
  194. }
  195. System.out.println("get response status code: ["+response.getStatus()+"], response message : ["+response.getMessage()+"] ,result :["+response.getResult()+"]");
  196. } catch (Exception e) {
  197. System.out.println("发送GET请求出现异常!" + e);
  198. e.printStackTrace();
  199. }
  200. // 使用finally块来关闭输入流
  201. finally {
  202. try {
  203. if (in != null) {
  204. in.close();
  205. }
  206. } catch (Exception e) {
  207. e.printStackTrace();
  208. }
  209. }
  210. return response;
  211. }
  212. }
本文导读目录
本文导读目录
以上内容是否对您有帮助?