サポートされているオーディオ形式、ファイルサイズ制限、再生時間制限、その他の入力要件については、オーディオ仕様 を参照してください。
クイックスタート
APIキーの取得： APIキーの取得 。セキュリティのため、APIキーは環境変数に設定することをお勧めします。SDKをダウンロードしてサンプルコードを実行します:
最新のSDKバンドルのダウンロード 。TAR アーカイブを抽出します。 neonui から HAR 形式の SDK を取得し、プロジェクトの依存関係に追加します。C++ 統合の場合、TAR アーカイブ内の native/libs と native/include を使用して、動的ライブラリとヘッダーファイルを取得します。
DevEco Studio でプロジェクトを開きます。サンプルコードは DashFunAsrFlashFileTranscriberPage.ets にあります。API キーを置き換えて機能を試してください。
呼び出し手順 同期モード
SDKを初期化する
ビジネス要件に基づいてパラメータを設定する
startFileTranscriber を呼び出して非リアルタイム音声認識リクエストを送信し、結果を待ちます。
onFileTransEventCallback を使用して EVENT_FILE_TRANS_RESULT イベントをリッスンし、最終的な認識結果を取得します。
release を呼び出して SDK リソースを解放します
リクエストパラメータ 接続および制御パラメータ これらの設定を構成するには、JSON 文字列を initializeFileTrans メソッドの parameters パラメータに渡します。
パラメータ例： 以下のJSON文字列は例であり、すべてのパラメータをリストしているわけではありません。必要に応じてコードにパラメータを追加してください。{ "url" : "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" , "apikey" : "st-****" , "device_id" : "my_device_id" , "service_mode" : "1" }
パラメータ
パラメータ 型 必須 説明 urlstringはい サービスエンドポイント。このパラメータを wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation に設定します。{WorkspaceId} を実際の ワークスペース ID に置き換えます。 apikeystringはい API キー。長期間有効なキーが露出するリスクを減らすために、有効期間が短く、より安全な 一時的な API キー を使用することをお勧めします。 service_modestringはい 動作モード。非リアルタイム音声認識の場合、このパラメータを"1"に設定します。 device_idstringはい エンドユーザーを識別する一意の文字列。アプリ内ユーザーIDまたはクライアント生成の一意のデバイス識別子を使用できます。このIDは主にログのトレースとトラブルシューティングに使用されます。 debug_pathstringいいえ ログファイルのパス。このパラメータは、save_log を true に設定して initializeFileTrans を呼び出した場合にのみ有効になります。この場合、ログファイルのパスを指定する必要があります。指定しない場合、エラーが発生します。ローカルには最大2つのログファイルが保持されます。 max_log_file_sizenumberいいえ ログファイルの最大サイズ (バイト単位)。このパラメータは、save_log を true に設定して initializeFileTrans を呼び出した場合にのみ有効になります。デフォルト：104857600 (100 * 1024 * 1024 バイト、または 100 MiB)。
認識パラメータ setParams を使用して nls_config パラメータを構成するか、startFileTranscriber を使用してすべての認識パラメータを構成します。パラメータ例： 以下のJSON文字列は例であり、すべてのパラメータをリストしているわけではありません。必要に応じてコードにパラメータを追加してください。{ "apikey" : "st-****" , "messages" : [ { "content" : [ { "input_audio" : { "data" : "{YOUR_AUDIO_URL}" }, "type" : "input_audio" } ], "role" : "user" } ], "nls_config" : { "format" : "mp3" , "model" : "fun-asr-flash-2026-06-15" } } パラメータ
パラメータ 型 必須 説明 apikeystringいいえ 接続と制御のパラメータ apikeyで一時的なAPIキー を使用している場合、有効期限切れを防ぐためにここで更新できます。 nls_configobjectはい 認識を制御するモデルとパラメータを含む、コア音声認識設定オブジェクト。 nls_config.modelstringはい モデル名。 nls_config.formatstringはい 音声形式。このパラメータを実際の形式に設定します。サポートされている形式には、wav、mp3、opusが含まれます。詳細については、音声仕様 を参照してください。 nls_config.sample_ratestringいいえ 音声のサンプルレート（Hz単位）。たとえば、16000は16 kHzのサンプルレートを示します。詳細については、音声仕様 を参照してください。 nls_config.vocabulary_idstringいいえ 事前コンパイルされた語彙のID。事前に語彙を作成し、認識時にそのIDを渡してホットワードを使用します。語彙が既知で、比較的安定しており、リクエスト間で再利用される場合にこのオプションを使用します。使用方法については、事前コンパイル済みホットワード を参照してください。 nls_config.language_hintsarray[string]いいえ 認識する言語コードを指定します。事前に言語が不明な場合は省略すると、モデルが自動検出します。最大 1 個の値を指定でき、それ以上指定した場合は最初の 1 個だけが有効です。
zh: 中国語
en: 英語
ja: 日本語
ko: 韓国語
vi: ベトナム語
th: タイ語
id: インドネシア語
ms: マレー語
tl: フィリピン語
hi: ヒンディー語
ar: アラビア語
fr: フランス語
de: ドイツ語
es: スペイン語
pt: ポルトガル語
ru: ロシア語
it: イタリア語
nl: オランダ語
sv: スウェーデン語
da: デンマーク語
fi: フィンランド語
no: ノルウェー語
el: ギリシャ語
pl: ポーランド語
cs: チェコ語
hu: ハンガリー語
ro: ルーマニア語
bg: ブルガリア語
hr: クロアチア語
sk: スロバキア語
messagesarray[object]はい メッセージのリスト。認識する音声と、認識精度を向上させるためのオプションの会話コンテキストが含まれています。 以下の説明を参照してください。
messagesパラメータ：
コンテキストは専門用語の認識精度を向上させます。使用方法については、コンテキスト強化 を参照してください。 制約事項 ：コンテキストメッセージ (input_text および text タイプ) はそれぞれ5つまでに制限されています。制限を超えた場合、最新の5つのメッセージのみが保持されます。ターンごとのコンテキストテキストの合計長 (user フィールドと assistant text フィールドの長さの合計) は 400 文字を超えてはなりません。各文字は1文字としてカウントされます。超過した文字は末尾から切り捨てられます。コンテキストが含まれる場合、messages メッセージは特定の順序に従う必要があります。コンテキストメッセージは会話のターンごとに配置します。各ターン内で、user (input_text タイプ) は対応する assistant (text タイプ) の前に配置する必要があります。入力オーディオを含む input_audio user メッセージは、messages の最後に配置する必要があります。
パラメータ 型 必須 説明 rolestringはい メッセージのロール。有効な値： user（必須）：ユーザーメッセージ。typeがinput_audioの場合、認識する音声を表します。typeがinput_textの場合、以前のターンからの認識結果またはドメイン固有の語彙（オプションのコンテキスト）を表します。assistant（オプションのコンテキスト）：以前のターンからの大規模言語モデルの応答。contentarray[object]はい メッセージコンテンツのリスト。以下の説明を参照してください。
contentパラメータ：
パラメータ 型 必須 説明 typestringはい コンテンツタイプ。各リクエストには少なくとも1つの input_audio メッセージが必要です。有効な値： input_audio（必須）：認識する音声入力（ロールはuser）。input_audioオブジェクトも指定する必要があります。input_text（オプションのコンテキスト）：以前のターンからのユーザー発話の認識結果、またはドメイン固有の語彙（ロールはuser）。textフィールドも指定する必要があります。text（オプションのコンテキスト）：以前のターンからの大規模言語モデルの応答（ロールはassistant）。textフィールドも指定する必要があります。input_audioobjectいいえ typeがinput_audioの場合に必須。input_audio.datastringはい 認識するオーディオデータ。サポートされているオーディオ形式、ファイルサイズ制限、再生時間制限、その他の入力要件については、 オーディオ仕様 を参照してください。次の2つの入力方法がサポートされています： 音声ファイルURL ：公開アクセス可能な音声ファイルURLを渡します。Base64 データ URI ：Base64 エンコードされたオーディオをデータ URI として渡します。data:{MIME_TYPE};base64, プレフィックスと Base64 エンコードされたオーディオデータを連結します。サポートされている MIME タイプには audio/wav、audio/mp3 が含まれます。例 (URL)：https://example.com/audio/sample.wav 例 (Base64)：data:audio/wav;base64,{BASE64_ENCODED_DATA} textstringいいえ type が input_text の場合は必須で、前のターンのユーザー発話の認識結果またはドメイン固有の語彙を指定します。type が text の場合は、前のターンの大規模言語モデルの応答を指定します。テキスト長は文字数でカウントされ、各文字は1文字としてカウントされます。各コンテキストターンにおけるすべてのメッセージの text フィールドの合計長は 400 文字を超えてはなりません。超過した文字は末尾から切り捨てられます。
主要インターフェース NativeNui initializeFileTrans 音声認識 SDK インスタンスを初期化します。
リアルタイム音声認識とは異なり、非リアルタイム (録音ファイル) 転写には、 initialize ではなく INativeFileTransCallback コールバックを伴う initializeFileTrans が必要です。
このメソッドはブロックされます。非UIスレッドから呼び出してください。
メソッドシグネチャ
public initializeFileTrans ( callback : INativeFileTransCallback , parameters : string , level : number , save_log : boolean = false ): number
パラメータ
パラメータ 型 説明 callbackINativeFileTransCallbackファイル転写イベントおよびデータコールバックインターフェースの実装。 parametersstring認証、接続、およびデバッグパラメータを含むJSON文字列。接続と制御のパラメータを参照してください。 levelnumberSDK ログレベル。 列挙型の値を使用します。 save_logbooleanログをローカルに保存するかどうか。trueに設定した場合、接続と制御のパラメータを使用してdebug_pathを設定してパスを指定し、max_log_file_sizeを使用してファイルサイズを設定します。
setParams このメソッドを使用して、 nls_config を個別に設定または更新します。すべてのパラメータが1回の呼び出しで startFileTranscriber に指定されている場合、このメソッドを呼び出す必要はありません。
メソッドシグネチャ
public setParams ( params : string ): number
パラメータ
パラメータ 型 説明 paramsstringnls_config パラメータ内の 認識パラメータ。nls_config 以外のパラメータはこのメソッドでは設定できません。
startFileTranscriber 認識を開始します。
メソッドシグネチャ
public startFileTranscriber ( params : string , task_id : ArrayBuffer ): number
パラメータ
パラメータ 型 説明 paramsstring認識パラメータ。 例： { "apikey" : "st-****" , "messages" : [ { "content" : [ { "input_audio" : { "data" : "{YOUR_AUDIO_URL}" }, "type" : "input_audio" } ], "role" : "user" } ], "nls_config" : { "format" : "mp3" , "model" : "fun-asr-flash-2026-06-15" } } task_idArrayBufferタスク ID バッファ。SDK は内部で生成されたランダムなタスク ID 文字列をこのバッファに書き込みます。そのバイト長は >= 33 バイト である必要があります (例では new ArrayBuffer(64) を使用)。呼び出しが成功した後、バッファをデコードしてタスクの task_id を取得します。
queryFileTranscriber このメソッドを使用して、非同期タスクの現在のステータスと結果をクエリします。呼び出しが成功すると、結果は onFileTransEventCallback コールバックの EVENT_FILE_TRANS_QUERY_RESULT イベントを介して返されます。
メソッドシグネチャ
public queryFileTranscriber ( task_id : string ): number
パラメータ
パラメータ 型 説明 task_idstringクエリを実行するタスクの ID ( startFileTranscriber によってバッファに書き込まれます)。
cancelFileTranscriber 現在のタスクを即座にキャンセルします。
メソッドシグネチャ
public cancelFileTranscriber ( task_id : string ): number
パラメータ
パラメータ 型 説明 task_idstringキャンセルするタスクのID。
release すべての内部 SDK リソースを解放します。この呼び出しの後、SDK インスタンスは使用できなくなります。再度使用するには、initializeFileTrans を呼び出して再度初期化します。
メソッドシグネチャ
GetVersion 現在のSDKバージョンを取得します。
メソッドシグネチャ
public GetVersion (): string
戻り値
現在の SDK バージョン。
INativeFileTransCallback：コールバック onFileTransEventCallback：イベントと認識結果をリッスンする メソッドシグネチャ
onFileTransEventCallback : ( event : Constants . NuiEvent , resultCode : number , finish : number , asrResult : AsrResult , taskId : string ) => void ;
パラメータ
パラメータ 型 説明 eventConstants.NuiEventコールバックイベント。 resultCodenumberEVENT_ASR_ERROR イベントが発生した場合にのみ有効です。finishnumberタスクが完了したかどうか。 asrResultAsrResult音声認識結果。 taskIdstringタスクID。
onFileTransLogTrackCallback：トレースログをリッスンする このコールバックは、トラブルシューティングとデバッグのために詳細な内部SDKログを受信します。
このコールバックを使用するには、20260908 以降の日付の HarmonyOS SDK パッケージをダウンロードしてください。
onFileTransLogTrackCallback ?: ( level : Constants . LogLevel , log : string ) => void ;
イベントタイプ HarmonyOS SDK では、イベントタイプは Constants.NuiEvent 列挙型によって定義されます。次のイベントは録音ファイルの転写に関連しています：
イベント 説明 EVENT_FILE_TRANS_CONNECTEDサービスに正常に接続しました。 EVENT_FILE_TRANS_UPLOADEDオーディオファイルが正常にアップロードされました。 EVENT_FILE_TRANS_QUERY_RESULTタスククエリ結果。 EVENT_FILE_TRANS_RESULT最終認識結果。 EVENT_ASR_ERROR音声認識中にエラーが発生しました。
