> 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-jie-ru-api.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) 模型应当用于移除非语音成分（例如静音、噪声），并生成一组隔离的语音片段，通过 ingestion 发送。此设置简单，且在提升延迟和检测性能的同时，可大幅降低 ingress / egress 成本。如需代码片段或实现帮助，请联系您的 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 密钥。
  * （可选） **用户名：** 由用户选择的友好显示名称字符串。它将与用户 ID 一起显示在 GGWP 仪表板中，否则默认使用用户 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 密钥
* 500
  * 服务器端错误响应