INTEGRATION GUIDE · BETA · SOURCE CHECKED 16 NOV 2026

Migrate Python from the Perspective API (before 31 Dec 2026)

Perspective-shaped requests, independent scores. Change the connection, then validate the moderation decisions.

Google’s Perspective API notice gives 31 December 2026 as the shutdown date. Plan and test your migration before then.

1. Prepare a staging copy

Save the integration version, settings, current thresholds and old scores before changing providers. Create a Decision Models key in the dashboard; store it only on your server. Examples use environment variables, never real keys.

googleapiclient builds a service client from its discovery document. Its build API accepts discoveryServiceUrl and developerKey. Plain requests has no Perspective-specific endpoint or attribute defaults; your application chooses them.

2. Change the endpoint and key

googleapiclient

Replace the discovery URL and key together. The discovery document sets the API root; changing only developerKey still sends requests to the old host. Save this example as smoke_google.py.

import os
from googleapiclient import discovery
client = discovery.build(
    "commentanalyzer", "v1alpha1",
    developerKey=os.environ["DM_MODERATION_KEY"],
    discoveryServiceUrl="https://moderation.decisionmodels.io/$discovery/rest?version=v1alpha1",
    static_discovery=False)
result = client.comments().analyze(body={
    "comment": {"text": "Thank you for explaining."},
    "requestedAttributes": {"TOXICITY": {}}, "doNotStore": True
}).execute()
print(result["attributeScores"]["TOXICITY"]["summaryScore"]["value"])

Plain requests

Save this alternative as smoke_requests.py. Install google-api-python-client or requests in your project environment as appropriate.

import os, requests
response = requests.post(
    "https://moderation.decisionmodels.io/v1alpha1/comments:analyze",
    headers={"Authorization": "Bearer " + os.environ["DM_MODERATION_KEY"]},
    json={"comment": {"text": "Thank you for explaining."},
          "requestedAttributes": {"TOXICITY": {}}}, timeout=15)
response.raise_for_status()
print(response.json()["attributeScores"]["TOXICITY"]["summaryScore"]["value"])

Attributes and compatibility

The examples request only built-in TOXICITY. Neither general-purpose client chooses moderation attributes for you. Preserve the requestedAttributes map from your application and classify each name using the list below.

Built-in and experimental attribute names

Built-in: TOXICITY, IDENTITY_ATTACK, INSULT, PROFANITY, THREAT. Built-in does not mean score parity with Perspective.

Experimental, not evaluated and uncalibrated: SEVERE_TOXICITY, SEXUALLY_EXPLICIT, FLIRTATION, SPAM, ATTACK_ON_AUTHOR, ATTACK_ON_COMMENTER, INCOHERENT, INFLAMMATORY, LIKELY_TO_REJECT, OBSCENE, UNSUBSTANTIAL. Responses identify requested experimental attributes in X-DM-Experimental-Attributes. Unknown attributes return 400. Check the current attribute and language documentation before enabling automatic actions.

Re-tune the thresholds

These clients impose no moderation decision threshold. Existing thresholds live in your application or requestedAttributes scoreThreshold fields. Retrieve unfiltered scores while tuning: scoreThreshold can omit a score entirely, which is different from returning zero.

Use the migration tool with representative comments, their saved Perspective scores and optional human labels. Compare flag rates, flagged-set overlap and, where labels exist, precision and recall. Matching a flag rate does not guarantee the same flagged comments or accuracy. Tune each attribute and action separately; do not copy the old numbers into production without review.

3. Test and re-tune

With DM_MODERATION_KEY set privately, this smoke command should return HTTP 200 and a numeric attributeScores.TOXICITY.summaryScore.value between 0 and 1. It checks transport and response shape, not moderation quality.

curl --fail-with-body --max-time 15 \
  'https://moderation.decisionmodels.io/v1alpha1/comments:analyze' \
  -H "Authorization: Bearer $DM_MODERATION_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"comment":{"text":"Thank you for explaining."},"requestedAttributes":{"TOXICITY":{}},"doNotStore":true}'
python3 smoke_google.py
# Or, for the requests example:
python3 smoke_requests.py

Inspect the result structure and keep missing attributes as missing. Test your own retry, timeout and error handling; the two sample files are alternatives, not required consecutive API calls.

In staging, test benign, abusive, borderline, quoted and multilingual comments; compare actual queue or warning actions with human decisions. Also test invalid keys, untested-language warnings, 429 rate limits and a timeout. Keep a manual moderation fallback rather than interpreting a failed request as a safe score. Check limits and errors and plan quotas and request rates.

4. Roll out with a fallback

The discovery URL does not add Google’s other features. Google HTTP multipart batch transport is not implemented; call comments().analyze(...).execute() individually or adapt to the native /v1/moderate batch contract. A googleapiclient execute timeout depends on the configured HTTP transport; set a bounded transport timeout in your application.

Keep the saved version and settings so you can reverse this change. Before Google’s shutdown, you can restore the Google endpoint together with its Google key and old thresholds if that service remains available to your account. After shutdown, use a tested alternative or manual review. Never send a Decision Models key to the Google host, or a Google key to Decision Models.

Shared gaps: scores come from an independent model; sentence-level span annotations are unavailable (one whole-text span only). Only PLAIN_TEXT is accepted. Valid explicit language hints are accepted and echoed. Untested hints or detected languages carry X-DM-Language-Untested. Tested languages: English (5 attributes) and German (offensive-language proxy only). This is not evidence of language quality. Suggested-score feedback is acknowledged but not stored or used to train the model. See the full API contract.

Source notes

These instructions follow the linked source revisions, inspected on 16 November 2026. Your installed release may differ. Patches and examples are migration recipes, not upstream endorsements or a claim of an end-to-end verified integration.

googleapiclient build options · Replacement request contract