A drop-in replacement for Perspective API's comments:analyze. Migrating? Start with the migration guide.
Base URL: https://cleanmod.dev. CORS is enabled, but call the API from your backend so your key stays private.
| POST | /v1alpha1/comments:analyze | Score a comment (Perspective's AnalyzeComment). |
| POST | /v1alpha1/comments:suggestscore | Accepted and acknowledged. Nothing is stored and it doesn't count toward quota. |
| GET | /$discovery/rest?version=v1alpha1 | Discovery document for Google's client libraries. Also at /discovery/v1/apis/commentanalyzer/v1alpha1/rest. |
Use a CleanMod API key from your dashboard. Any of these work:
Authorization: Bearer YOUR_API_KEY (recommended)?key=YOUR_API_KEY query parameter, as Perspective clients send itx-goog-api-key or x-api-key headerKeys in a query string tend to be recorded in proxy and hosting logs along the way, ours included, which is why the header is recommended. CleanMod keeps only a hash of your key and redacts keys from the moderation logs it writes.
| Field | Type | Notes |
|---|---|---|
| comment.text | string, required | The comment to score. Max 20 KB. |
| comment.type | enum | PLAIN_TEXT (default). HTML is rejected, as on Perspective. |
| requestedAttributes | map, required | Attribute name → config, e.g. {"TOXICITY": {}}. See the attribute table below. |
| requestedAttributes.*.scoreThreshold | number | Scores below this value are left out of the response. |
| requestedAttributes.*.scoreType | enum | PROBABILITY only (the default). |
| languages | string[] | ISO 639-1 / BCP-47 codes. If omitted, the language is detected. |
| doNotStore | boolean | Only a hash of the comment is stored, never the text. |
| spanAnnotations | boolean | Accepted. Span scores are always returned (see below). |
| clientToken | string | Echoed back in the response. |
| dropUnsupportedAttributes | boolean | Skip attributes that are unknown or not supported for the language instead of returning an error. |
| context, sessionId, communityId | — | Accepted and ignored. |
curl -X POST https://cleanmod.dev/v1alpha1/comments:analyze \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"comment": { "text": "friendly greetings from python" },
"requestedAttributes": { "TOXICITY": {} }
}'The same shape as Perspective's AnalyzeCommentResponse. All scores are probabilities between 0 and 1.
{
"attributeScores": {
"TOXICITY": {
"spanScores": [
{ "begin": 0, "end": 30, "score": { "value": 0.0113647086545825, "type": "PROBABILITY" } }
],
"summaryScore": { "value": 0.0113647086545825, "type": "PROBABILITY" }
}
},
"languages": ["en"],
"detectedLanguages": ["en"]
}summaryScore: the score for the whole comment.spanScores: one span for comments up to about 1,000 characters; longer comments get one span per ~1,000-character chunk, and the summary is the highest chunk score. Offsets are UTF-16 code units, end-exclusive. Spans are not per-sentence as on Perspective.languages: the languages you sent, or the detected one.detectedLanguages: only present when the language was detected. If the text was too short to detect, it is ["und"] and the comment is scored as English.clientToken: echoed if you sent one.The _EXPERIMENTAL versions of the six production attributes return the same scores. Other Perspective attributes (FLIRTATION, SPAM, the New York Times and bridging attributes) return Unknown requested attribute.
English only, for now. Comments in other languages, whether sent in languages or detected, return LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE. Request a language.
| Perspective attribute | What it scores | Languages on CleanMod |
|---|---|---|
| TOXICITY | Rude, disrespectful or unreasonable comments | English |
| SEVERE_TOXICITY | Very hateful, aggressive or disrespectful comments | English |
| IDENTITY_ATTACK | Negative or hateful comments targeting identity | English |
| INSULT | Insulting, inflammatory or negative comments toward a person | English |
| PROFANITY | Swear words, curse words and other obscene language | English |
| THREAT | Intent to inflict pain, injury or violence | English |
| SEXUALLY_EXPLICIT | References to sexual acts or body parts | English |
Scores come from open Detoxify-family models and don't match Perspective's numerically. Re-check your thresholds.
Errors use Google's error envelope with Perspective's documented messages:
{
"error": {
"code": 400,
"message": "Attribute INSULT does not support request languages: es",
"status": "INVALID_ARGUMENT",
"details": [{
"@type": "type.googleapis.com/google.commentanalyzer.v1alpha1.Error",
"errorType": "LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE",
"languageNotSupportedByAttributeError": {
"requestedLanguages": ["es"],
"attribute": "INSULT"
}
}, {
"@type": "type.googleapis.com/google.rpc.Help",
"links": [{
"description": "Request support for more languages",
"url": "https://cleanmod.dev/languages"
}]
}]
}
}| HTTP | status | message |
|---|---|---|
| 400 | INVALID_ARGUMENT | API key not valid. Please pass a valid API key. |
| 403 | PERMISSION_DENIED | Permission denied on the service. (no API key sent) |
| 400 | INVALID_ARGUMENT | Comment must be non-empty. |
| 400 | INVALID_ARGUMENT | Comment text too long. |
| 400 | INVALID_ARGUMENT | Missing requested_attributes |
| 400 | INVALID_ARGUMENT | Unknown requested attribute: <ATTR> |
| 400 | INVALID_ARGUMENT | Attribute <ATTR> does not support request languages: <langs> |
| 400 | INVALID_ARGUMENT | Requested score type <TYPE> is not supported by attribute <ATTR> |
| 400 | INVALID_ARGUMENT | Currently, only 'PLAIN_TEXT' comments are supported |
| 400 | INVALID_ARGUMENT | Invalid JSON payload received. … |
| 429 | RESOURCE_EXHAUSTED | Quota exceeded … (monthly plan quota) |
| 503 | UNAVAILABLE | The service is currently unavailable. |
The googleapis Node client and the Python discovery client build request URLs from a discovery document. Point them at CleanMod's:
https://cleanmod.dev/$discovery/rest?version=v1alpha1Full examples are in the migration guide.
comments:analyze call counts as one request toward your monthly plan quota (see pricing). Over quota returns HTTP 429 RESOURCE_EXHAUSTED.