> 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/chinese-simplified/api-wen-dang-yu-yin/biao-zhun-tao-can/yu-yin-cai-yang-api.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/5b74f51c46d6d25e4148b5a11a56ab046af9eb94" alt=""><figcaption><p>语音采样示意图</p></figcaption></figure>

***注意**: 采样总会降低审核效果，因为没有一种轻量方法能将安全音频与事件音频清晰分离。不过，如果你必须进行采样，通常是为了控制成本，那么使用此端点将帮助你尽可能轻松地最大化你的月度时长。*

## **参数**

POST 请求中需要以下参数：

* **数据：** 一个包含以下字段的字典：
  * **user\_id：** 正在被考虑进行采样的用户。
    * 示例： `player10`
  * **会话 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
  * 服务器端错误响应