CleanMod

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

  1. Step 1

    Get a CleanMod API key

    Create a free account and generate a key in the dashboard.

  2. Step 2

    Change the URL and key

    Replace commentanalyzer.googleapis.com with cleanmod.dev (or the discovery URL, if you use Google's client libraries).

  3. 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

Before: Perspective
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": {} }
}'
After: CleanMod
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)

Before: Perspective
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);
After: CleanMod
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)

Before: Perspective
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();
After: CleanMod
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)

Before: Perspective
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()
After: CleanMod
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 attributeWhat it scoresLanguages on CleanMod
TOXICITYRude, disrespectful or unreasonable commentsEnglish
SEVERE_TOXICITYVery hateful, aggressive or disrespectful commentsEnglish
IDENTITY_ATTACKNegative or hateful comments targeting identityEnglish
INSULTInsulting, inflammatory or negative comments toward a personEnglish
PROFANITYSwear words, curse words and other obscene languageEnglish
THREATIntent to inflict pain, injury or violenceEnglish
SEXUALLY_EXPLICITReferences to sexual acts or body partsEnglish

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

CleanMod scores comments with open Detoxify-family models (by Unitary), trained on Jigsaw's public comment datasets. They are not Google's production models, so the values won't match. For example, Perspective's own documentation example (“What kind of idiot name is foo? Sorry, I like your name.”) scores 0.86 TOXICITY on Perspective and 0.997 on CleanMod. Re-check your thresholds on a sample of your own comments before you switch (see how to validate).

English only, for now

All seven attributes are scored in English. Other languages, including the ones Perspective supported (German, Spanish, French and others), return Perspective's 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

For comments up to about 1,000 characters, you get one span covering the whole text. Longer comments are scored in chunks of about 1,000 characters, with one span per chunk; the summary score is the highest chunk score. Offsets are UTF-16, end-exclusive, like Perspective's.

Language detection on very short text

If you don't send 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

These return Perspective's 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 PROBABILITY score type is supported, as on Perspective.
  • context, sessionId and communityId are accepted and ignored.
  • comments:suggestscore is 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-client npm package hard-codes Google's URL and can't be pointed elsewhere without forking it. Switch to plain fetch (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. 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. 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. 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. 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. 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 →