> 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-image/standard-package/image-moderation-api.md). # Image Moderation API \[ Base URL: `api.ggwp.com`] `POST` /image/v1/moderate ## **Description** The Image Moderation endpoint receives an input image, along with a list of configurable options, and returns a list of supported categories with their corresponding flags and overall severity. ### **Processing Modes** To support different quality and performance requirements, the Image API offers two processing modes mentioned below. Both modes uses same categories, with different configurable settings for category severities and differ in latency and analytical depth. You can pass this configuration via the `x-api-processing-mode` header with `x-api-processing-mode:quality/performance` **Quality Mode (default)** Runs GGWP’s full model for maximum detection accuracy and more nuanced severity coverage across categories. Supports file formats across: JPG, JPEG, PNG, GIF, WEBP * **Latency:** \~1000–1200 ms median. * **Category Coverage:** Supports more nuanced severity levels per category mentioned in header section using different severity configuration settings. * **Best For:** Communities with stricter safety policies or younger audiences where it is important to minimize the risk of harmful images slipping through moderation. Also useful for offline checks where latency is less critical. **Performance Mode** Uses a streamlined model optimized for low latency while still covering the core categories supported by the Image API. Supports file formats across: JPG, JPEG, PNG. * **Latency:** \~150–200 ms median. * **Category Coverage:** Supports the standard set of coverage across categories mentioned in the Headers section. * **Best For:** Real-time Image moderation and high-volume workflows where fast response times are required. ## **Headers** ***Note:** This section is not required if your configuration settings were shared with GGWP separately during onboarding.* ***Quality mode:*** The following header options allow you to customize moderation categories per request. By default, all categories are set to **high**: * `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 You can pass these settings via the `x-api-config` header as a **base64-encoded JSON object**. #### Example `config.json` ```json { "non_explicit_nudity": "high", "gambling": "off", "violence": "low" } ``` Convert to base64: {% code overflow="wrap" %} ```bash $ base64 config.json ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogImhpZ2giLAogICJnYW1ibGluZyI6ICJvZmYiLAogICJ2aW9sZW5jZSI6ICJsb3ciCn0= ``` {% endcode %} ***Performance mode:*** The following header options allow you to customize moderation categories per request. By default, all categories are turned **on**: * `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 You can pass these settings via the `x-api-config` header as a **base64-encoded JSON object**. #### Example `config.json` ```json { "non_explicit_nudity": "off", "gambling": "off", "violence": "on" } ``` Convert to base64: {% code overflow="wrap" %} ```bash $ base64 config.json ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogIm9mZiIsCiAgImdhbWJsaW5nIjogIm9mZiIsCiAgInZpb2xlbmNlIjogIm9uIgp9 ``` {% endcode %} Make request: {% 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 %} ## **Parameters** `body`: Sent as `multipart/form-data` (UTF-8 encoded). * **file**: Binary image file. The image must conform to the following requirements: * **File format**: JPG, JPEG, PNG, (GIF/ WEBP with quality mode only). * **Size limit:** up to 5MB. * **file\_name**: Descriptor for the image file. * Example: `avatar123.jpeg` * **user\_id:** Unique identifier for the user the image should be attributed to. Detected incidents will influence the user’s reputation score and profile. * (OPTIONAL) **username**: Friendly display name chosen by the user. Shown in the GGWP dashboard alongside `user_id`. Defaults to `user_id` if not provided. * (OPTIONAL) **session\_id**: Unique session identifier for the conversation, match, or channel where the image was shared. * (OPTIONAL) **timestamp**: UTC time when the image was shared, in `YYYY-MM-DD HH:MM:SS.SSS` or `YYYY-MM-DD HH:MM:SS` format. If omitted, the server assigns the current UTC timestamp. * (OPTIONAL) **image\_url**: URL associated with the image (must be `http` or `https`). If valid, this will be displayed in the dashboard. * (OPTIONAL) **metadata**: JSON string of custom key/value pairs. Must be under 5KB. Only permitted keys and types are valid. Work with your GGWP representative to define which keys apply to your platform. ## Example Call **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 endpoint url = "https://api.ggwp.com/image/v1/moderate" # Authentication and config (base64-encoded JSON string for categories) headers = { "x-api-key": "GGWP_API_KEY", "x-api-config": "", "x-api-processing-mode": "quality" } # Metadata and other parameters 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" } # Image file files = { "file": open("/location/to/avatar123.jpeg", "rb") } # Send the POST request response = requests.post(url, headers=headers, data=data, files=files) # Examine the response print(response.status_code) print(response.json()) ``` ## **Output** * 200 response - successful operation ```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 * Invalid or malformed request. Possible causes: * Missing required fields (e.g., `file`, `file_name`, `user_id`) * File format not supported (only JPEG/JPG/PNG allowed) * File size exceeds 5MB limit * Invalid timestamp format * Metadata exceeds 5KB or contains disallowed keys * 403 * Invalid or missing API key * 500 * Server-side error response