> 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/rimiapi.md).

# 音声取り込みAPI

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

`POST` /voice/v1/ingest

## **説明**

Voice Ingestionエンドポイントは、インシデント処理のために音声ファイルを受け取り、一意の **audio\_id** ファイルのステータスを照会し、成功時にインシデント結果を特定するためのものです。音声ファイルには短い発話（例: 1〜2文）が含まれている必要があり、以下の要件に準拠していなければなりません：

* **ファイル形式**：WAV、OGG、MP3
* **サイズ上限：** 最大5MB

技術的な制約がない限り、OGG は推奨フォーマットです。音質に対して最も優れたファイル圧縮率を提供します。連続音声ストリームを扱う場合は、軽量な [音声活動検出器](https://github.com/snakers4/silero-vad) モデルを使用して、無音やノイズなどの非音声成分を除去し、取り込みに送信するための分離された音声クリップのセットを生成してください。これは簡単に設定でき、待ち時間と検出性能を向上させながら、送受信コストを大幅に削減します。必要に応じて、コードスニペットや実装の सहायताについては GGWP の担当者までお問い合わせください。

## **パラメータ**

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

* **data:** 上記要件に準拠した音声ファイルのバイナリ。
* **ヘッダー**
  * **ファイル名**：音声ファイルの識別子。 
    * 例： `20230620_john123.wav`
  * **ユーザーID:** 音声が紐づくユーザーです。検出された音声インシデントは、そのユーザーの評判スコアとプロフィールに影響します。
    * 例： `player10`
  * **セッションID:** 音声が記録されたセッション（例: 会話）です。マッチベースのゲームでは、これがマッチIDとなり、GGWP のコンテキストモデルが同じ session-id 内の他のユーザー音声 / メッセージから以前の文脈を利用できるようになります。
    * 例： `match_unranked_20230620_12345`
  * **音声時刻:** 音声の UTC 開始時刻を YYYY-MM-DD HH:MM:SS.SSS または YYYY-MM-DD HH:MM:SS 形式で指定します。これはセッション内の会話の順序を判断するために使用されます。
    * 例： `2023-06-20 10:24:23`
  * **x-api-key:** あなたの組織とダッシュボードに対応する GGWP API キー。
  * （任意） **username:** ユーザーが選択したわかりやすい表示名の文字列です。これは GGWP ダッシュボードで User ID の横に表示され、指定がない場合は User ID が既定値になります。
    * 例： `john123`

## **呼び出し例**

**Bash**

```bash
curl --location --request POST 'https://api.ggwp.com/voice/v1/ingest' \
--header 'file-name: 20230620_john123.wav' \
--header 'user-id: player10' \
--header 'username: john123' \
--header 'session-id: match_unranked_20230620_12345' \
--header 'audio-time: 2023-06-20 10:24:23' \
--header 'x-api-key: GGWP_API_KEY' \
--data-binary '@/location/to/20230620_john123.wav'
```

**Python**

```python
import requests

# ユーザー / セッション情報を含むヘッダーを準備
headers = {
    "file-name": "20230620_john123.wav",
    "user-id": "player10",
    "username": "john123",
    "session-id": "match_unranked_20230620_12345",
    "audio-time": "2023-06-20 10:24:23",
    "x-api-key": "GGWP_API_KEY"
}

# 音声ファイルをメモリに読み込む
with open('/location/to/20230620_john123.wav', 'rb') as f:
    file_content = f.read()

# データとヘッダーを指定して POST リクエストを送信
response = requests.post(
    'https://api.ggwp.com/voice/v1/ingest',
    headers=headers,
    data=file_content
)

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

## **出力**

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

  ```bash
  {
      "audio_id": "01999d0b-cd00-4616-9d50-d9e1f6dddc60",
      "message": "ファイル 20230620_john123.wav を正常にアップロードしました。"
  }
  ```
* 400
  * 無効な入力パラメータ
* 403
  * 無効な API キー、または API キーがありません
* 500
  * サーバー側のエラーレスポンス