Moderations API¶

Classify content for harm with Amazon Bedrock Guardrails, inline guardrail checks (no guardrail resource needed), or Amazon Comprehend toxicity detection through an OpenAI-compatible Moderations interface.

Why Choose the Moderations API?¶

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¶

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

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

Guardrail checks (InvokeGuardrailChecks) are available in a limited set of AWS regions only (currently us-east-1, us-east-2, us-west-2, eu-west-2, eu-north-1, ap-northeast-1, and ap-southeast-2): calls run in the configured Bedrock regions that offer the operation, in priority order with multi-region failover, and the backend is unavailable when none of them does.

Category Mapping¶

Amazon 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 Bedrock Guardrail Checks — the inline contentFilter check uses the same five-category mapping as guardrail content policy filters, but reports each category's severity score (0.0 to 1.0 in 0.2 increments) directly in category_scores. A category — and the input — is flagged when its score reaches 0.5.

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. Comprehend's DetectToxicContent API is always called with the English language code, regardless of the input's actual language.

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 resource model (guardrail checks and Comprehend are text-only).

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, once for every policy the guardrail applies, each at that policy's own rate; see Amazon Bedrock pricing. No Bedrock model invocation is involved. The units AWS reports per policy appear in usage logs and cost tracking as text_units and input_images, under one model per applied policy:

  Model	Policy
  amazon.bedrock-runtime-guardrail-content	Content filters (text_units, and input_images for image content)
  amazon.bedrock-runtime-guardrail-topic	Denied topics
  amazon.bedrock-runtime-guardrail-word	Word filters
  amazon.bedrock-runtime-guardrail-sensitive-information	Sensitive information (paid entity types)
  amazon.bedrock-runtime-guardrail-sensitive-information-free	Sensitive information (free entity types)
  amazon.bedrock-runtime-guardrail-contextual-grounding	Contextual grounding
  amazon.bedrock-runtime-guardrail-automated-reasoning	Automated reasoning

  A guardrail applying several policies therefore produces several usage entries for one request, and its cost is their sum. - Guardrail checks — AWS bills per text unit and per requested check; the gateway requests the contentFilter check only. Billed text units appear in usage logs and cost tracking as text_units under the amazon.bedrock-runtime-guardrail-checks model. - 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.