> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/ops/control/speak-api-asynchronous.md).

# 強制発話：SpeakAPI（スピークAPI）

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

{% hint style="warning" %}
このAPIはデジタルヒューマン株式会社が提供するオーケストレーションレイヤーにデジタルヒューマンと会話AIが接続され、DHXが読み込まれている場合のみ有効です。コードスニペットに`dhx.js`と`dhx.css`を新たに読み込み、 `dhxOptions` で `personaIdentifier` `uneeq`を指定する必要があります。通常は[コードスニペットサンプル](/dev/hosted-experience/hosted-experience-code-samples.md)をそのままご利用いただければ気にする必要はありません。
{% endhint %}

```html
<link rel="stylesheet" href="https://hosted-experience.jp/css/dhx.css">

<script>
      window.dhxOptions = {
            "personaIdentifier": 'デジタルヒューマン株式会社から提供',
            "uneeq": uneeq
        }
</script>

<script src="https://hosted-experience.jp/js/dhx.js"></script>
```

{% hint style="warning" %}
APIエンドポイントは国内のリージョンにホストされています。
{% endhint %}

### **メソッド**

`POST`

`/api/v1/{uuid}/speak`

### **エンドポイント**

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

| URL（Connection BaseUrl）               | パス                     |
| ------------------------------------- | ---------------------- |
| `https://{DIP上のペルソナの情報か、担当に確認してください}` | `/api/v1/{uuid}/speak` |

```html
https://{DIP上のペルソナの情報か、担当に確認してください}/api/v1/{uuid}/speak
```

### リクエストパラメータ

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

### POSTデータ（JSON形式）

| キー             | 値            | 必須 | 備考                                                                                                                  |
| -------------- | ------------ | -- | ------------------------------------------------------------------------------------------------------------------- |
| `session_id`   | アバターのセッションID | ○  | [セッションIDを確認するには？](/ops/troubleshooting/checking-log-and-session-id.md)                                              |
| `speak_text`   | 発話させたい文字列    | ○  | プレーンな発話文字列に追加して、[SynAnim (シンアニム) - シンセティック アニメーションエンジン](/ops/control/behavior-overview.md) の制御タグやSSMLが利用可能です。       |
| `instructions` | インストラクション    |    | <p>任意、JSON文字列をセットしてください。ただしフロントエンドの種類によって異なります。<br>・ <a href="/pages/Nq3WwOOkKEtN1nQZdlKb">ホステッドエクスペリエンスの場合</a></p> |

### レスポンス（JSON形式）

| キー           | 値                             | 備考                                                                                                                                                                                                                                        |
| ------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result`     | success または error             |                                                                                                                                                                                                                                           |
| `speak_text` | DHKK内で処理が行われた後の発話リクエスト文字列     | 後続の処理で整形、[SSML](/ops/control/speech-control-ssml.md)や[アクションタグ](/ops/control/behavior-overview.md)等が付与される場合があります。最終的な処理された文字列はフロントエンドのJavaScriptコンソールに表示されるログをご確認ください。                                                                     |
| `metadata`   | DHKK内で処理が行われた後の発話リクエストメタデータ   |                                                                                                                                                                                                                                           |
| `type`       | resultがerrorの場合にエラーの原因を特定する値。 | <p>以下のエラーが存在します。<br>- PersonaNotFoundError : 指定したpersonaIdentifierのペルソナが存在しません。<br>- PersonaSuspendError : ペルソナがサスペンドされています。<br>- SessionNotLiveError : 指定した<code>session\_id</code>と接続できません。<br>- SpeakQueryError : Bodyの内容に誤りがあります。</p> |
| `detail`     | resultがerrorの場合にエラーの詳細を特定する値。 |                                                                                                                                                                                                                                           |

### Crulサンプル

```bash

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

```bash
curl -X POST 'https://{エンドポイントURL}/api/v1/{uuid}/speak' \
-H 'Content-Type: application/json' \
-d '{
    "session_id": "ブラウザのJavaScriptコンソールからUneeQ Session IDを取得",
    "speak_text": "こんにちは<uneeq:custom_event name=\"camera_close_up\" />今日は<uneeq:action_bow />良い天気ですね",
    "instructions": "<インストラクション>"
}'
```

### セキュリティについて

このAPIはフロントエンドアプリからではなく、常にバックエンドサービスからリクエストしてください。フロントエンドから制御したい場合はホステッドエクスペリエンスのメソッドを使用してください。