Run examples

Methods

For more information about using SDKs, see SDK overview.

Call the short-sentence recognition API with cURL

1. Prepare a mono audio file that is less than 60 seconds long and in WAVE format (Microsoft PCM, 16-bit, mono, 16,000 Hz). You can use our sample audio file.

2. Run the following command.

   curl -X POST -H "X-NLS-Token: d9afc8a07b154e0b86d415226******" "http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr?appkey=TuBrUhcloN******" --data-binary @./nls-sample-16k.wav

   Note

   • In this example, d9afc8a07b154e0b86d415226****** is the token you obtained from the Intelligent Speech Interaction console overview, and TuBrUhcloN****** is the Appkey you obtained after creating a project in the Intelligent Speech Interaction console.

   • If you run this command in a Windows Command Prompt, you can omit the quotation marks around the URL.

   • For more details about the interface, see API reference.

   The command returns the following recognition result.

   {"task_id":"12964b9b46d046ae8f377fd516df****","result":"北京的天气","status":20000000,"message":"SUCCESS"}%

Call the short-sentence recognition API with Postman

1. Download Postman.

2. Prepare a mono audio file that is less than 60 seconds long and in WAVE format (Microsoft PCM, 16-bit, mono, 16,000 Hz). You can use our sample audio file.

3. Send the following POST request in Postman.

   Parameter	Example
   Request URL	http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr
   Params	appkey: TuBrUhcloN*****. Get the Appkey from the Intelligent Speech Interaction console.
   Header	X-NLS-Token: d9afc8a07b154e0b86d415226******. On the Intelligent Speech Interaction console overview page, click Get Temporary AccessToken.
   Body	Binary format. Upload the audio file, for example, nls-sample-16k.wav.

   1. Enter the POST URL and parameters.

      Select the POST method and set the URL to http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr. In Params, add the appkey parameter and set its value to your Appkey.

   2. Enter the headers.

      Add the X-NLS-Token header and set its value to your token. Set Content-Type to application/octet-stream.

   3. Enter the body.

      Select the binary type and upload a test audio file (such as test_8k_45s.wav).

4. Check the response. The result field contains the recognized text.

   A successful request returns a JSON response, where the result field is the recognition result (such as "Weather in Beijing"), the status is 20000000, and the message is SUCCESS.

   For the complete API reference for Short-Sentence Recognition, see API reference.

Call real-time speech recognition using an SDK

1. Download the nls-sdk-java-demo.

2. In your IDE, open the downloaded sample code and set your Appkey and token. Then, right-click and select Run "SpeechTranscriberDemo main()".

   Parameter	Value
   Appkey	Get the Appkey from the Intelligent Speech Interaction console.
   Token	On the Intelligent Speech Interaction console overview page, click Get Temporary AccessToken.
   FilePath	Default: nls-sample-16k.wav. This file, located in the SDK package, simulates real-time data streaming from a local file. Other test audio files must meet the audio format requirements for real-time recognition and be placed in the SDK package directory.

   // 1. Replace with your Appkey and token.
   String appKey = "YOUR_APPKEY";
   String token = "YOUR_TOKEN";
   String filePath = "nls-sample-16k.wav";
   
   // 2. Comment out the following code, which is used for passing parameters from the command line when running a JAR package.
   // if (args.length == 3) {
   //     appKey = args[0];
   //     token = args[1];
   //     filePath = args[2];
   // }

   • 1. To get your Appkey and token, see Start here.

   • 2. Comment out this code block, which allows passing parameters from the command line when running a JAR package.

   The real-time recognition call returns the following result, where the result field contains the recognized text.

   name: SentenceBegin, status: 0
   name: TranscriptionResultChanged, result: 北京
   name: TranscriptionResultChanged, result: 北京的
   name: TranscriptionResultChanged, result: 北京的天气
   name: SentenceEnd, result: 北京的天气。

   For more details about the speech recognition interface, see API reference.

Call audio file transcription with Python

Before calling the interface, you must set your access credentials as environment variables. Use ALIYUN_AK_ID for your AccessKey ID, ALIYUN_AK_SECRET for your AccessKey Secret, and NLS_APP_KEY for your Intelligent Speech Interaction Appkey.

