Perspective API alternative: migrate before December 31, 2026
Google Jigsaw is shutting down Perspective API on December 31, 2026, with no migration path. CleanMod is a Perspective API replacement that speaks the same comments:analyze format, so you change the URL and the key and keep the rest of your code. This guide covers the code changes, what's different, and how to check your thresholds before you cut over.
Migration in three steps
Step 1
Get a CleanMod API key
Create a free account and generate a key in the dashboard.
Step 2
Change the URL and key
Replace
commentanalyzer.googleapis.comwithcleanmod.dev(or the discovery URL, if you use Google's client libraries).Step 3
Re-check thresholds
Scores differ from Perspective's. Compare on a sample of your own comments and adjust your cut-offs (how).
Before and after code
The endpoint is POST https://cleanmod.dev/v1alpha1/comments:analyze. CleanMod accepts the key as ?key= (like Perspective), Authorization: Bearer, x-goog-api-key or x-api-key.
curl
curl -X POST \
"https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze?key=$GOOGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"comment": { "text": "What kind of idiot name is foo?" },
"languages": ["en"],
"requestedAttributes": { "TOXICITY": {}, "INSULT": {} }
}'curl -X POST \
"https://cleanmod.dev/v1alpha1/comments:analyze" \
-H "Authorization: Bearer $CLEANMOD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"comment": { "text": "What kind of idiot name is foo?" },
"languages": ["en"],
"requestedAttributes": { "TOXICITY": {}, "INSULT": {} }
}'
# Also works, if you can't change how the key is sent:
# "https://cleanmod.dev/v1alpha1/comments:analyze?key=$CLEANMOD_API_KEY"We recommend the Authorization header. Keys in a ?key= query string tend to end up in proxy, load balancer and hosting logs.
Node.js (googleapis)
const { google } = require("googleapis");
const DISCOVERY_URL =
"https://commentanalyzer.googleapis.com/$discovery/rest?version=v1alpha1";
const client = await google.discoverAPI(DISCOVERY_URL);
const res = await client.comments.analyze({
key: process.env.GOOGLE_API_KEY,
resource: {
comment: { text: "What kind of idiot name is foo?" },
requestedAttributes: { TOXICITY: {} },
},
});
console.log(res.data.attributeScores.TOXICITY.summaryScore.value);const { google } = require("googleapis");
const DISCOVERY_URL =
"https://cleanmod.dev/$discovery/rest?version=v1alpha1";
const client = await google.discoverAPI(DISCOVERY_URL);
const res = await client.comments.analyze({
key: process.env.CLEANMOD_API_KEY,
resource: {
comment: { text: "What kind of idiot name is foo?" },
requestedAttributes: { TOXICITY: {} },
},
});
console.log(res.data.attributeScores.TOXICITY.summaryScore.value);Only the discovery URL and the key change. The discovery document CleanMod serves points the client at cleanmod.dev.
Node.js (fetch)
const res = await fetch(
"https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze?key=" +
process.env.GOOGLE_API_KEY,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
comment: { text: "What kind of idiot name is foo?" },
requestedAttributes: { TOXICITY: {} },
}),
}
);
const data = await res.json();const res = await fetch(
"https://cleanmod.dev/v1alpha1/comments:analyze",
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer " + process.env.CLEANMOD_API_KEY,
},
body: JSON.stringify({
comment: { text: "What kind of idiot name is foo?" },
requestedAttributes: { TOXICITY: {} },
}),
}
);
const data = await res.json();Python (google-api-python-client)
from googleapiclient import discovery
client = discovery.build(
"commentanalyzer",
"v1alpha1",
developerKey=GOOGLE_API_KEY,
discoveryServiceUrl="https://commentanalyzer.googleapis.com/$discovery/rest?version=v1alpha1",
static_discovery=False,
)
response = client.comments().analyze(body={
"comment": {"text": "What kind of idiot name is foo?"},
"requestedAttributes": {"TOXICITY": {}},
}).execute()from googleapiclient import discovery
client = discovery.build(
"commentanalyzer",
"v1alpha1",
developerKey=CLEANMOD_API_KEY,
discoveryServiceUrl="https://cleanmod.dev/$discovery/rest?version=v1alpha1",
static_discovery=False,
)
response = client.comments().analyze(body={
"comment": {"text": "What kind of idiot name is foo?"},
"requestedAttributes": {"TOXICITY": {}},
}).execute()Attribute mapping
Attribute names are unchanged. TOXICITY_EXPERIMENTAL, SEVERE_TOXICITY_EXPERIMENTAL, IDENTITY_ATTACK_EXPERIMENTAL, INSULT_EXPERIMENTAL, PROFANITY_EXPERIMENTAL and THREAT_EXPERIMENTAL return the same scores as their production counterparts.
| 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 |
Differences from Perspective
CleanMod matches Perspective's request and response format. These are the places where the behaviour isn't the same.
Scores are different numbers
English only, for now
LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE error, with a link to request the language. We add languages based on demand: tell us which ones you need.Span scores are per chunk, not per sentence
Language detection on very short text
languages and the comment is too short to detect (“lol”, “ok”), CleanMod scores it as English and returns detectedLanguages: ["und"] instead of an error. Send languages if you know them.Unsupported attributes
Unknown requested attribute error (or are dropped with dropUnsupportedAttributes): FLIRTATION, SPAM, ATTACK_ON_AUTHOR, ATTACK_ON_COMMENTER, INCOHERENT, INFLAMMATORY, LIKELY_TO_REJECT, OBSCENE, UNSUBSTANTIAL, the bridging attributes (AFFINITY_EXPERIMENTAL, COMPASSION_EXPERIMENTAL, …).Smaller details
- Only the
PROBABILITYscore type is supported, as on Perspective. context,sessionIdandcommunityIdare accepted and ignored.comments:suggestscoreis accepted and acknowledged, but nothing is stored and it doesn't count toward your quota. CleanMod doesn't train on your data.- Comments are limited to 20 KB, as on Perspective.
- Quotas are monthly, per plan, instead of Perspective's per-second quota. Going over returns HTTP 429
RESOURCE_EXHAUSTED. - The
perspective-api-clientnpm package hard-codes Google's URL and can't be pointed elsewhere without forking it. Switch to plainfetch(above) or the googleapis client instead.
How to validate before cutover
Perspective still works until December 31, 2026, so you can compare both on real traffic before you switch.
- 1
Run both in parallel
Keep calling Perspective as you do today, and also send each comment to CleanMod (in a background job, so it doesn't add latency). Store both sets of scores next to your moderation outcome.
- 2
Use a representative sample
A few hundred to a few thousand recent comments, including ones your moderators removed and ones they approved, in the languages you actually receive.
- 3
Re-pick your thresholds
For each attribute you act on, find the CleanMod score that gives you the same flag or block rate, or the same precision on comments your moderators removed, as your current Perspective threshold. Don't reuse the old numbers as they are.
- 4
Check languages and attributes
Look for LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE and Unknown requested attribute errors in the parallel run. Decide whether to drop those attributes, set dropUnsupportedAttributes, or handle those comments differently.
- 5
Switch, then keep watching
Change the URL and key in production, and keep an eye on flag rates for the first few days.
FAQ
›When does Perspective API shut down?
Google Jigsaw says Perspective API will remain active until December 31, 2026. After that, requests to commentanalyzer.googleapis.com will stop working.
›Is CleanMod a drop-in Perspective API replacement?
For the comments:analyze method, yes: same request fields, the same response format (attributeScores, summaryScore, spanScores, languages, clientToken) and Google-style errors with Perspective's messages. You change the base URL (or the discovery URL) and the API key. Scores, languages and a few details differ; see the differences section.
›Will my moderation thresholds still work?
Probably not exactly. CleanMod's scores don't match Perspective's numerically, so re-pick thresholds on a sample of your own comments, ideally by running both APIs in parallel before Perspective goes away.
›Which languages does CleanMod support?
English, for all seven attributes. Other languages return Perspective's LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE error. If you need another language, request it at cleanmod.dev/languages: we add languages based on demand and will email you when yours is ready.
›Is CleanMod affiliated with Google or Jigsaw?
No. CleanMod is an independent service. Perspective is a trademark of Google LLC.
›Do you store the comments I send?
By default CleanMod stores a hash of each comment, not the text. You can turn on short text previews for your logs in the dashboard. With doNotStore: true, only the hash is stored regardless of that setting.
›Can I call it from the browser?
CORS is enabled, but calling it from a browser exposes your API key. Call CleanMod from your backend.
›How much does it cost?
There's a free plan for testing and small sites, and paid plans for higher volume. See the pricing page.
Pricing details are on the pricing page. Full endpoint reference: Perspective-compatible API docs.
Start the parallel run today
Get a free CleanMod key and compare scores while Perspective is still running.
Get a free API key →