> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/jp/apidokyumento/pakkji/sanpuringuapi.md).

# 音声サンプリングAPI

\[ ベース URL: `api.ggwp.com`]

`POST` /voice/v1/sample

## **説明**

Voice Samplingエンドポイントは、ユーザーIDとセッションIDを受け取り、そのセッション内のユーザーの音声を処理のために送信すべきかどうかを判断するための真偽値を返します。このエンドポイントは、コスト予測性のために総音声量の一部を処理したいクライアントにのみ適用されます。

例として、クライアントは想定される合計200,000時間のうち、月間100,000時間の音声を処理したいと考える場合があります。これをサンプリングする簡単な方法として、音声クリップの50%をランダムに送信対象から外したり、100,000の上限に達したら送信を停止したりできますが、これらの方法では、ユーザーの過去の行動や、セッション内で誰かがミュートしたかどうかといった文脈を活用できません。

Voice Samplingエンドポイントにより、GGWPは利用可能な文脈を使って賢くカスタマイズ可能なサンプリング手法を管理し、シンプルなAPIを通じてそのロジックを公開しながら、月間時間を最大化できます。クライアントは新しいセッションの開始時に各ユーザーに対してこのエンドポイントを1回呼び出し、出力される真偽値を使ってユーザーの音声を送信するかどうかを判断できます。バックエンドでは、GGWPは各ユーザーの評判スコアと受信した文脈データ（ミュートや友人グラフなど）を使用して、最も重要な会話をモデレートします。

<figure><img src="/files/8c0f274ebac2dce1c0b14c85deb94b47609cebfa" alt=""><figcaption><p>音声サンプリングの図解</p></figcaption></figure>

***注**: サンプリングは常にモデレーションの効果を下げます。なぜなら、安全な音声とインシデントの音声をきれいに分離する軽量な方法がないためです。ただし、コスト管理のためなど、どうしてもサンプリングが必要な場合は、このエンドポイントを使うことで、月間時間をできるだけ簡単に最大化するのに役立ちます。*

## **パラメータ**

POSTリクエストでは次のパラメータが必要です:

* **data:** 以下のフィールドを含む辞書:
  * **user\_id:** サンプリング対象として検討されているユーザー。
    * 例： `player10`
  * **session\_id:** ユーザーがサンプリング対象として検討されているセッション（例: 会話）。マッチベースのゲームでは、これはマッチIDになります。
    * 例： `match_unranked_20230620_12345`
* **ヘッダー**
  * **x-api-key:** あなたの組織とダッシュボードに対応するGGWP APIキー。

## **呼び出し例**

**Bash**

```bash
curl --location --request POST 'https://api.ggwp.com/voice/v1/sample' \
--header 'x-api-key: GGWP_API_KEY' \
--data-raw '{
  "session_id": "match_unranked_20230620_12345",
  "user_id": "player10"
}'
```

**Python**

```python
import requests

# ヘッダーとデータ本文を準備する
headers = {
    "x-api-key": "GGWP_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "user_id": "player10",
    "session_id": "match_unranked_20230620_12345"
}

# ヘッダーを付けてPOSTリクエストを送信する
response = requests.post(
    'https://api.ggwp.com/voice/v1/sample',
    headers=headers,
    json=data
)

# レスポンスを確認
print(response.json())
```

## **出力**

* 200 レスポンス - 成功した操作

  ```bash
  {
      "user_id": "player10",
      "session_id": "match_unranked_20230620_12345",
      "sample": true
  }
  ```
* 400
  * 無効な入力パラメータ
* 403
  * 無効な API キー、または API キーがありません
* 500
  * サーバー側のエラーレスポンス