1. Install Python 3 and the Python SDK.

   1. Install Python 3.

   2. Run the following command to install aliyun-python-sdk-core version 2.13.3 using pip (recommended).

      pip install aliyun-python-sdk-core==2.13.3

2. Copy the sample code and fill in the parameters.

   1. Obtain the following parameters.

      Parameter	Value
      AccessKey ID	These are used as a pair. View them in the Access Control console.
      AccessKey Secret
      Appkey	Get the Appkey from the Intelligent Speech Interaction console.
      FileLink	The default value is the demo test audio file. To test other audio files, upload them to OSS. For format requirements, see API reference. If the file in OSS is not public, obtain an access URL first. For more information, see Obtain the URLs of one or more files.

   2. Copy the following sample code and save it as a Python file, such as demo.py. The script reads the credentials that you set as environment variables.

      # -*- coding: utf8 -*-
      import json
      import time
      import os
      from aliyunsdkcore.acs_exception.exceptions import ClientException
      from aliyunsdkcore.acs_exception.exceptions import ServerException
      from aliyunsdkcore.client import AcsClient
      from aliyunsdkcore.request import CommonRequest
      def fileTrans(akId, akSecret, appKey, fileLink) :
          # The region ID. This is a fixed value.
          REGION_ID = "cn-shanghai"
          PRODUCT = "nls-filetrans"
          DOMAIN = "filetrans.cn-shanghai.aliyuncs.com"
          API_VERSION = "2018-08-17"
          POST_REQUEST_ACTION = "SubmitTask"
          GET_REQUEST_ACTION = "GetTaskResult"
          # Request parameters
          KEY_APP_KEY = "appkey"
          KEY_FILE_LINK = "file_link"
          KEY_VERSION = "version"
          KEY_ENABLE_WORDS = "enable_words"
          # Whether to enable intelligent channel splitting
          KEY_AUTO_SPLIT = "auto_split"
          # Response parameters
          KEY_TASK = "Task"
          KEY_TASK_ID = "TaskId"
          KEY_STATUS_TEXT = "StatusText"
          KEY_RESULT = "Result"
          # Status values
          STATUS_SUCCESS = "SUCCESS"
          STATUS_RUNNING = "RUNNING"
          STATUS_QUEUEING = "QUEUEING"
          # Create an AcsClient instance.
          client = AcsClient(akId, akSecret, REGION_ID)
          # Submit the audio file transcription request.
          postRequest = CommonRequest()
          postRequest.set_domain(DOMAIN)
          postRequest.set_version(API_VERSION)
          postRequest.set_product(PRODUCT)
          postRequest.set_action_name(POST_REQUEST_ACTION)
          postRequest.set_method('POST')
          # Use API version "4.0" to enable features like word-level timestamps. To use the default legacy version ("2.0"), comment out the 'KEY_VERSION' parameter.
          # To enable word-level timestamps, set KEY_ENABLE_WORDS to True. This requires API version "4.0".
          task = {KEY_APP_KEY : appKey, KEY_FILE_LINK : fileLink, KEY_VERSION : "4.0", KEY_ENABLE_WORDS : False}
          # To enable intelligent channel splitting, set KEY_AUTO_SPLIT to True in the task.
          # task = {KEY_APP_KEY : appKey, KEY_FILE_LINK : fileLink, KEY_VERSION : "4.0", KEY_ENABLE_WORDS : False, KEY_AUTO_SPLIT : True}
          task = json.dumps(task)
          print(task)
          postRequest.add_body_params(KEY_TASK, task)
          taskId = ""
          try :
              postResponse = client.do_action_with_exception(postRequest)
              postResponse = json.loads(postResponse)
              print (postResponse)
              statusText = postResponse[KEY_STATUS_TEXT]
              if statusText == STATUS_SUCCESS :
                  print ("Audio file transcription request successful!")
                  taskId = postResponse[KEY_TASK_ID]
              else :
                  print ("Audio file transcription request failed!")
                  return
          except ServerException as e:
              print (e)
          except ClientException as e:
              print (e)
          # Create a CommonRequest and set the task ID.
          getRequest = CommonRequest()
          getRequest.set_domain(DOMAIN)
          getRequest.set_version(API_VERSION)
          getRequest.set_product(PRODUCT)
          getRequest.set_action_name(GET_REQUEST_ACTION)
          getRequest.set_method('GET')
          getRequest.add_query_param(KEY_TASK_ID, taskId)
          # Submit the request to query the audio file transcription result.
          # Poll for the transcription result until the server returns a status of "SUCCESS", "SUCCESS_WITH_NO_VALID_FRAGMENT",
          # or an error. Then, stop polling.
          statusText = ""
          while True :
              try :
                  getResponse = client.do_action_with_exception(getRequest)
                  getResponse = json.loads(getResponse)
                  print (getResponse)
                  statusText = getResponse[KEY_STATUS_TEXT]
                  if statusText == STATUS_RUNNING or statusText == STATUS_QUEUEING :
                      # Continue polling
                      time.sleep(10)
                  else :
                      # Stop polling
                      break
              except ServerException as e:
                  print (e)
              except ClientException as e:
                  print (e)
          if statusText == STATUS_SUCCESS :
              print ("Audio file transcription successful!")
          else :
              print ("Audio file transcription failed!")
          return
      accessKeyId = os.getenv('ALIYUN_AK_ID')
      accessKeySecret = os.getenv('ALIYUN_AK_SECRET')
      appKey = os.getenv('NLS_APP_KEY')
      fileLink = "https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav"
      # Run the audio file transcription.
      fileTrans(accessKeyId, accessKeySecret, appKey, fileLink)

