Intelligent Speech Interaction:RESTful API

前提条件

API を呼び出す前に、次の情報を準備してください。

• プロジェクトの appkey。プロジェクトの作成方法と appkey の取得方法については、「プロジェクトの作成」をご参照ください。

• アクセス トークン。トークンの取得方法については、「アクセス トークンの取得」をご参照ください。

音声の要件

言語とシナリオモデルはリクエストで指定できません。コンソールでプロジェクトの音声に一致するモデルを選択してください。詳細については、「プロジェクトの管理」をご参照ください。

クイックテスト

サンプル音声ファイル nls-sample-16k.wav のダウンロード。このファイルは、汎用モデル用の 16 kHz WAV ファイルです。

appkey とトークンを設定し、次のコマンドを実行してください。

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

成功応答の例：

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

仕組み

クライアントは、認証情報、リクエストパラメーター、および完全な音声を 1 つの HTTP POST リクエストで送信します。音声を処理した後、サーバーは同じ HTTP 接続を介して 1 つの JSON 応答を返します。応答が到着するまで接続を開いたままにしてください。

1. クライアントはサーバーに POST リクエストを送信します。

2. サーバーは認証情報とリクエストパラメーターを検証し、音声を処理します。

3. サーバーはタスク ID、ステータスコード、および文字起こし結果を返します。

サービスエンドポイント

プロジェクトのリージョンとネットワーク環境に基づいてエンドポイントを選択してください。パブリックエンドポイントは HTTPS と HTTP をサポートしています。HTTPS を推奨します。

関連 API

リクエストは、リクエスト行、リクエストヘッダー、およびリクエストボディで構成されます。

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]

応答

{
  "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"
}

ステータスコード

散発的なサーバーエラー (5xxxxxxx) は再試行してください。エラーが解決しない場合は、応答のタスク ID を含めてチケットを送信してください。

コード例

以下の例では、エンドポイント、appkey、トークン、およびローカルの音声パスを環境変数から読み取り、PCM 音声をバイナリデータとして送信します。

トークンの取得方法については、「アクセス トークンの取得」をご参照ください。

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("環境変数がありません： " + 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("環境変数がありません： ") + 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("音声ファイルを開けません");
    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("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"環境変数がありません： {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("環境変数がありません： " . $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('音声ファイルを読み取れません');
}

$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(`環境変数がありません： ${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($"環境変数がありません： {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("環境変数がありません： " + 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))
}

関連ドキュメント

• プロジェクトを作成し、認識モデルを設定するには、「プロジェクトの管理」をご参照ください。

• アクセス トークンを生成するには、「アクセス トークンの取得」をご参照ください。