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.

At a glance¶

• Three backends behind one endpoint: your own Bedrock guardrail (categories, thresholds, denied topics, word filters and sensitive-information policies configured in AWS), inline guardrail content filter checks, or Amazon Comprehend toxicity detection.
• Works out of the box. Guardrail checks and Comprehend need no setup at all, so /v1/moderations answers on any deployment, with or without a guardrail configured.
• OpenAI model names are aliases. omni-moderation-latest and text-moderation-latest resolve to an AWS backend, so an existing integration changes its base URL and nothing else.
• Text and images. Every element of an input array is classified independently and gets its own entry in results; PNG and JPEG images are classified by guardrail-resource models.
• Classifications run in your own AWS account — no traffic to third-party endpoints.
• Differs from OpenAI: only the five categories with an AWS counterpart are populated, and scores come back at the backend's own granularity rather than as continuous confidences on every backend.

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

Endpoints¶

Feature compatibility¶

Models¶

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.

Working with the Moderations API¶

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.

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.

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.

Limits and behaviour to know¶

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.

model names an exact value from Selecting the Model: this route chooses the classification model before the request is examined, so a wildcard pattern is rejected, unlike on the routes that generate a response.

Guardrail checks moderation calls the bedrock:InvokeGuardrailChecks IAM action; see IAM Permissions. A deployment without that permission keeps working: where guardrail checks are only reached as the default omni-moderation-* resolution, an AccessDenied response degrades the request to Comprehend toxicity detection and records a warning in the log. A request that names amazon.bedrock-runtime-guardrail-checks explicitly is not degraded.

Request headers¶

The Amazon Bedrock guardrail headers select the guardrail this endpoint classifies with. All headers are optional.

Content Safety (Guardrails)¶

Both headers are honoured only when AWS_BEDROCK_ALLOW_GUARDRAIL_OVERRIDE is enabled — otherwise the server guardrail applies, as described under Selecting the model. X-Amzn-Bedrock-Trace is accepted but has no effect on this route — categories and scores are read from the guardrail's assessments, which are always returned.

Example with headers:

curl -X POST "$BASE/v1/moderations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id" \
  -H "X-Amzn-Bedrock-GuardrailVersion: 1" \
  -d '{
    "input": "Some text to classify"
  }'

Try it¶

Classify one string:

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

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"]}
    }
  ]
}

Classify text and an image together:

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"}}
    ]
  }'

Next steps¶

Next: Guardrails configuration · Chat Completions API · Responses API · Model pricing