3. Run the following command to execute the sample code.

   python3 demo.py

   A successful execution returns a result similar to the following, ending with the message Audio file transcription successful!.

   {'TaskId': 'xxx', 'StatusCode': 21050000, 'StatusText': 'SUCCESS', 'Result': {'Sentences': [{'Text': '北京的天气', 'BeginTime': 0, 'EndTime': 2365, 'ChannelId': 0}]}}
   Audio file transcription successful!

   For more details about the Audio File Transcription interface, see API reference.

Call speech synthesis using an SDK

1. Download the nls-sdk-java-demo.

2. In your IDE, open the downloaded sample code and set the parameters for Speech Synthesis. Then, right-click and select Run "SpeechSynthesizerDemo main()".

   Parameter	Value
   Appkey	Get the Appkey from the Intelligent Speech Interaction console.
   Token	On the Intelligent Speech Interaction console overview page, click Get Temporary AccessToken.

   // 1. Replace YOUR_APPKEY and YOUR_TOKEN with your actual AppKey and token.
   String appKey = "YOUR_APPKEY";
   String token = "YOUR_TOKEN";
   String filePath = "nls-sample-16k.wav";
   
   // 2. Comment out the following code. It is used for passing parameters from the command line.
   // if (args.length == 3) {
   //     appKey = args[0];
   //     token = args[1];
   //     filePath = args[2];
   // }

   // 3. Set the Speech Synthesis parameters.
   synthesizer.setVoice("xiaoyun");
   synthesizer.setSampleRate(16000);
   synthesizer.setFormat(OutputFormatEnum.WAV);
   synthesizer.setText("The weather is nice and sunny today.");

   • 1. To get your Appkey and token, see Start here.

   • 2. Comment out this code block. This code is for passing parameters from the command line when running a JAR package.

   • 3. Enter the parameters for Speech Synthesis in this section.

   Running the code prints the following logs to the console, and the synthesized audio is saved to the tts_test.wav file.

   name: SynthesisStarted
   [binary audio data received]
   name: SynthesisCompleted
   Output file: tts_test.wav

   For more details about the Speech Synthesis interface, see API reference.

Call asynchronous long-text synthesis API with cURL

