Intelligent Speech Interaction:RESTful API

Prerequisites

Prepare the following information before calling the API:

• A project appkey. For information about how to create a project and obtain the appkey, see Create a project.

• An access token. For information about how to obtain a token, see Obtain an access token.

Audio requirements

The language and scenario model cannot be specified in the request. Select a model that matches the audio for the project in the console. For more information, see Manage projects.

Quick test

Download the sample audio file nls-sample-16k.wav. The file is a 16 kHz WAV file for the generic model.

Set the appkey and token, and then run the following command:

curl -X POST \
  -H "X-NLS-Token: <token>" \
  "https://nls-gateway-ap-southeast-1.aliyuncs.com/stream/v1/asr?appkey=<appkey>&format=wav&sample_rate=16000" \
  --data-binary @nls-sample-16k.wav

Example success response:

{
  "task_id": "cf7b0c5339244ee29cd4e43fb97f****",
  "result": "Weather in Beijing.",
  "status": 20000000,
  "message": "SUCCESS"
}

How it works

The client sends the authentication information, request parameters, and complete audio in one HTTP POST request. After processing the audio, the server returns one JSON response over the same HTTP connection. Keep the connection open until the response arrives.

1. The client sends a POST request to the server.

2. The server validates the authentication information and request parameters and processes the audio.

3. The server returns the task ID, status code, and transcription result.

Service endpoints

Select the endpoint based on the project region and network environment. Public endpoints support HTTPS and HTTP. HTTPS is recommended.

API reference

A request consists of a request line, request headers, and a request body.

POST /stream/v1/asr?appkey=<appkey>&format=pcm&sample_rate=16000&enable_punctuation_prediction=true HTTP/1.1

POST /stream/v1/asr?appkey=23f5****&format=pcm&sample_rate=16000 HTTP/1.1
X-NLS-Token: 450372e4279bcc2b3c793****
Content-Type: application/octet-stream
Content-Length: 94616
Host: nls-gateway-ap-southeast-1.aliyuncs.com

[audio data]

Responses

{
  "task_id": "cf7b0c5339244ee29cd4e43fb97f****",
  "result": "Weather in Beijing.",
  "status": 20000000,
  "message": "SUCCESS"
}

{
  "task_id": "8bae3613dfc54ebfa811a17d8a7a****",
  "result": "",
  "status": 40000001,
  "message": "Gateway:ACCESS_DENIED:The token is invalid"
}

Status codes

Retry an occasional server error (5xxxxxxx). If the error persists, submit a ticket and include the task ID from the response.

Code examples

The following examples read the endpoint, appkey, token, and local audio path from environment variables and send PCM audio as binary data.

For information about how to obtain a token, see Obtain an access token.

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;

public class SpeechRecognition {
    private static String required(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Missing environment variable: " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String endpoint = required("NLS_ENDPOINT");
        String appKey = URLEncoder.encode(required("NLS_APP_KEY"), StandardCharsets.UTF_8);
        String token = required("NLS_TOKEN");
        Path audioFile = Path.of(required("NLS_AUDIO_FILE"));
        String url = endpoint + "?appkey=" + appKey
                + "&format=pcm&sample_rate=16000"
                + "&enable_punctuation_prediction=true"
                + "&enable_inverse_text_normalization=true";

        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
                .header("X-NLS-Token", token)
                .header("Content-Type", "application/octet-stream")
                .POST(HttpRequest.BodyPublishers.ofFile(audioFile))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(
                request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
    }
}

#include <curl/curl.h>

#include <cstdlib>
#include <fstream>
#include <iostream>
#include <iterator>
#include <stdexcept>
#include <string>

std::string required(const char* name) {
    const char* value = std::getenv(name);
    if (value == nullptr || *value == '\0') {
        throw std::runtime_error(std::string("Missing environment variable: ") + name);
    }
    return value;
}

size_t writeResponse(char* data, size_t size, size_t count, void* target) {
    static_cast<std::string*>(target)->append(data, size * count);
    return size * count;
}

int main() {
    std::ifstream file(required("NLS_AUDIO_FILE"), std::ios::binary);
    if (!file) throw std::runtime_error("Cannot open audio file");
    std::string audio((std::istreambuf_iterator<char>(file)),
                      std::istreambuf_iterator<char>());

    curl_global_init(CURL_GLOBAL_DEFAULT);
    CURL* curl = curl_easy_init();
    if (curl == nullptr) throw std::runtime_error("Cannot initialize cURL");
    char* escaped = curl_easy_escape(curl, required("NLS_APP_KEY").c_str(), 0);
    std::string url = required("NLS_ENDPOINT") + "?appkey=" + escaped
            + "&format=pcm&sample_rate=16000"
            + "&enable_punctuation_prediction=true"
            + "&enable_inverse_text_normalization=true";
    curl_free(escaped);

    std::string response;
    std::string tokenHeader = "X-NLS-Token: " + required("NLS_TOKEN");
    curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, tokenHeader.c_str());
    headers = curl_slist_append(headers, "Content-Type: application/octet-stream");
    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, audio.data());
    curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, static_cast<curl_off_t>(audio.size()));
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writeResponse);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);

    CURLcode code = curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    curl_global_cleanup();
    if (code != CURLE_OK) throw std::runtime_error(curl_easy_strerror(code));
    std::cout << response << std::endl;
}

