The Flash Recognizer for short audio files lets you upload a short audio clip using an HTTPS POST request and synchronously receive the transcription result. For example, a 30-minute audio file can be transcribed in 10 seconds. This feature meets the real-time requirements for scenarios such as generating audio or video captions and performing near-real-time quality inspections.
Billing and concurrency limits
The Flash Recognizer for short audio files is available only in the commercial version and does not support a free trial. For more information, see Trial and commercial versions. To use this feature, you must activate the commercial version. For more information, see Upgrade from the trial version to the commercial version.
For more information about billing, see Billing methods.
For more information about concurrency limits, see Concurrency and QPS.
Features
You must strictly follow these requirements during development. Otherwise, the recognition may fail and return an empty result.
Audio and video formats: This feature supports audio and video files encoded in MP4, AAC, MP3, OPUS, and WAV formats.
Limits: Audio files must be smaller than 100 MB and no longer than 2 hours. For files longer than 2 hours, use the standard version of Audio File Transcription.
Model types: 8000 (telephony) and 16000 (non-telephony).
NoteThe server automatically adjusts the sample rate of audio that does not meet the requirements based on the sample rate in the request parameters.
Configurable results: You can configure whether to convert Chinese numerals to Arabic numerals in the output. You can also process only the first channel of a multi-channel audio file.
Console configuration: You can configure hotwords and custom language models for your project in the console.
The following language and dialect models are currently supported:
You cannot specify language and dialect models in your code. Instead, you must go to the All Projects page in the Intelligent Speech Interaction console and select the Configure Project Features operation for the relevant project to select the model. For more information, see Manage projects.
Prerequisites
You have obtained a project AppKey. For more information, see Create a project.
You have obtained an access token. For more information, see Overview of obtaining a token.
Interaction flow
The client sends an HTTPS POST request with audio data to the server. The server returns an HTTPS response with the recognition result.
For all server responses except for the audio stream, the header of the response message contains the task_id parameter. This parameter is the unique identifier for the request.
Endpoints
Access type | Description | URL | Host |
Public access | All servers can use the public access URL. |
|
|
Alibaba Cloud ECS private network access | If you use Alibaba Cloud ECS instances in the China (Shanghai), China (Beijing), or China (Shenzhen) regions, you can use the private network access URL. ECS instances in the classic network cannot access AnyTunnel, which means they cannot access the Voice Service over the private network. If you want to use AnyTunnel, create a VPC and access the service from within the VPC. Note
|
|
|
The following examples use the public access URL. If you are using an Alibaba Cloud ECS instance in Shanghai and need to access the service over the private network, you must use the HTTP protocol and replace the public access URL and Host with their private network equivalents.
Audio input
Upload a binary audio stream
The following is an example of an HTTPS request message.
POST /stream/v1/FlashRecognizer?appkey=23f5****&token=450372e4279bcc2b3c793****&format=wav&sample_rate=16000 HTT
Content-type: application/octet-stream
Content-Length: 94616
Host: nls-gateway-cn-shanghai.aliyuncs.com
[audio data]A complete RESTful API request for the Flash Recognizer includes the following components: an HTTPS request line, HTTPS request headers, and an HTTPS request body.
HTTPS request line
The HTTPS request line specifies the URL and request parameters. The following is the complete request URL that consists of the URL and request parameters:
https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=Yu1******uncS&format=wav&sample_rate=16000&vocabulary_id=a17******d6b&token=1234*****URL
Protocol
URL
Method
HTTP/1.1
nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer
POST
Request parameters
Parameter
Type
Required
Description
appkey
String
Yes
The AppKey of your application.
format
String
Yes
The audio encoding format. Supported formats: MP4, AAC, MP3, OPUS, and WAV.
token
String
Yes
The authentication token.
sample_rate
Integer
No
The sample rate of the speech recognition model. If the uploaded audio does not match this value, it is automatically upsampled or downsampled to 8000 or 16000. Valid values: 16000 (non-telephony) and 8000 (telephony). Default: 16000.
vocabulary_id
String
No
The ID of the hotword vocabulary to add. Default: No hotword vocabulary is added.
customization_id
String
No
The ID of the custom language model to add. Default: No custom model is added.
enable_inverse_text_normalization
Boolean
No
Specifies whether to enable Inverse Text Normalization (ITN) to convert Chinese numerals to Arabic numerals. If you set this parameter to true, Chinese numerals are converted to Arabic numerals in the output. Default: false.
enable_word_level_result
Boolean
No
Specifies whether to return word-level information. Valid values: true and false. Default: false.
enable_timestamp_alignment
Boolean
No
Specifies whether to enable the timestamp calibration feature. Valid values: true and false. Default: false.
first_channel_only
Boolean
No
Specifies whether to recognize only the first channel. Valid values: true and false. (You can enable this parameter if the recognition result is duplicated.)
Default (empty): Processes two channels for 8k audio and one channel for 16k audio.
false: Processes two channels for both 8k and 16k audio.
true: Processes one channel for both 8k and 16k audio.
NoteMulti-channel audio incurs additional charges. For example, a two-channel audio file is billed at twice the rate.
speech_noise_threshold
Float
No
The noise threshold parameter. Valid values: -1 to 1.
The closer the value is to -1, the more likely noise is to be classified as speech.
The closer the value is to 1, the more likely speech is to be classified as noise.
ImportantThis is an advanced parameter. Adjust it with caution and perform thorough testing.
special_word_filter
String (JSON format)
No
The sensitive word filtering feature. You can enable or disable it and customize the sensitive words. This parameter supports the following actions:
No processing (default, displays the original text), Filter, and Replace with *.
For specific call instructions, see the custom word filtering example below.
NoteIf this feature is enabled but no sensitive words are configured, the default word list is filtered: Sensitive word list.
sentence_max_length
Integer
No
The maximum number of characters to display per sentence. Valid values: 4 to 50. This feature is disabled by default. If enabled without specifying a number, long sentences are segmented. This parameter can be used in caption generation scenarios to control the maximum number of characters per line.
The following is a custom word filtering example:
// Take real-time transcription as an example, JSONObject root = new JSONObject(); root.put("system_reserved_filter", true); // Replace the following words with an empty string JSONObject root1 = new JSONObject(); JSONArray array1 = new JSONArray(); array1.add("start"); array1.add("happen"); root1.put("word_list", array1); // Replace the following words with * JSONObject root2 = new JSONObject(); JSONArray array2 = new JSONArray(); array2.add("test"); root2.put("word_list", array2); // You can set all or some of them root.put("filter_with_empty", root1); root.put("filter_with_signed", root2); transcriber.addCustomedParam("special_word_filter", root);
HTTPS request headers
HTTPS request headers consist of key-value pairs. Each pair is on a separate line, with the key and value separated by a colon (:). Set the following headers:
Name
Type
Required
Description
Content-type
String
Yes
Set to "application/octet-stream" to indicate that the data in the HTTPS request body is a binary stream.
Content-Length
long
Yes
The length of the request data in the HTTPS request body, which is the length of the audio file.
Host
String
Yes
Set to "nls-gateway-cn-shanghai.aliyuncs.com", which is the domain name of the server for the HTTPS request.
HTTPS request body
The HTTPS request body contains binary audio data. Therefore, the
Content-Typein the HTTPS request header must be set toapplication/octet-stream.
Use an audio file URL
If you want to recognize an audio file that is not stored locally, you can make a request using an audio URL. This method does not require you to upload the audio file. The following is an example of an HTTPS request message:
POST /stream/v1/FlashRecognizer?appkey=23f5****&token=450372e4279bcc2b3c793****&format=wav&sample_rate=16000&audio_address=https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wa
HTTP Content-type: application/text
Host: nls-gateway-cn-shanghai.aliyuncs.comA complete RESTful API request for the Flash Recognizer includes the following components: an HTTPS request line and HTTPS request headers.
HTTPS request line
The HTTPS request line specifies the URL and request parameters. The following is the complete request URL that consists of the URL and request parameters:
https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=Yu1******uncS&format=wav&sample_rate=16000&vocabulary_id=a17******d6b&token=1234*****URL
Protocol
URL
Method
HTTP/1.1
nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer
POST
Request parameters
Parameter
Type
Required
Description
appkey
String
Yes
The AppKey of your application.
format
String
Yes
The audio encoding format. Supported formats: MP4, WAV, OPUS, AAC, and MP3.
token
String
Yes
The authentication token.
sample_rate
Integer
No
The sample rate of the speech recognition model. If the uploaded audio does not match this value, it is automatically upsampled or downsampled to 8000 or 16000. Valid values: 16000 (non-telephony) and 8000 (telephony). Default: 16000.
vocabulary_id
String
No
The ID of the hotword vocabulary to add. Default: No hotword vocabulary is added.
customization_id
String
No
The ID of the custom language model to add. Default: No custom model is added.
enable_inverse_text_normalization
Boolean
No
Specifies whether to enable Inverse Text Normalization (ITN) to convert Chinese numerals to Arabic numerals. If you set this parameter to true, Chinese numerals are converted to Arabic numerals in the output. Default: false.
enable_word_level_result
Boolean
No
Specifies whether to return word-level information. Valid values: true and false. Default: false.
enable_timestamp_alignment
Boolean
No
Specifies whether to enable the timestamp calibration feature. Valid values: true and false. Default: false.
first_channel_only
Boolean
No
Specifies whether to recognize only the first channel. Valid values: true and false. (You can enable this parameter if the recognition result is duplicated.)
Default (empty): Processes two channels for 8k audio and one channel for 16k audio.
false: Processes two channels for both 8k and 16k audio.
true: Processes one channel for both 8k and 16k audio.
NoteMulti-channel audio incurs additional charges. For example, a two-channel audio file is billed at twice the rate.
speech_noise_threshold
Float
No
The noise threshold parameter. Valid values: -1 to 1.
The closer the value is to -1, the more likely noise is to be classified as speech.
The closer the value is to 1, the more likely speech is to be classified as noise.
ImportantThis is an advanced parameter. Adjust it with caution and perform thorough testing.
audio_address
String
Yes
Required when using an audio file URL. The address where the audio file is stored. We recommend using Alibaba Cloud OSS.
HTTPS request headers
HTTPS request headers consist of key-value pairs. Each pair is on a separate line, with the key and value separated by a colon (:). Set the following headers:
Name
Type
Required
Description
Content-type
String
Yes
Set to "application/text".
Host
String
Yes
Set to "nls-gateway-cn-shanghai.aliyuncs.com", which is the domain name of the server for the HTTPS request.
Response
After you send the HTTPS request to upload the audio, the server returns a response. The recognition result is included in the response as a JSON string.
Successful response
{ "task_id":"a819f959441b49****", "status":20000000, "message":"SUCCESS", "flash_result":{ "duration":22, "sentences":[ { "text":"Hello,", "words":[ { "text":"Hello", "begin_time":"1010", "end_time":"1520", "punc":"," } ], "begin_time":1010, "end_time":1520, "channel_id":1 }, { "text":"Hey,", "words":[ { "text":"Hey", "begin_time":"3540", "end_time":"3570", "punc":"," } ], "begin_time":3540, "end_time":3570, "channel_id":1 }, { "text":"So what time is five fifty now,", "words":[ { "text":"So", "begin_time":"8810", "end_time":"8840", "punc":"" }, { "text":"five", "begin_time":"12750", "end_time":"13200", "punc":"" }, { "text":"fifty", "begin_time":"13200", "end_time":"13890", "punc":"" }, { "text":"now", "begin_time":"14330", "end_time":"14600", "punc":"" }, { "text":"is", "begin_time":"14600", "end_time":"14720", "punc":"" }, { "text":"what", "begin_time":"14720", "end_time":"14960", "punc":"" }, { "text":"time", "begin_time":"19570", "end_time":"21220", "punc":"" }, { "text":"now", "begin_time":"21220", "end_time":"22330", "punc":"" } ], "begin_time":8810, "end_time":22330, "channel_id":1 } ] } }The following table describes the response fields.
Parameter
Type
Description
task_id
String
A 32-bit task ID. Record this value for troubleshooting.
status
Integer
The service status code.
message
String
A description of the service status.
The following table describes the parameters of the flash_result object.
Parameter
Type
Description
duration
Integer
The audio duration in milliseconds.
latency
Integer
The server-side processing time in milliseconds.
sentences.text
String
The sentence-level recognition result.
sentences.begin_time
Integer
The start time of the sentence in milliseconds.
sentences.end_time
Integer
The end time of the sentence in milliseconds.
sentences.channel_id
Integer
For multi-channel audio files, the recognition results are returned separately for each channel. The channel ID starts from 0.
sentences.words.text
String
The word information contained in the current sentence.
sentences.words.punc
String
The punctuation at the end of the current word. It is empty if there is no punctuation.
sentences.words.begin_time
Integer
The start time of the current word in milliseconds.
sentences.words.end_time
Integer
The end time of the current word in milliseconds.
Failed response
The following is an example of an invalid authentication token:
{ "task_id": "8bae3613dfc54ebfa811a17d8a7a****", "result": "", "status": 40000001, "message": "Gateway:ACCESS_DENIED:The token 'c0c1e860f3*******de8091c68a' is invalid!" }
Service status codes
General-purpose error codes
Status code | Status message | Cause | Solution |
40000000 | The default client error code. This code corresponds to multiple error messages. | Invalid parameters or call logic was used. | Compare your code with the sample code in the official documentation to test and verify it. |
40000001 | The token 'xxx' has expired. The token 'xxx' is invalid | Invalid parameters or call logic was used. This is a general-purpose client error code that usually indicates an incorrect token, such as an expired or invalid token. | Compare your code with the sample code in the official documentation to test and verify it. |
40000002 | Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'! | The message is invalid or incorrect. | Compare your code with the sample code in the official documentation to test and verify it. |
40000003 | PARAMETER_INVALID Failed to decode url params | The parameters passed by the user are incorrect. This error is common for RESTful API calls. | Compare your code with the sample code in the official documentation to test and verify it. |
40000005 | Gateway:TOO_MANY_REQUESTS:Too many requests! | Too many concurrent requests. | If you are using the Free Edition, you can upgrade to a commercial version to increase the concurrency. If you are already using a commercial version, you can purchase a concurrency resource plan to increase your concurrency quota. |
40000009 | Invalid wav header! | The message header is invalid. | If you send a WAV audio file and set the |
40000009 | Too large wav header! | The WAV header of the transmitted audio is invalid. | You can send the audio stream in a format such as PCM or OPUS. If you use the WAV format, make sure that the WAV header of the audio file contains the correct data length. |
40000010 | Gateway:FREE_TRIAL_EXPIRED:The free trial has expired! | The trial period has ended, and the commercial version is not activated or your account has an overdue payment. | You can log on to the console to check the service activation status and your account balance. |
40010001 | Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal | The operation or parameter is not supported. | Check whether the parameters passed in the call are consistent with the requirements in the official documentation. You can compare them with the error message to identify and set the correct parameters. For example, if you are using a curl command to make a RESTful API request, check whether the URL you constructed is valid. |
40010003 | Gateway:DIRECTIVE_INVALID:[xxx] | A general-purpose client-side error code. | This error indicates that the client passed an incorrect parameter or instruction. Detailed error messages are available for different operations. You can refer to the corresponding documentation to set the parameters correctly. |
40010004 | Gateway:CLIENT_DISCONNECT:Client disconnected before task finished! | The client actively terminated the connection before the request was processed. | None. Alternatively, you can close the connection after the server responds. |
40010005 | Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping! | The client sent a message instruction that is not currently supported. | Compare your code with the sample code in the official documentation to test and verify it. |
40020105 | Meta:APPKEY_NOT_EXIST:Appkey not exist! | A non-existent Appkey was used. | Confirm whether a non-existent Appkey was used. You can log on to the console and view the project configuration to find the Appkey. |
40020106 | Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch! | The Appkey and token passed in the call were not created by the same Alibaba Cloud account UID. This causes a mismatch. | Check whether you are using resources from two different accounts. Do not use an Appkey from Account A with a token generated from Account B. |
403 | Forbidden | The token is invalid. For example, the token does not exist or has expired. | Set a valid token. Tokens have an expiration period. You must obtain a new token before the current one expires. |
41000003 | MetaInfo doesn't have end point info | Failed to retrieve the routing information for this Appkey. | Check whether you are using resources from two different accounts. Do not use an Appkey from Account A with a token generated from Account B. |
41010101 | UNSUPPORTED_SAMPLE_RATE | The sample rate is not supported. | Real-time speech recognition currently supports only audio with a sample rate of 8000 Hz or 16000 Hz. |
41040201 | Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously! | Failed to retrieve data from the client due to a timeout. | When you call real-time speech recognition, the client must send data at a real-time rate and close the connection promptly after the data is sent. |
50000000 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
50000001 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
52010001 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
Flash audio file recognition error codes
Status code | Status message | Cause | Solution |
40000004 | Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time | After a task is submitted, the server returns this error message if no task result is returned for more than 50 seconds. | If a task returns this error code, retry submitting it. We recommend retrying a maximum of two times. |
40000005 | - | Too many requests. | Check whether the number of concurrent connections or requests per second has been exceeded. |
40270001 | - | The audio format is not supported. | The requested audio format is not in the supported list. |
40270002 | NO_VALID_AUDIO_ERROR | The audio is invalid. | No valid text was recognized from the audio. |
40270003 | - | Audio decoding error. | An error occurred while decoding the audio according to the requested format. |
40270004 | - | No valid audio stream. | No valid audio stream was extracted from the multi-channel audio. |
40270006 | - | File download failed. | Check whether the file link is valid. |
Quick test
The example audio is a WAV file that uses the general-purpose model. If you use a different audio file, you must specify the corresponding encoding format and sample rate, and set the corresponding model in the console.
Use the following cURL command to test the RESTful API for the Flash Recognizer.
curl -X POST 'https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=${appkey}&token=${token}&format=wav&sample_rate=16000' --data-binary @${audio_file}Example:
curl -X POST 'https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=tt43P2u****&token=4a036531cfdd****&format=wav&sample_rate=16000' --data-binary @./nls-sample-16k.wav
Java example
The following are the dependency files:
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>3.9.1</version>
</dependency>
<!-- http://mvnrepository.com/artifact/com.alibaba/fastjson -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.83</version>
</dependency>Sending requests and handling responses:
import java.net.URLEncoder;
import java.io.File;
import java.util.HashMap;
public class SpeechFlashRecognizerDemo {
private String appkey;
public SpeechFlashRecognizerDemo(String appkey) {
this.appkey = appkey;
}
public void process(String fileName, String token,String format, int sampleRate) {
/**
* Set up the HTTPS REST POST request.
* 1. Use the HTTPS protocol.
* 2. Speech recognition service domain name: nls-gateway-cn-shanghai.aliyuncs.com
* 3. Speech recognition API request path: /stream/v1/FlashRecognizer
* 4. Set the required request parameters: appkey, token, format, sample_rate
*/
String url = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer";
String request = url;
request = request + "?appkey=" + appkey;
request = request + "&token=" + token;
request = request + "&format=" + format;
request = request + "&sample_rate=" + sampleRate;
System.out.println("Request: " + request);
/**
* Set the HTTPS header fields.
*
* 1. Content-Type: application/octet-stream
*/
HashMap<String, String> headers = new HashMap<String, String>();
/**
* Send the HTTPS POST request and receive the server's response.
*/
long start = System.currentTimeMillis();
String response;
if (new File(fileName).isFile()){
headers.put("Content-Type", "application/octet-stream");
response = HttpUtil.sendPostFile(request, headers, fileName);
}else {
headers.put("Content-Type", "application/text");
response = HttpUtil.sendPostLink(request, headers, fileName);
}
System.out.println("latency = " + (System.currentTimeMillis() - start) + " ms");
if (response != null) {
System.out.println("Response: " + response);
}
else {
System.err.println("Recognition failed!");
}
}
public static void main(String[] args) {
if (args.length < 2) {
System.err.println("SpeechRecognizerRESTfulDemo need params: <token> <app-key>");
System.exit(-1);
}
String token = args[0];
String appkey = args[1];
SpeechFlashRecognizerDemo demo = new SpeechFlashRecognizerDemo(appkey);
//String fileName = SpeechRecognizerRestfulDemo.class.getClassLoader().getResource("./nls-sample-16k.wav").getPath();
// Important: A local file is used here to simulate sending real-time stream data. In actual use, you can collect or receive the audio stream in real time from a source and send it to the ASR server.
String fileName = "https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav";
fileName = URLEncoder.encode(fileName, "UTF-8");
String format = "wav";
int sampleRate = 16000;
demo.process(fileName,token, format, sampleRate);
System.exit(-1);
}
}The following code shows the HttpUtils class:
import okhttp3.*;
import java.io.File;
import java.io.IOException;
import java.net.SocketTimeoutException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.TimeUnit;
public class HttpUtil {
private static String getResponseWithTimeout(Request q) {
String ret = null;
OkHttpClient.Builder httpBuilder = new OkHttpClient.Builder();
OkHttpClient client = httpBuilder.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(60, TimeUnit.SECONDS)
.writeTimeout(60, TimeUnit.SECONDS)
.build();
try {
Response s = client.newCall(q).execute();
ret = s.body().string();
s.close();
} catch (SocketTimeoutException e) {
ret = null;
System.err.println("get result timeout");
} catch (IOException e) {
System.err.println("get result error " + e.getMessage());
}
return ret;
}
public static String sendPostFile(String url, HashMap<String, String> headers, String fileName) {
RequestBody body;
File file = new File(fileName);
if (!file.isFile()) {
System.err.println("The filePath is not a file: " + fileName);
return null;
} else {
body = RequestBody.create(MediaType.parse("application/octet-stream"), file);
}
Headers.Builder hb = new Headers.Builder();
if (headers != null && !headers.isEmpty()) {
for (Map.Entry<String, String> entry : headers.entrySet()) {
hb.add(entry.getKey(), entry.getValue());
}
}
Request request = new Request.Builder()
.url(url)
.headers(hb.build())
.post(body)
.build();
return getResponseWithTimeout(request);
}
public static String sendPostData(String url, HashMap<String, String> headers, byte[] data) {
RequestBody body;
if (data.length == 0) {
System.err.println("The send data is empty.");
return null;
} else {
body = RequestBody.create(MediaType.parse("application/octet-stream"), data);
}
Headers.Builder hb = new Headers.Builder();
if (headers != null && !headers.isEmpty()) {
for (Map.Entry<String, String> entry : headers.entrySet()) {
hb.add(entry.getKey(), entry.getValue());
}
}
Request request = new Request.Builder()
.url(url)
.headers(hb.build())
.post(body)
.build();
return getResponseWithTimeout(request);
}
public static String sendPostLink(String url, HashMap<String, String> headers, String link){
RequestBody body;
if (link.isEmpty()) {
System.err.println("The send link is empty.");
return null;
} else {
url=url+"&audio_address="+link;
}
Headers.Builder hb = new Headers.Builder();
if (headers != null && !headers.isEmpty()) {
for (Map.Entry<String, String> entry : headers.entrySet()) {
hb.add(entry.getKey(), entry.getValue());
}
}
Request request = new Request.Builder()
.url(url)
.headers(hb.build())
.build();
return getResponseWithTimeout(request);
}
}C++ example
The C++ example uses the third-party cURL function library to handle HTTPS requests and responses. Download the cURL library and example files.
The directory structure is as follows:
File/Folder | Description |
CMakeLists.txt | The CMakeLists.txt file for the example project. |
demo | The restfulFlashRecognizerDemo.cpp file is the RESTful API example for the Flash Recognizer. |
include | The curl folder is the header file directory for the cURL library. |
lib | Contains the cURL dynamic library, version curl-7.60. Select a version based on your platform:
|
readme.txt | Description. |
release.log | Update history. |
version | Version number. |
build.sh | The example compilation script. |
Compile and run the example:
Assume that the example files are unzipped to the path/to directory. Run the following commands in the Linux terminal to compile and run the program.
With CMake support:
Confirm that CMake 2.4 or later is installed on your local system.
Change the directory:
cd path/to/sdk/lib.Unzip the file:
tar -zxvpf linux.tar.gz.Change the directory:
cd path/to/sdk.Run the compilation script:
./build.sh.Change the directory:
cd path/to/sdk/demo.Run the example program:
./restfulFlashRecognizerDemo <your-token> <your-appkey>.
Without CMake support:
Change the directory:
cd path/to/sdk/lib.Unzip the file:
tar -zxvpf linux.tar.gz.Change the directory:
cd path/to/sdk/demo.Use the g++ command to compile the example program:
g++ -o restfulFlashRecognizerDemo restfulFlashRecognizerDemo.cpp -I path/to/sdk/include -L path/to/sdk/lib/linux -lssl -lcrypto -lcurl -D_GLIBCXX_USE_CXX11_ABI=0.Specify the library path:
export LD_LIBRARY_PATH=path/to/sdk/lib/linux/.Run the example program:
./restfulFlashRecognizerDemo <your-token> <your-appkey>.
#include <iostream>
#include <string>
#include <fstream>
#include <sstream>
#include "curl/curl.h"
using namespace std;
#ifdef _WIN32
string UTF8ToGBK(const string& strUTF8) {
int len = MultiByteToWideChar(CP_UTF8, 0, strUTF8.c_str(), -1, NULL, 0);
unsigned short * wszGBK = new unsigned short[len + 1];
memset(wszGBK, 0, len * 2 + 2);
MultiByteToWideChar(CP_UTF8, 0, (char*)strUTF8.c_str(), -1, (wchar_t*)wszGBK, len);
len = WideCharToMultiByte(CP_ACP, 0, (wchar_t*)wszGBK, -1, NULL, 0, NULL, NULL);
char *szGBK = new char[len + 1];
memset(szGBK, 0, len + 1);
WideCharToMultiByte(CP_ACP, 0, (wchar_t*)wszGBK, -1, szGBK, len, NULL, NULL);
string strTemp(szGBK);
delete[] szGBK;
delete[] wszGBK;
return strTemp;
}
#endif
/**
* The callback function for the HTTPS RESTful API request response.
* The recognition result is a JSON-formatted string.
*/
size_t responseCallback(void* ptr, size_t size, size_t nmemb, void* userData) {
string* srResult = (string*)userData;
size_t len = size * nmemb;
char *pBuf = (char*)ptr;
string response = string(pBuf, pBuf + len);
#ifdef _WIN32
response = UTF8ToGBK(response);
#endif
*srResult += response;
cout << "current result: " << response << endl;
cout << "total result: " << *srResult << endl;
return len;
}
int sendAsrRequest(const char* request, const char* token, const char* fileName, string* srResult) {
CURL* curl = NULL;
CURLcode res;
/**
* Read the audio file.
*/
ifstream fs;
fs.open(fileName, ios::out | ios::binary);
if (!fs.is_open()) {
cerr << "The audio file is not exist!" << endl;
return -1;
}
stringstream buffer;
buffer << fs.rdbuf();
string audioData(buffer.str());
curl = curl_easy_init();
if (curl == NULL) {
return -1;
}
/**
* Set the HTTPS request line.
*/
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(curl, CURLOPT_URL, request);
/**
* Set the HTTPS request headers.
*/
struct curl_slist* headers = NULL;
// Content-Type
headers = curl_slist_append(headers, "Content-Type:application/octet-stream");
// Content-Length
string content_Length = "Content-Length:";
ostringstream oss;
oss << content_Length << audioData.length();
content_Length = oss.str();
headers = curl_slist_append(headers, content_Length.c_str());
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
/**
* Set the HTTPS request data.
*/
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, audioData.c_str());
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, audioData.length());
/**
* Set the callback function for the HTTPS request response.
*/
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, responseCallback);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, srResult);
/**
* Send the HTTPS request.
*/
res = curl_easy_perform(curl);
// Release resources.
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
if (res != CURLE_OK) {
cerr << "curl_easy_perform failed: " << curl_easy_strerror(res) << endl;
return -1;
}
return 0;
}
int process(const char* request, const char* token, const char* fileName) {
// Initialize once globally.
curl_global_init(CURL_GLOBAL_ALL);
string srResult = "";
int ret = sendAsrRequest(request, token, fileName, &srResult);
curl_global_cleanup();
return ret;
}
int main(int argc, char* argv[]) {
if (argc < 3) {
cerr << "params is not valid. Usage: ./demo your_token your_appkey" << endl;
return -1;
}
string token = argv[1];
string appKey = argv[2];
string url = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer";
string format = "wav";
int sampleRate = 16000;
string fileName = "nls-sample-16k.wav";
/**
* Set the RESTful request parameters.
*/
ostringstream oss;
oss << url;
oss << "?appkey=" << appKey;
oss << "&token=" << token;
oss << "&format=" << format;
oss << "&sample_rate=" << sampleRate;
string request = oss.str();
cout << "request: " << request << endl;
process(request.c_str(), token.c_str(), fileName.c_str());
return 0;
}Python example
For Python 2.x, use the httplib module. For Python 3.x, use the http.client module.
Use RFC 3986 for URL encoding. For Python 2.x, use urllib.quote from the urllib module. For Python 3.x, use urllib.parse.quote_plus from the urllib.parse module.
If you use a private network access URL, you must use the HTTP protocol. You need to change
HTTPSConnectiontoHTTPConnectionin the following function:# For Python 2.x, use httplib # conn = httplib.HTTPConnection(host) # For Python 3.x, use http.client conn = http.client.HTTPConnection(host)
# -*- coding: UTF-8 -*-
# For Python 2.x, import the httplib module
# import httplib
# For Python 3.x, import the http.client module
import http.client
import json
def process(request, audioFile) :
# Read the audio file
with open(audioFile, mode = 'rb') as f:
audioContent = f.read()
host = 'nls-gateway-cn-shanghai.aliyuncs.com'
# Set the HTTP request headers
httpHeaders = {
'Content-Length': len(audioContent)
}
# For Python 2.x, use httplib
# conn = httplib.HTTPSConnection(host)
# For Python 3.x, use http.client
conn = http.client.HTTPSConnection(host)
conn.request(method='POST', url=request, body=audioContent, headers=httpHeaders)
response = conn.getresponse()
print('Response status and response reason:')
print(response.status ,response.reason)
body = response.read()
try:
print('Recognize response is:')
body = json.loads(body)
print(body)
status = body['status']
if status == 20000000 :
result = body['result']
print('Recognize result: ' + result)
else :
print('Recognizer failed!')
except ValueError:
print('The response is not json format string')
conn.close()
appKey = 'Your appkey'
token = 'Your token'
# Service request URL
url = 'https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer'
# Audio file. Download URL: https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav
audioFile = 'nls-sample-16k.wav'
format = 'wav'
sampleRate = 16000
print(type(sampleRate))
enablePunctuationPrediction = True
enableInverseTextNormalization = True
enableVoiceDetection = False
# Set the RESTful request parameters
request = url + '?appkey=' + appKey
request = request + '&token=' + token
request = request + '&format=' + format
request = request + '&sample_rate=' + str(sampleRate)
print('Request: ' + request)
process(request, audioFile)PHP example
The PHP example uses cURL functions, which require PHP 4.0.2 or later with the cURL extension installed.
<?php
function process($token, $request, $audioFile)
{
/**
* Read the audio file.
*/
$audioContent = file_get_contents($audioFile);
if ($audioContent == FALSE) {
print "The audio file is not exist!\n";
return;
}
$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_TIMEOUT, 120);
/**
* Set the HTTP request line.
*/
curl_setopt($curl, CURLOPT_URL, $request);
curl_setopt($curl, CURLOPT_POST,TRUE);
/**
* Set the HTTP request headers.
*/
$contentType = "application/octet-stream";
$contentLength = strlen($audioContent);
$headers = array(
// "X-NLS-Token:" . $token,
"Content-type:" . $contentType,
"Content-Length:" . strval($contentLength)
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
/**
* Set the HTTP request data.
*/
curl_setopt($curl, CURLOPT_POSTFIELDS, $audioContent);
curl_setopt($curl, CURLOPT_NOBODY, FALSE);
/**
* Send the HTTP request.
*/
$returnData = curl_exec($curl);
curl_close($curl);
if ($returnData == FALSE) {
print "curl_exec failed!\n";
return;
}
print $returnData . "\n";
$resultArr = json_decode($returnData, true);
$status = $resultArr["status"];
if ($status == 20000000) {
$result = $resultArr["result"];
print "The audio file recognized result: " . $result . "\n";
}
else {
print "The audio file recognized failed.\n";
}
}
$appkey = "Your appkey";
$token = "Your token";
$url = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer";
//$audioFile = "/path/to/nls-sample-16k.wav";
$audioFile = "./nls-sample-16k.wav";
$format = "wav";
$sampleRate = 16000;
/**
* Set the RESTful request parameters.
*/
$request = $url;
$request = $request . "?appkey=" . $appkey;
$request = $request . "&token=" . $token;
$request = $request . "&format=" . $format;
$request = $request . "&sample_rate=" . strval($sampleRate);
print "Request: " . $request . "\n";
process($token, $request, $audioFile);
?>