リアルタイムストリーミングの認識

Classic/VPC環境で利用できます。

リアルタイムで、16kHZ、1Channel、16bits per sampleの PCM(ヘッダなしの WAVファイル)形式の音声データを認識し、テキストに変換します。gRPC方式を通じてのみアクセスが可能です。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

リクエスト手順

gRPC方式を通じて認識をリクエストする方法は次の通りです。

1. 事前準備
2. Config JSON
3. 認識(Recognize)

1. Protoc Compilerのインストールと準備

APIを使用するための事前準備のため、gRPCサイトを参照して Protoc Compilerをインストールします。インストール後、必要に応じて Pythonと Javaの中から言語を選択し、APIのインターフェースが定義された'nest.proto'ファイルを通じてCompilerを呼び出します。
Protoc Compilerをインストールして gRPCコードを生成する方法は次の通りです。

1. Protoc Compilerをインストールするサーバにリモートアクセスします。

2. gRPC使用のためのパッケージとプラグインをインストールします。

   • Rocky Linux: Python

     # 最新状態の確認
     sudo dnf update
     
     # Pythonのインストール: Linuxサーバに Pythonをインストールします。
     sudo dnf install python3
     
     # pipのインストールとアップグレード: pipは Python用パッケージインストールプログラムです。
     sudo dnf install python3-pip
     pip3 install --upgrade pip
     
     # grpcio-toolsのインストール: pipを使用して「grpcio-tools」をインストールします。
     pip3 install grpcio-tools
     
     # nest.protoファイルの作成
     touch nest.proto
     
     # protoc compilerで nest.protoファイルをコンパイル
     python3 -m grpc_tools.protoc -I=. --python_out=. --grpc_python_out=. nest.proto
     

   • Rocky Linux: Java

     # protoc-gen-grpc-javaプラグインのダウンロード(バージョン番号は確認が必要 https://github.com/grpc/grpc-java/releases)
     curl -OL https://repo1.maven.org/maven2/io/grpc/protoc-gen-grpc-java/1.66.0/protoc-gen-grpc-java-1.66.0-linux-x86_64.exe
     
     # PATHに追加
     mv protoc-gen-grpc-java-1.66.0-linux-x86_64.exe /usr/local/bin/protoc-gen-grpc-java
     
     # 実行権限に変更する
     chmod +x /usr/local/bin/protoc-gen-grpc-java
     
     # インストールの確認
     protoc-gen-grpc-java --version
     
     # nest.protoファイルの作成
     touch nest.proto
     
     # protoc compilerで nest.protoファイルをコンパイル
     protoc --proto_path=. --java_out=output/directory --grpc-java_out=output/directory nest.proto
     

3. 'nest.proto'ファイルを開いて次のコードを入力し、gRPCコードを生成します。

   syntax = "proto3";
   option java_multiple_files = true;
   package com.nbp.cdncp.nest.grpc.proto.v1;
   
   enum RequestType {
     CONFIG = 0;
     DATA = 1;
   }
   
   message NestConfig {
     string config = 1;
   }
   
   message NestData {
     bytes chunk = 1;
     string extra_contents = 2;
   }
   message NestRequest {
     RequestType type = 1;
     oneof part {
       NestConfig config = 2;
       NestData data = 3;
     }
   }
   
   message NestResponse {
     string contents = 1;
   }
   service NestService {
     rpc recognize(stream NestRequest) returns (stream NestResponse){};
   }
   

2. 認証(Authorization)

Protoc Compilerで gRPCコードの生成が完了したら、認証を行います。認証は、API呼び出し時にAuthorizationヘッダに Bearerトークンを含め、サーバに対して正当性の認証を行う方式で実施します。認証を行う際は、次の点にご注意ください。

• gRPC Channelを設定し、nest_grpc_pb2の Client Side Proxyであるstubを作成します。
• stubの作成後、recognizeメソッドを呼び出す際に、認証キーを含むMetadata(メタデータ)を付与して実行します。
  • リアルタイムストリーミング認識 APIは Freeプランではサポートしていません。Basic長文認識プランでのみサポートしています。

認証ヘッダ

認証ヘッダは次の通りです。

認証手順

認証方法は次の通りです。

Python

Rocky Linux環境にて Pythonを使用して認証を行う方法は次の通りです。

1. Pythonファイルを作成します。ここではファイル名をmain.pyに指定しました。

   touch main.py
   

2. main.pyに次の内容を追加します。

   import grpc
   import json
   
   import nest_pb2
   import nest_pb2_grpc
   
   channel = grpc.secure_channel(
           'clovaspeech-gw.ncloud.com:50051',
           grpc.ssl_channel_credentials()
   )
   client = NestServiceStub(channel)
   metadata = (("authorization", f"Bearer {secretKey}"),) #小文字 authorizationは必須 / secretkeyは長文認識ドメインで確認
   call = client.YourMethod(YourRequest(), metadata=metadata)
   

Java

Rocky Linux環境にて Javaを使用して認証を行う方法は次の通りです。

1. Javaファイルを作成します。ここではファイル名をmain.javaに指定しました。

   touch main.java
   

2. main.javaに次の内容を追加します。

   ManagedChannel channel = NettyChannelBuilder
               .forTarget("clovaspeech-gw.ncloud.com:50051")
               .useTransportSecurity()
               .build();
   NestServiceGrpc.NestServiceStub client = NestServiceGrpc.newStub(channel);
   Metadata metadata = new Metadata();
   metadata.put(Metadata.Key.of("Authorization", Metadata.ASCII_STRING_MARSHALLER),
                "Bearer ${secretKey}");
   client = MetadataUtils.attachHeaders(client, metadata);
   