1. Run the following command to submit a speech synthesis task.

   • Get the Appkey from the Intelligent Speech Interaction console.

   • On the Intelligent Speech Interaction console overview page, click Get Temporary AccessToken.

   curl -X POST 'https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async' \
   -H 'Content-Type: application/json' \
   --data-raw '{
       "payload":{
           "tts_request":{
               "voice":"xiaoyun",
               "sample_rate":16000,
               "format":"wav",
               "text":"今天天气好晴朗",
               "enable_subtitle": true
           },
           "enable_notify":false
       },
       "context":{
           "device_id":"my_device_id"
       },
       "header":{
           "appkey":"TuBrUhcloN******",  # Replace with your Appkey.
           "token":"d9afc8a07b154e0b86d4152265******" # Replace with your token.
       }
   }'
                 

   A successful request returns the following response, which contains the task_id, the unique identifier for this task.

   // The POST response is as follows and includes the task_id.
   
   {"status":200,"data":{"task_id":"8b240239f3c646748c84acaf98c****"},"error_code":20000000,"error_message":"SUCCESS","request_id":"cc03ca1bccab438eb74740127391****"}

2. Based on the task_id from the previous step, send a GET request to download the synthesized file.

   GET request URL:
   https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey={Appkey}&task_id={task_id}&token={Token}
   
   Example:
   curl -X GET 'https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey=TuBrUhcloNpE****&task_id=8b240239f3c646748c84acaf98c******&token=d9afc8a07b154e0b86d4152265******'

3. If the command runs successfully, it returns the following result, where audio_address is the download link for the synthesized audio.

   // Example GET response. The audio_address is the URL to listen to and download the synthesized audio. Copy and paste it into your browser.
   
   {"status":200,"data":{"sentences":[{"text":"今天天气好晴朗","begin_time":"0","end_time":"1985"}],"task_id":"8b240239f3c646748c84acaf9*","audio_address":"http://nls-cloud-cn-shanghai.oss-cn-shanghai.aliyuncs.com/jupiter-flow/tmp/8b240239f3c646748c84ac******.wav?Expires=16630****&OSSAccessKeyId=LTAI****************&Signature=rTFF****************","notify_custom":""},"error_code":20000000,"error_message":"SUCCESS","request_id":"6dd08e26170f4be8bd5a510daa2*****"}

   For more information about Asynchronous Long-text Synthesis, see the API reference.

Call asynchronous long-text synthesis API with Postman

1. Download Postman.

2. Send the following POST request in Postman.

   • Get the Appkey from the Intelligent Speech Interaction console.

   • On the Intelligent Speech Interaction console overview page, click Get Temporary AccessToken.

   Parameter	Example
   URL	https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async
   Header	Content-Type: application/json
   Body	See the code below.

   Body code:

   {
       "payload":{
           "tts_request":{
               "voice":"xiaoyun",
               "sample_rate":16000,
               "format":"wav",
               "text":"今天天气好晴朗",
               "enable_subtitle": true
           },
           "enable_notify":false
       },
       "context":{
           "device_id":"my_device_id"
       },
       "header":{
           "appkey":"TuBrUhcloN******",  # Replace with your Appkey
           "token":"d9afc8a07b154e0b86d4152265******" # Replace with your token
       }
   }

   1. Enter the POST URL.

      Select the POST method and set the URL to https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async. In Params, add the appkey parameter and set its value to your Appkey.

   2. Enter the headers.

      Add the Header X-NLS-Token and set its value to your token. Set Content-Type to application/json.

   3. Enter the body.

      Select the raw option and the JSON type. Paste the JSON content from the Body code above, replacing the placeholder appkey and token with your actual values.

   A successful POST request returns a response that contains the task_id. In the response, status is 20000000, message is SUCCESS, and error_code is 0.

3. Get and download the synthesized file.

   1. Send a GET request using the task_id from the previous step.

      GET request URL:
      https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey={Appkey}&task_id={task_id}&token={Token}
      
      Example:
      https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey=TuBrUhcloN******&task_id=8a63f10b2eaa4c75a47962eeee******&token=d9afc8a07b154e0b86d4152265******

   2. The response to a GET request returns the audio_address URL of the synthesized audio file. The JSON response contains a status field (200), a data object (which includes the audio_address download URL, a sentences array of start and end times, and the task_id), and an error_code field (20000000).

   3. Copy the audio_address from the previous step into your browser to listen to and download the file. This file is retained for a maximum of 7 days.

      An audio player page appears in your browser, where you can play the synthesized audio directly.

      For more details about the Asynchronous Long-text Synthesis interface, see the API reference.

FAQ