> 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-2/standard-package/api.md). # 이미지 모더레이션 API \[ 기본 URL: `api.ggwp.com`] `POST` /image/v1/moderate ## **설명** 이미지 검토 엔드포인트는 입력 이미지와 구성 가능한 옵션 목록을 받아, 지원되는 카테고리 목록과 그에 대응하는 플래그 및 전체 심각도를 반환합니다. ### **처리 모드** 다양한 품질 및 성능 요구 사항을 지원하기 위해 Image API는 아래에 언급된 두 가지 처리 모드를 제공합니다. 두 모드는 동일한 카테고리를 사용하지만, 카테고리 심각도에 대한 구성 가능한 설정이 다르며 지연 시간과 분석 깊이가 다릅니다. 이 구성을 다음을 통해 전달할 수 있습니다. `x-api-processing-mode` 헤더와 함께 `x-api-processing-mode:quality/performance` **품질 모드(기본값)** GGWP의 전체 모델을 실행하여 최대 감지 정확도와 카테고리 전반의 보다 세분화된 심각도 범위를 제공합니다. 지원 파일 형식: JPG, JPEG, PNG, GIF, WEBP * **지연 시간:** 중앙값 약 1000\~1200ms. * **카테고리 범위:** 헤더 섹션에 언급된 각 카테고리에 대해 다른 심각도 구성 설정을 사용하여 더 세분화된 심각도 수준을 지원합니다. * **적합한 용도:** 더 엄격한 안전 정책을 가진 커뮤니티나, 유해한 이미지가 검토를 통과하는 위험을 최소화하는 것이 중요한 더 어린 대상에게 적합합니다. 지연 시간이 덜 중요한 오프라인 검사에도 유용합니다. **성능 모드** Image API가 지원하는 핵심 카테고리를 계속 포함하면서 낮은 지연 시간에 최적화된 간소화된 모델을 사용합니다. 지원 파일 형식: JPG, JPEG, PNG. * **지연 시간:** 중앙값 약 150\~200ms. * **카테고리 범위:** Headers 섹션에 언급된 카테고리 전반의 표준 범위를 지원합니다. * **적합한 용도:** 빠른 응답 시간이 필요한 실시간 이미지 검토 및 대규모 워크플로에 적합합니다. ## **헤더** ***참고:** 온보딩 중에 구성 설정을 GGWP와 별도로 공유한 경우 이 섹션은 필요하지 않습니다.* ***품질 모드:*** 다음 헤더 옵션을 사용하면 요청마다 검토 카테고리를 사용자 지정할 수 있습니다. 기본적으로 모든 카테고리는 다음으로 설정됩니다. **높음**: * `explicit_nudity`: off/low/medium/high * `non_explicit_nudity`: off/low/medium/high * `hate_imagery`: off/low/medium/high * `violence`: off/low/medium/high * `gore`: off/low/medium/high * `weapons`: off/low/medium/high * `alcohol_drugs`: off/low/medium/high * `gambling`: off/low/medium/high * `profanity`: off/low/medium/high 이 설정은 다음을 통해 전달할 수 있습니다. `x-api-config` 헤더에서 **base64로 인코딩된 JSON 객체**. #### 예시 `config.json` ```json { "non_explicit_nudity": "high", "gambling": "off", "violence": "low" } ``` base64로 변환: {% code overflow="wrap" %} ```bash $ base64 config.json ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogImhpZ2giLAogICJnYW1ibGluZyI6ICJvZmYiLAogICJ2aW9sZW5jZSI6ICJsb3ciCn0= ``` {% endcode %} ***성능 모드:*** 다음 헤더 옵션을 사용하면 요청마다 검토 카테고리를 사용자 지정할 수 있습니다. 기본적으로 모든 카테고리는 다음으로 설정됩니다. **켜짐**: * `explicit_nudity`: on/off * `non_explicit_nudity`: on/off * `hate_imagery`: on/off * `violence`: on/off * `gore`: on/off * `weapons`: on/off * `alcohol_drugs`: on/off * `gambling`: on/off * `profanity`: on/off 이 설정은 다음을 통해 전달할 수 있습니다. `x-api-config` 헤더에서 **base64로 인코딩된 JSON 객체**. #### 예시 `config.json` ```json { "non_explicit_nudity": "off", "gambling": "off", "violence": "on" } ``` base64로 변환: {% code overflow="wrap" %} ```bash $ base64 config.json ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogIm9mZiIsCiAgImdhbWJsaW5nIjogIm9mZiIsCiAgInZpb2xlbmNlIjogIm9uIgp9 ``` {% endcode %} 요청 보내기: {% code overflow="wrap" %} ```bash curl --request POST 'https://api.ggwp.com/image/v1/moderate' \\ --header 'x-api-key: ' \\ --header 'x-api-config: ' \\ -F "file=@/path/to/example.jpeg" \\ -F "file_name=avatar123.jpeg" \\ -F "user_id=user989" ``` {% endcode %} ## **매개변수** `본문`: 다음으로 전송됨 `multipart/form-data` (UTF-8 인코딩). * **file**: 이진 이미지 파일입니다. 이미지는 다음 요구 사항을 충족해야 합니다. * **파일 형식**: JPG, JPEG, PNG, (GIF/WEBP는 품질 모드에서만 가능). * **크기 제한:** 최대 5MB. * **file\_name**: 이미지 파일에 대한 설명자. * 예시: `avatar123.jpeg` * **user\_id:** 이미지가 귀속될 사용자에 대한 고유 식별자입니다. 감지된 사건은 사용자의 평판 점수와 프로필에 영향을 미칩니다. * (선택 사항) **username**: 사용자가 선택한 친숙한 표시 이름입니다. GGWP 대시보드에 `user_id`와 함께 표시됩니다. `user_id` 제공되지 않으면 기본값이 사용됩니다. * (선택 사항) **session\_id**: 이미지가 공유된 대화, 경기 또는 채널의 고유 세션 식별자입니다. * (선택 사항) **timestamp**: 이미지가 공유된 UTC 시간으로, 다음 형식 중 하나입니다. `YYYY-MM-DD HH:MM:SS.SSS` 또는 `YYYY-MM-DD HH:MM:SS` 형식. 생략하면 서버가 현재 UTC 타임스탬프를 할당합니다. * (선택 사항) **image\_url**: 이미지와 연결된 URL(다음 중 하나여야 함 `http` 또는 `https`). 유효하면 대시보드에 표시됩니다. * (선택 사항) **metadata**: 사용자 지정 키/값 쌍의 JSON 문자열입니다. 5KB 이하여야 합니다. 허용된 키와 타입만 유효합니다. 플랫폼에 적용되는 키를 정의하려면 GGWP 담당자와 협업하세요. ## 예시 호출 **Bash** ```bash curl --request POST 'https://api.ggwp.com/image/v1/moderate' \\ --header 'x-api-key: ' \\ --header 'x-api-config: ' \\ --header 'x-api-processing-mode: quality' \\ -F "file=@/path/to/example.jpeg" \\ -F "file_name=avatar123.jpeg" \\ -F "user_id=user989" \\ -F "username=nlxdz" \\ -F "session_id=match_7765" \\ -F "timestamp=2025-10-10 16:49:02" \\ -F "image_url=https://cdn.example.com/uploads/avatar123.jpeg" ``` **Python** ```python import requests # API 엔드포인트 url = "https://api.ggwp.com/image/v1/moderate" # 인증 및 구성(카테고리를 위한 base64로 인코딩된 JSON 문자열) headers = { "x-api-key": "GGWP_API_KEY", "x-api-config": "", "x-api-processing-mode": "quality" } # 메타데이터 및 기타 매개변수 data = { "file_name": "avatar123.jpeg", "user_id": "player10", "username": "purpleCarrot", "session_id": "match_unranked_20230620_12345", "timestamp": "2025-10-10 16:49:02", "image_url": "https://cdn.example.com/uploads/avatar123.jpeg" } # 이미지 파일 files = { "file": open("/location/to/avatar123.jpeg", "rb") } # POST 요청 전송 response = requests.post(url, headers=headers, data=data, files=files) # 응답 확인 print(response.status_code) print(response.json()) ``` ## **출력** * 200 응답 - 성공적인 작업 ```json { "image_id": "20251010164902.482311-946bb8a9-0766-4c31-995a-d910da8531e5", "file_name": "avatar123.jpeg", "flag": true, "severity": "medium", "categories": { "explicit_nudity": true, "non_explicit_nudity": false, "hate_imagery": false, "violence": false, "gore": false, "weapons": false, "alcohol_drugs": false, "gambling": false, "profanity": true }, "timestamp": "2025-10-10 16:49:02" } ``` * 400 * 잘못되었거나 형식이 맞지 않는 요청입니다. 가능한 원인: * 필수 필드 누락(예: `file`, `file_name`, `user_id`) * 지원되지 않는 파일 형식(JPEG/JPG/PNG만 허용) * 파일 크기가 5MB 제한을 초과함 * 잘못된 타임스탬프 형식 * 메타데이터가 5KB를 초과하거나 허용되지 않은 키를 포함함 * 403 * 잘못된 API 키 또는 누락된 API 키 * 500 * 서버 측 오류 응답