SpeakAPI（スピークAPI）をつかって、非同期で一方的に喋らせるには？

SpeakAPI（スピークAPI）はデジタルヒューマンを非同期（ユーザーからのリクエストなしに）で喋らせたいときに利用できます。下記のAPI経由あてに発話させたい文字列をPOSTしてください。

⚠️

このAPIはデジタルヒューマン株式会社が提供するオーケストレーションレイヤーにデジタルヒューマンと会話AIが接続されているときのみ有効です。

⚠️

APIエンドポイントは国内のリージョンにホストされています。

メソッド

POST

/api/v1/<uuid>/speak

エンドポイント

デジタルヒューマンが稼働するプラットフォームによって変わるので、担当に確認してください。

エンドポイント識別	URL	パス
nlp-orch-001	`https://nlp-orch-001.digitalhumans.ne.jp/`	`/api/v1/<uuid>/speak`
nlp-orch-002	`https://nlp-orch-002.digitalhumans.ne.jp/`	`/api/v1/<uuid>/speak`

例：　https://nlp-orch-001.digitalhumans.ne.jp/api/v1/<uuid>/speak

リクエストパラメータ

キー	値	必須	備考
uuid	DHKKが発行した識別子	○	デジタルヒューマン株式会社から提供しない限り確認する方法はありません。

POSTデータ（JSON形式）

キー	値	必須	備考
session_id	アバターのセッションID	○	セッションIDを確認するには？
speak_text	発話させたい文字列	○	プレーンな発話文字列に追加して、SynAnim (シンアニム) - シンセティックアニメーションエンジンの制御タグが利用可能です。
instructions	インストラクション		任意、JSON文字列をセットしてください。ただしフロントエンドの種類によって異なります。・ホステッドエクスペリエンスの場合

💡

instructions displayHtmlが未指定の場合、イベントハンドリングのAvatarAnswerContent content プロパティには、speak_textの値が自動入力されます。

レスポンス（JSON形式）

キー	値	備考
result	success または error
speak_text	DHKK内で処理が行われた後の発話リクエスト文字列	後続の処理で整形、SSMLやアクションタグ等が付与される場合があります。最終的な処理された文字列はフロントエンドのJavaScriptコンソールに表示されるログをご確認ください。
platform_status_code	デジタルヒューマンプラットフォームのレスポンス(JSON形式)
platform_response	デジタルヒューマンプラットフォームのレスポンス(JSON形式)
{message} エラーメッセージ	resultがerrorの場合のみ

デジタルヒューマンプラットフォームのレスポンス(JSON形式)

DHKKが提供するSpeakAPIのレスポンスパラメータplatform_status_codeとplatform_responseに格納されます。

Code	Status	Response	Reason	備考
204	No Content		非送信請求応答が正常に送信されました	正常に送信された場合でも、後続の音声合成などのエラーによって発話が行われないことがあります。表示されているデジタルヒューマンが発話しない場合は、フロントエンドのJavaScriptコンソールに表示されるログをご確認ください。
400	Bad Request	`{ "error": ERROR_DESCRIPTION }`	リクエストの本文/ヘッダーが無効です
401	Unauthorized	`{ "error": ERROR_DESCRIPTION }`	sessionIdJWTが無効です	お客様の問題ではなくプラットフォームとSpeakAPI間の認証に問題がある場合があります。担当までご連絡ください。
403	Forbidden	`{ "error": ERROR_DESCRIPTION }`	承認に失敗しました	お客様の問題ではなくプラットフォームとSpeakAPI間の認証に問題がある場合があります。担当までご連絡ください。
406	Not Acceptable	`{ "error": Avatar response queue limit reached }`	25の既存のメッセージがまだ配信されていないときにメッセージの発言が要求されました	応答制限についてをご覧下さい。
500	Server Error	`{ "error": ERROR_DESCRIPTION }`	サーバーでエラーが発生しました

Crulサンプル

curl -X POST "https://nlp-orch-001.digitalhumans.ne.jp/api/v1/<uuid>/speak" \
-H "Content-Type: application/json" \
-d '{
  "session_id": "ブラウザのJavaScriptコンソールからUneeQ Session IDを取得",
  "instructions":"<インストラクション>",
  "speak_text": "サンプルSpeak発話文"
}'

応答制限について

現在、APIは一度に最大25件（以前は5件）までのメッセージをキューに入れることができます。25件を超えるメッセージがスピーク待ちとしてキューに入っている場合、既存のメッセージがすべてデジタルヒューマンによって話されて処理されるまで、APIは「406 Not Acceptable」を返します。

セキュリティについて

このAPIはフロントエンドアプリからではなく、常にバックエンドサービスからリクエストしてください。

お役に立ちましたか？

😞

😐

🤩

最終更新日 October 8, 2024