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

# 음성 수집 API

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

`POST` /voice/v1/ingest

## **설명**

음성 수집 엔드포인트는 사고 처리를 위해 오디오 파일을 수신하고 고유한 **audio\_id** 를 반환하여 파일 상태를 조회하고 성공 시 사고 결과를 식별합니다. 오디오 파일은 짧은 음성(예: 1-2문장)을 포함해야 하며 다음 요구 사항을 준수해야 합니다:

* **파일 형식**: WAV, OGG, MP3
* **크기 제한:** 최대 5MB

기술적 제약이 없다면 OGG는 오디오 품질 대비 가장 우수한 파일 압축을 제공하므로 권장 형식입니다. 연속 오디오 스트림을 다룰 때는 가벼운 [음성 활동 감지기](https://github.com/snakers4/silero-vad) 모델을 사용하여 비음성 구성 요소(예: 무음, 잡음)를 제거하고 수집을 통해 전송할 개별 음성 클립 세트를 생성해야 합니다. 이는 설정이 간단하며 수신/전송 비용을 크게 줄이고 지연 시간과 탐지 성능을 향상시킵니다. 필요 시 코드 스니펫이나 구현 도움을 위해 GGWP 담당자에게 문의하십시오.

## **매개변수**

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

* **데이터:** 위 요구 사항을 준수하는 오디오 파일 바이너리.
* **헤더**
  * **파일 이름**: 오디오 파일에 대한 설명자. 
    * 예시: `20230620_john123.wav`
  * **사용자 ID:** 오디오가 귀속되어야 하는 사용자. 감지된 오디오 사고는 사용자의 평판 점수와 프로필에 영향을 미칩니다.
    * 예시: `player10`
  * **세션 ID:** 오디오가 기록된 세션(예: 대화). 매치 기반 게임의 경우 이는 매치 ID가 되며 GGWP의 문맥 모델이 동일 세션 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 키.
  * (선택 사항) **사용자명:** 사용자가 선택한 친숙한 표시 이름 문자열. 이는 GGWP 대시보드에서 사용자 ID와 함께 표시되며, 없을 경우 사용자 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
  * 서버 측 오류 응답