接口说明

cURL

上传本地音频文件，audio_file 默认为 nls-sample-16k.wav。

: "${NLS_APP_KEY:?Set NLS_APP_KEY}"
: "${NLS_TOKEN:?Set NLS_TOKEN}"
audio_file="${1:-nls-sample-16k.wav}"
curl --silent --show-error --max-time 120 --request POST \
  "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=${NLS_APP_KEY}&token=${NLS_TOKEN}&format=wav&sample_rate=16000" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary "@${audio_file}"

Java

使用 JDK 11 或更高版本，无需额外依赖。第一个程序参数为本地文件路径或音频 URL，必须提供。

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;
import java.time.Duration;

public class FlashRecognizer {
    private static String requiredEnv(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 {
        if (args.length != 1) {
            throw new IllegalArgumentException("Provide a local audio path or an HTTPS audio URL");
        }
        String query = "appkey=" + URLEncoder.encode(requiredEnv("NLS_APP_KEY"), StandardCharsets.UTF_8)
                + "&token=" + URLEncoder.encode(requiredEnv("NLS_TOKEN"), StandardCharsets.UTF_8)
                + "&format=wav&sample_rate=16000";
        boolean remote = args[0].startsWith("https://") || args[0].startsWith("http://");
        if (remote) {
            query += "&audio_address=" + URLEncoder.encode(args[0], StandardCharsets.UTF_8);
        }
        HttpRequest.BodyPublisher body = remote
                ? HttpRequest.BodyPublishers.noBody()
                : HttpRequest.BodyPublishers.ofFile(Path.of(args[0]));
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?" + query))
                .timeout(Duration.ofSeconds(120))
                .header("Content-Type", remote ? "application/text" : "application/octet-stream")
                .POST(body).build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println("HTTP status: " + response.statusCode());
        System.out.println(response.body());
        // Check the JSON status field; recognized text is in flash_result.sentences.
    }
}

C++

使用 C++11 或更高版本及 libcurl。第一个程序参数为本地音频路径，必须提供。

#include <curl/curl.h>
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>
#include <string>

size_t receive(char* data, size_t size, size_t count, void* output) {
    const size_t bytes = size * count;
    static_cast<std::string*>(output)->append(data, bytes);
    return bytes;
}

int main(int argc, char** argv) {
    const char* appkey = std::getenv("NLS_APP_KEY");
    const char* token = std::getenv("NLS_TOKEN");
    if (!appkey || !token || argc != 2) {
        std::cerr << "Set NLS_APP_KEY and NLS_TOKEN; provide a local WAV path\n";
        return 1;
    }
    std::ifstream file(argv[1], std::ios::binary);
    if (!file) return 1;
    std::ostringstream buffer;
    buffer << file.rdbuf();
    const std::string audio = buffer.str();
    if (curl_global_init(CURL_GLOBAL_DEFAULT) != CURLE_OK) return 1;
    CURL* client = curl_easy_init();
    if (!client) { curl_global_cleanup(); return 1; }
    char* encodedKey = curl_easy_escape(client, appkey, 0);
    char* encodedToken = curl_easy_escape(client, token, 0);
    if (!encodedKey || !encodedToken) {
        curl_free(encodedKey); curl_free(encodedToken);
        curl_easy_cleanup(client); curl_global_cleanup(); return 1;
    }
    std::string url = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?appkey=";
    url += std::string(encodedKey) + "&token=" + encodedToken + "&format=wav&sample_rate=16000";
    curl_free(encodedKey); curl_free(encodedToken);
    curl_slist* headers = curl_slist_append(nullptr, "Content-Type: application/octet-stream");
    std::string response;
    curl_easy_setopt(client, CURLOPT_URL, url.c_str());
    curl_easy_setopt(client, CURLOPT_POST, 1L);
    curl_easy_setopt(client, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(client, CURLOPT_POSTFIELDS, audio.data());
    curl_easy_setopt(client, CURLOPT_POSTFIELDSIZE_LARGE, static_cast<curl_off_t>(audio.size()));
    curl_easy_setopt(client, CURLOPT_CONNECTTIMEOUT, 10L);
    curl_easy_setopt(client, CURLOPT_TIMEOUT, 120L);
    curl_easy_setopt(client, CURLOPT_WRITEFUNCTION, receive);
    curl_easy_setopt(client, CURLOPT_WRITEDATA, &response);
    CURLcode result = curl_easy_perform(client);
    long status = 0;
    curl_easy_getinfo(client, CURLINFO_RESPONSE_CODE, &status);
    curl_slist_free_all(headers);
    curl_easy_cleanup(client);
    curl_global_cleanup();
    if (result != CURLE_OK) {
        std::cerr << curl_easy_strerror(result) << '\n'; return 1;
    }
    std::cout << "HTTP status: " << status << '\n' << response << '\n';
    // Check the JSON status field; recognized text is in flash_result.sentences.
    return status >= 200 && status < 300 ? 0 : 1;
}

Python

使用 Python 3 标准库，无需额外依赖。第一个程序参数为本地文件路径或音频 URL，默认读取 nls-sample-16k.wav。

import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request

audio_file = sys.argv[1] if len(sys.argv) > 1 else "nls-sample-16k.wav"
params = {
    "appkey": os.environ["NLS_APP_KEY"],
    "token": os.environ["NLS_TOKEN"],
    "format": "wav",
    "sample_rate": 16000,
}
if audio_file.startswith(("https://", "http://")):
    params["audio_address"] = audio_file
    audio = b""
    content_type = "application/text"
else:
    with open(audio_file, "rb") as source:
        audio = source.read()
    content_type = "application/octet-stream"
url = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?"
request = urllib.request.Request(
    url + urllib.parse.urlencode(params), data=audio,
    headers={"Content-Type": content_type}, method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    with error:
        result = json.load(error)
print("task_id:", result.get("task_id"))
if result.get("status") != 20000000:
    raise RuntimeError("Recognition failed: " + str(result.get("status")))
for sentence in result["flash_result"]["sentences"]:
    print(sentence["channel_id"], sentence["text"])

PHP

使用 PHP 7.3 或更高版本，并启用 cURL 扩展。第一个程序参数为本地文件路径或音频 URL，默认读取 nls-sample-16k.wav。

<?php
$appkey = getenv('NLS_APP_KEY');
$token = getenv('NLS_TOKEN');
if (!$appkey || !$token) {
    throw new RuntimeException('Set NLS_APP_KEY and NLS_TOKEN');
}
$source = $argv[1] ?? 'nls-sample-16k.wav';
$params = ['appkey' => $appkey, 'token' => $token, 'format' => 'wav', 'sample_rate' => 16000];
$remote = preg_match('/^https?:\/\//', $source) === 1;
if ($remote) {
    $params['audio_address'] = $source;
    $body = '';
} else {
    $body = file_get_contents($source);
    if ($body === false) {
        throw new RuntimeException('Cannot read audio file');
    }
}
$url = 'https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer?'
    . http_build_query($params, '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => ['Content-Type: ' . ($remote ? 'application/text' : 'application/octet-stream')],
]);
$response = curl_exec($curl);
if ($response === false) {
    $error = curl_error($curl);
    if (PHP_VERSION_ID < 80000) { curl_close($curl); }
    throw new RuntimeException($error);
}
if (PHP_VERSION_ID < 80000) { curl_close($curl); }
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
echo 'task_id: ' . ($result['task_id'] ?? '') . PHP_EOL;
if (($result['status'] ?? null) !== 20000000) {
    throw new RuntimeException('Recognition failed: ' . ($result['status'] ?? 'unknown'));
}
foreach ($result['flash_result']['sentences'] as $sentence) {
    echo $sentence['channel_id'] . ': ' . $sentence['text'] . PHP_EOL;
}

上传二进制音频流

将音频原始二进制数据放入请求体，Content-Type 设置为 application/octet-stream。Content-Length 为音频数据的字节数，可由 HTTP 客户端根据请求体设置。

使用音频文件链接

将音频文件 URL 经 URL 编码后放入 audio_address 查询参数，Content-Type 设置为 application/text，请求体为空。音频 URL 必须可由服务端访问；使用有有效期的链接时，需确保识别期间链接仍有效。