Moderations API (OpenAI Compatible)¶

Classify content for harm with AWS Bedrock Guardrails or Amazon Comprehend toxicity detection through an OpenAI-compatible Moderations interface.

Why Choose Moderations?¶

Quick Start: Available Endpoint¶

Example request:

curl -X POST "$BASE/v1/moderations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Some text to classify"
  }'

Example response:

{
  "id": "modr-0f1b3c6e8d9a4b5c",
  "model": "abcd1234efgh:1",
  "results": [
    {
      "flagged": true,
      "categories": {"hate": true, "harassment": false, "...": false},
      "category_scores": {"hate": 0.75, "harassment": 0.25, "...": 0.0},
      "category_applied_input_types": {"hate": ["text"], "harassment": ["text"], "...": ["text"]}
    }
  ]
}

Feature Compatibility¶

Model Support¶

Both moderation models appear in the /v1/models and /search_models listings (mcp_tool=openai_moderation) with their OpenAI aliases.

AWS Bedrock Guardrails¶

Amazon Comprehend¶

Comparison¶

Selecting the Model¶

The model parameter selects the moderation model:

The server guardrail comes from AWS_BEDROCK_GUARDRAIL_IDENTIFIER / AWS_BEDROCK_GUARDRAIL_VERSION, or from the X-Amzn-Bedrock-GuardrailIdentifier / X-Amzn-Bedrock-GuardrailVersion request headers when AWS_BEDROCK_ALLOW_GUARDRAIL_OVERRIDE is enabled. Explicit guardrails in model also require that setting.

Guardrails are regional: a plain guardrail ID is applied in the primary Bedrock region, while an ARN selects its own region. Comprehend calls use AWS_COMPREHEND_REGION (with multi-region failover otherwise).

Category Mapping¶

AWS Bedrock Guardrails — content policy filters map to the OpenAI moderation categories:

Filter confidence levels become scores: NONE → 0.0, LOW → 0.25, MEDIUM → 0.5, HIGH → 0.75.

Every other guardrail policy — denied topics, word filters, sensitive information (PII), prompt attacks, contextual grounding — still contributes to the top-level flagged field whenever the guardrail intervenes, even though no individual category is set.

Amazon Comprehend — toxicity labels map to the OpenAI moderation categories, with their detection scores (0.0–1.0) reported directly:

An input is flagged when its overall toxicity or any label score reaches 0.5. Long texts are split into 1 KB segments and the highest score per category is kept.

With either model, OpenAI sub-categories without a counterpart (e.g. self-harm, sexual/minors) are always false.

Inputs¶

Each input element is classified independently and yields one entry in results:

• input as a string — one text classification.
• input as an array of strings — one classification per string.
• input as an array of parts — {"type": "text", "text": ...} and {"type": "image_url", "image_url": {"url": ...}} parts. Images must be PNG or JPEG, and require a guardrail model.

Each result's category_applied_input_types reflects the classified element's modality: ["text"] for every category on text inputs; on image inputs, ["image"] for the categories that support images and [] for the text-only ones.

An input array holds at most 2048 elements. Each element is classified — and billed — independently by a separate AWS call, so large arrays incur a proportional number of AWS calls.

MCP / AI agent usage: image_url.url accepts an HTTPS URL, data URI (data:<mime>;base64,<data>), base64 string, or S3 URI — no binary upload needed.

curl -X POST "$BASE/v1/moderations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.png"}}
    ]
  }'

Billing¶

• Guardrails — AWS bills per text unit and per image processed by the ApplyGuardrail API; see AWS Bedrock pricing. No Bedrock model invocation is involved.
• Comprehend — AWS bills toxicity detection per 100-character unit with a 3-unit minimum per call; see Amazon Comprehend pricing. Billed units appear in usage logs and cost tracking as comprehend_units under the amazon.comprehend-toxicity model.