import os
import urllib.parse
import urllib.request


def required(name):
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing environment variable: {name}")
    return value


endpoint = required("NLS_ENDPOINT")
query = urllib.parse.urlencode({
    "appkey": required("NLS_APP_KEY"),
    "format": "pcm",
    "sample_rate": 16000,
    "enable_punctuation_prediction": "true",
    "enable_inverse_text_normalization": "true",
})
with open(required("NLS_AUDIO_FILE"), "rb") as audio_file:
    request = urllib.request.Request(
        f"{endpoint}?{query}",
        data=audio_file.read(),
        headers={
            "X-NLS-Token": required("NLS_TOKEN"),
            "Content-Type": "application/octet-stream",
        },
        method="POST",
    )
with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

<?php

function required_env(string $name): string {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Missing environment variable: " . $name);
    }
    return $value;
}

$query = http_build_query([
    'appkey' => required_env('NLS_APP_KEY'),
    'format' => 'pcm',
    'sample_rate' => 16000,
    'enable_punctuation_prediction' => 'true',
    'enable_inverse_text_normalization' => 'true',
]);
$audio = file_get_contents(required_env('NLS_AUDIO_FILE'));
if ($audio === false) {
    throw new RuntimeException('Cannot read the audio file');
}

$curl = curl_init(required_env('NLS_ENDPOINT') . '?' . $query);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $audio,
    CURLOPT_HTTPHEADER => [
        'X-NLS-Token: ' . required_env('NLS_TOKEN'),
        'Content-Type: application/octet-stream',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($curl);
if ($response === false) {
    throw new RuntimeException(curl_error($curl));
}
echo $response . PHP_EOL;

import fs from "node:fs";
import http from "node:http";
import https from "node:https";

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable: ${name}`);
  return value;
}

const endpoint = new URL(required("NLS_ENDPOINT"));
endpoint.search = new URLSearchParams({
  appkey: required("NLS_APP_KEY"),
  format: "pcm",
  sample_rate: "16000",
  enable_punctuation_prediction: "true",
  enable_inverse_text_normalization: "true",
});
const audio = fs.readFileSync(required("NLS_AUDIO_FILE"));
const transport = endpoint.protocol === "https:" ? https : http;

const request = transport.request(endpoint, {
  method: "POST",
  headers: {
    "X-NLS-Token": required("NLS_TOKEN"),
    "Content-Type": "application/octet-stream",
    "Content-Length": audio.length,
  },
}, (response) => {
  let body = "";
  response.setEncoding("utf8");
  response.on("data", (chunk) => { body += chunk; });
  response.on("end", () => console.log(body));
});
request.on("error", (error) => { throw error; });
request.end(audio);

using System.Net.Http.Headers;

static string Required(string name)
{
    string? value = Environment.GetEnvironmentVariable(name);
    if (string.IsNullOrWhiteSpace(value))
        throw new ArgumentException($"Missing environment variable: {name}");
    return value;
}

string query = string.Join("&", new Dictionary<string, string>
{
    ["appkey"] = Required("NLS_APP_KEY"),
    ["format"] = "pcm",
    ["sample_rate"] = "16000",
    ["enable_punctuation_prediction"] = "true",
    ["enable_inverse_text_normalization"] = "true",
}.Select(item => $"{Uri.EscapeDataString(item.Key)}={Uri.EscapeDataString(item.Value)}"));

using HttpClient client = new();
using ByteArrayContent audio = new(await File.ReadAllBytesAsync(Required("NLS_AUDIO_FILE")));
audio.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
using HttpRequestMessage request = new(HttpMethod.Post, $"{Required("NLS_ENDPOINT")}?{query}");
request.Headers.Add("X-NLS-Token", Required("NLS_TOKEN"));
request.Content = audio;
using HttpResponseMessage response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func required(name string) string {
	value := os.Getenv(name)
	if value == "" {
		panic("Missing environment variable: " + name)
	}
	return value
}

func main() {
	audio, err := os.ReadFile(required("NLS_AUDIO_FILE"))
	if err != nil {
		panic(err)
	}
	query := url.Values{
		"appkey":                            {required("NLS_APP_KEY")},
		"format":                            {"pcm"},
		"sample_rate":                       {"16000"},
		"enable_punctuation_prediction":     {"true"},
		"enable_inverse_text_normalization": {"true"},
	}
	request, err := http.NewRequest(
		http.MethodPost, required("NLS_ENDPOINT")+"?"+query.Encode(), bytes.NewReader(audio))
	if err != nil {
		panic(err)
	}
	request.Header.Set("X-NLS-Token", required("NLS_TOKEN"))
	request.Header.Set("Content-Type", "application/octet-stream")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}

Related documents

• To create a project and configure the recognition model, see Manage projects.

• To generate an access token, see Obtain an access token.