3. Config JSON

Protocで作成されたnest_pb2のNestRequestオブジェクトを使ってストリーミングエンドポイントに渡される Config JSONについて説明します。Config JSONは、リアルタイムストリーミング認識 APIを初回呼び出す際に転送する必要があります。
Config JSONには、次のようなフィールドを提供しています。

• transcription: 音声認識言語を設定
• keywordBoosting: 入力された単語の認識率を高める設定
• forbidden: 禁止語を設定
• semanticEpd: 音声認識結果生成基準を設定
• translationEpd: 翻訳時の Target言語、レスポンス受信方法などを設定

リクエストボディ

Config JSONのリクエストボディの説明は次の通りです。

Transcription

Transcriptionの説明は次の通りです。

Keyword Boosting

Keyword Boostingフィールドの詳細は次の通りです。

boostings

keywordBoosting.boostingsの説明は次の通りです。

Forbidden

Forbiddenフィールドの詳細は次の通りです。

SemanticEPD

Semantic EPDフフィールドの詳細は次の通りです。

Translation EPD

Translation EPDフィールドの詳細は次の通りです。

リクエスト例

Config JSONのリクエストのサンプルコードは次の通りです。

#Semantic EPD    
 {
  "semanticEpd": {
    "skipEmptyText": false,           
    "useWordEpd": false,              
    "usePeriodEpd": true,             
    "gapThreshold": 2000,             
    "durationThreshold": 20000,       
    "syllableThreshold": 0            
  }
}
#Translation Info / EPD
 {
  "translation": {
    "targets": ["en"],         
    "mergedResult": False,
    "gapThreshold": 2000,      
    "durationThreshold": 20000,
    "honorific": False,      
    "glossaryKey": string
            }
         }    
#KeywordBoosting
  {
  "keywordBoosting": {                  
    "boostings": [
      {
        "words": "test,test1,test2",
        "weight": 1
      },
      {
        "words": "テスト,テスト1,テスト2",
        "weight": 0.5
      }
    ],
  },
#Forbidden
    "forbidden": {
    "forbiddens":  "禁止語1,禁止語2",
  }
}

レスポンスボディ

Config JSONのレスポンスボディの説明は次の通りです。

エラーメッセージ

リクエスト失敗時に表示されるエラーメッセージの説明は次の通りです。

レスポンス例

Config JSONのレスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

{
  "uid": "{uid}",
  "responseType": [ "config" ],
  "config": {
    "status": "Success",
    "keywordBoosting": {
      "status": "Success"
    },
    "forbidden" : {
      "status": "Success"
    }
}

失敗

リクエストでhobiddenを入力して呼び出しが失敗した場合のレスポンスのサンプルコードは次の通りです。

{
  "uid": "{uid}",
  "responseType": [ "config" ]
  "config": {
    "status": "Unknown key: hobidden"
  }
}

4. 認識(Recognize)

Config JSONで必要な設定を行った後、recognizeを通じて音声認識 APIを呼び出し、リアルタイムで音声データを処理して認識します。Protocにて生成したコードにあるNestRequestと認証メタデータをstubのメソッドであるrecognizeを通じて音声認識 APIを呼び出す仕組みです。

リクエストボディ

Recognizeのリクエストボディの説明は次の通りです。

レスポンスボディ

Recognizeのレスポンスボディの説明は次の通りです。

alignInfos

config.alignInfosの説明は次の通りです。

エラーメッセージ

Recognizeリクエスト失敗時に表示されるエラーメッセージの説明は次の通りです。

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

• レスポンス成功および"responseType": [ "transcription" ]の場合

{
  "uid": "{uid}"
  "responseType": [ "transcription" ]
  "transcription": {
    "text": "これはテキストです。",
    "position": 0,
    "periodPositions": [3],
    "periodAlignIndices": [3],
    "epFlag": false,
    "seqId": 0,
    "epdType": "durationThreshold",
    "startTimestamp": 190,
    "endTimestamp": 840,
    "confidence": 0.997389124199423,
    "alignInfos": [
      {"word":"これは","start":190,"end":340,"confidence":0.9988637124943075},
      {"word":"テキスト","start":341,"end":447,"confidence":0.9990018488549978},
      {"word":"です","start":448,"end":580,"confidence":0.9912501264550316},
      {"word":".","start":581,"end":700,"confidence":0.9994397226648595},
      {"word":" ","start":701,"end":840,"confidence":0.9984142043105126}
    ]
  }
}

失敗

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

{
  "uid": string,                     # required
  "responseType": [ "recognize" ],    # required
  "recognize": {                     # required
    "status": string,                # required
    "epFlag": {                      # optional
      "status": string
    },
    "seqId": {                       # optional
      "status": string
    },
    "audio": {                       # op
      "status": 
    }
  }
}

5. その他の API

現在有効化状態の Stub呼び出し数と、ドメインの許可された最大 Stub数などを照会します。

curl --location 'https://clovaspeech-gw.ncloud.com:50051/api/v1/1064/active-calls' \
--header 'Authorization: Bearer ${API_KEY}'

レスポンス

レスポンスパラメータ

レスポンス例

{
    "activeCalls": 3,
    "maxCalls": 15,
    "timestamp": "2025-04-25T12:09:27.382+09:00"
}