AI AWS Content Moderation Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing sensitive parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

• comprehend — object · required

  AWS Comprehend configurations.

  • access_key_id — string · required

    AWS access key ID.

  • secret_access_key — string · required

    AWS secret access key. The value is encrypted with AES before being stored in etcd.

  • region — string · required

    AWS region.

  • endpoint — string · optional

    AWS Comprehend service endpoint. If not set, defaults to https://comprehend.{region}.amazonaws.com.

  • ssl_verify — boolean · optional · default: true

    If true, enable TLS certificate verification.

• moderation_categories — object · optional

  Key-value pairs of moderation category and their corresponding threshold.

  In each pair, the key should be one of the PROFANITY, HATE_SPEECH, INSULT, HARASSMENT_OR_ABUSE, SEXUAL, or VIOLENCE_OR_THREAT; and the threshold value should be between 0 and 1 (inclusive).

• moderation_threshold — number · optional · default: 0.5

  Valid values: between 0 and 1 inclusive

  Overall toxicity threshold. A higher value means more toxic content allowed.

  This option differs from the individual category thresholds in moderation_categories. For example, if moderation_categories is set with a PROFANITY threshold of 0.5, and a request has a PROFANITY score of 0.1, the request will not exceed the category threshold. However, if the request has other categories like SEXUAL or VIOLENCE_OR_THREAT exceeding the moderation_threshold, the request will be rejected.

• check_request — boolean · optional · default: true

  If true, moderate request content.

  Introduced in API7 Enterprise 3.9.16 and 3.10.3, and APISIX 3.18.0.

• deny_code — integer · optional · default: 200

  Valid values: between 200 and 599 inclusive

  HTTP status code returned when flagged traffic is denied before response headers are sent. The default 200 returns a provider-compatible refusal; set a 4xx value to expose moderation as an HTTP error. After streaming starts, the status cannot be changed.

  Introduced in API7 Enterprise 3.9.16 and 3.10.3, and APISIX 3.18.0.

• deny_message — string · optional

  Message returned when request or response content is denied. If unset, the plugin returns the threshold failure reason.

  Introduced in API7 Enterprise 3.9.16 and 3.10.3, and APISIX 3.18.0.

• fail_mode — string · optional · default: skip

  Valid values: skip, warn, or error

  Behavior when the plugin receives a request it cannot moderate, such as non-AI traffic on a Consumer binding or a request that did not pass through AI Proxy. With skip, the request passes unchecked. With warn, it passes unchecked and a warning is logged. With error, the plugin rejects it with the applicable HTTP 400 or 500 response. None of these outcomes means moderation succeeded.

  Introduced in API7 Enterprise 3.9.14 and APISIX 3.18.0.

• request_check_roles — array[string] · optional · default: ["user", "tool", "system", "assistant"]

  Valid values: user, assistant, system, or tool

  Message roles to moderate on the request side. user, tool, and assistant follow request_check_mode; system is checked on every request because system content can be affected by malicious tool-call arguments. assistant messages are client-supplied conversation history, so they are moderated by default as well.

  Selecting system also covers developer messages, which is the role OpenAI uses in place of system on newer models and on the Responses API. There is no separate developer entry.

  Tool-result moderation applies to OpenAI-compatible formats where tool output is represented as a distinct tool role or item.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• request_check_mode — string · optional · default: all

  Valid values: all or last

  Which messages of the selected roles are moderated. With all, every message of a selected role is checked. With last, only the latest consecutive block of selected-role messages is checked. The system role is unaffected and is always checked when selected.

  Selecting assistant together with last widens the block that is considered latest, because assistant turns no longer end it.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• request_check_length_limit — integer · optional · default: 1000

  Valid values: between 4 and 1024 inclusive

  Maximum number of bytes of request content per Amazon Comprehend text segment. Longer content is split across several segments so that it is moderated in full instead of being truncated.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• check_response — boolean · optional · default: false

  If true, moderate the content of the LLM response in addition to the request. A non-streaming response is moderated before it is returned and fails closed with HTTP 500 if Comprehend cannot score it. A streaming response is moderated according to stream_check_mode; after bytes are sent, provider failures are logged and the remaining stream passes without a verdict.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• response_check_length_limit — integer · optional · default: 1000

  Valid values: between 4 and 1024 inclusive

  Maximum number of bytes of response content per Amazon Comprehend text segment. Longer content is split across several segments.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• stream_check_mode — string · optional · default: final_packet

  Valid values: final_packet or realtime

  How a streaming response is moderated when check_response is enabled. With final_packet, the assembled response is moderated once and the last chunk is annotated with its risk level. With realtime, batches are moderated while the response streams, and the remainder of the stream is replaced with the denial message as soon as a batch is flagged.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• stream_check_cache_size — integer · optional · default: 128

  Valid values: greater than or equal to 1

  Maximum number of characters accumulated per moderation batch in realtime mode. A smaller value detects harmful content earlier at the cost of more moderation calls.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• stream_check_interval — number · optional · default: 3

  Valid values: greater than or equal to 0.1

  Number of seconds between batch checks in realtime mode.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• timeout — integer · optional · default: 10000

  Valid values: greater than or equal to 1

  Timeout in milliseconds for a request to Amazon Comprehend.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• keepalive — boolean · optional · default: true

  If true, keep the connection to Amazon Comprehend alive so that it is reused across the moderation calls of a request instead of being reopened for each of them.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.

• keepalive_timeout — integer · optional · default: 60000

  Valid values: greater than or equal to 1000

  Idle time in milliseconds after which a pooled connection to Amazon Comprehend is closed.

  Introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0.