> 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/api-docs-voice/standard-package/voice-ingestion-api.md).

# Voice Ingestion API

\[ Base URL: `api.ggwp.com`]

`POST` /voice/v1/ingest

## **Description**

The Voice Ingestion endpoint receives an audio file for incident processing and returns a unique **audio\_id** for querying file status and identifying incident results upon success. The audio file should contain short speech (e.g. 1-2 sentences) and must conform to the following requirements:

* **File format**: WAV, OGG, MP3
* **Size limit:** up to 5MB

Unless there are technical constraints, OGG is the recommended format offering the best file compression relative to audio quality. When working with continuous audio streams, a light [Voice-Activity Detector](https://github.com/snakers4/silero-vad) model should be used to remove non-speech components (e.g. silence, noise) and produce a set of isolated speech clips to send through ingestion. This is simple to set up, and greatly reduces ingress / egress costs while improving latency and detection performance. Please contact your GGWP representative for a code snippet or implementation help as needed.

## **Parameters**

The following parameters are required in the POST request:

* **data:** the audio file binary conforming to the above requirements.
* **headers**
  * **file-name**: the descriptor for the audio file. 
    * Example: `20230620_john123.wav`
  * **user-id:** the user that the audio should be attributed to. Detected audio incidents will influence the user's reputation score and profile.
    * Example: `player10`
  * **session-id:** the session (e.g. conversation) during which the audio was logged. For match-based games, this will be the match ID, and allows GGWP's contextual models to use prior context from other user speech / messages in the same session-id.
    * Example: `match_unranked_20230620_12345`
  * **audio-time:** the audio's UTC start time in YYYY-MM-DD HH:MM:SS.SSS or YYYY-MM-DD HH:MM:SS format. This is used to determine the order of conversation in a session.
    * Example: `2023-06-20 10:24:23`
  * **x-api-key:** the GGWP API key corresponding to your organization and dashboard.
  * (OPTIONAL) **username:** string with the friendly display name picked by the user. This will be displayed alongside User ID in the GGWP dashboard, otherwise will default to the User ID.
    * Example: `john123`

## **Example Call**

**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

# Prepare the headers with user / session info
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"
}

# Read the audio file into memory
with open('/location/to/20230620_john123.wav', 'rb') as f:
    file_content = f.read()

# Send the POST request with data and headers
response = requests.post(
    'https://api.ggwp.com/voice/v1/ingest',
    headers=headers,
    data=file_content
)

# Examine the response
print(response.json())
```

## **Output**

* 200 response - successful operation

  ```bash
  {
      "audio_id": "01999d0b-cd00-4616-9d50-d9e1f6dddc60",
      "message": "Successfully uploaded file 20230620_john123.wav."
  }
  ```
* 400
  * Invalid input parameters
* 403
  * Invalid or missing API key
* 500
  * Server-side error response