> 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/kr/api-1/standard-package/api-2.md).

# 음성 샘플링 API

\[ 기본 URL: `api.ggwp.com`]

`POST` /voice/v1/sample

## **설명**

음성 샘플링 엔드포인트는 사용자 ID와 세션 ID를 받아 해당 세션에서 사용자의 오디오를 처리 대상으로 보낼지 여부를 결정하는 불리언을 반환합니다. 이 엔드포인트는 비용 예측을 위해 전체 오디오 일부만 처리하려는 클라이언트에만 적용됩니다.

예시로, 클라이언트가 예상 총 200,000시간 중 월 100,000시간만 처리하려고 할 수 있습니다. 이를 위한 간단한 방법으로는 오디오 클립의 50%를 무작위로 제외하거나 100,000 제한에 도달하면 전송을 중단하는 방식이 있지만, 이러한 방법들은 사용자의 과거 행동이나 세션에서 음소거 여부 같은 컨텍스트를 활용하지 않습니다.

음성 샘플링 엔드포인트는 이용 가능한 컨텍스트를 사용해 스마트하고 사용자화된 샘플링 방식을 GGWP가 관리할 수 있게 하여 월간 시간을 최대화하고 간단한 API를 통해 그 논리를 노출합니다. 클라이언트는 새로운 세션 시작 시 각 사용자에 대해 이 엔드포인트를 한 번 호출하고 출력된 불리언을 사용해 사용자의 오디오를 보낼지 결정할 수 있습니다. 백엔드에서는 GGWP가 각 사용자의 평판 점수와 수신된 컨텍스추얼 데이터(예: 음소거나 친구 그래프)를 사용해 가장 관련성 높은 대화를 중재합니다.

<figure><img src="/files/b9cc77be2435a9215c565a20e8c1708ad7a9363a" alt=""><figcaption><p>음성 샘플링 그림(설명)</p></figcaption></figure>

***참고**: 샘플링은 안전한 오디오와 사건성 오디오를 깔끔하게 분리하는 경량 방법이 없기 때문에 항상 중재 효과를 감소시킵니다. 그러나 비용 통제로 인해 샘플링이 필요하다면 이 엔드포인트를 사용하면 가능한 한 쉽게 월간 시간을 최대화하는 데 도움이 됩니다.*

## **매개변수**

POST 요청에 다음 매개변수가 필요합니다:

* **데이터:** 다음 필드를 포함하는 딕셔너리:
  * **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 키
* 500
  * 서버 측 오류 응답