Migrating from Perspective API to Tisane API

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Why Migrate?

Google's Perspective API is being sunset in 2026 and will no longer accept requests after 2026. Tisane API is a natural language processing platform purpose-built for content moderation, offering comparable – and in many ways broader – coverage of problematic content types, with multi-language support, structured JSON responses, severity ratings, and explainability built in.

This guide covers everything you need to migrate your integration: account setup, request/response format changes, and a full attribute mapping table.

Step 1 – Create a Tisane Account and Obtain an API Key

1. Go to https://tisane.ai and sign up for a free account.
2. Log in and navigate to your account dashboard to retrieve your primary or secondary API key.
3. In every request, include your key as a header:

Ocp-Apim-Subscription-Key: YOUR_API_KEY

Note: No Google Cloud project is required. Tisane authentication is handled entirely via this subscription key header.

Step 2 – Understand the API Differences

Endpoint

Paradigm

The two APIs take a fundamentally different approach to content moderation:

• Perspective API returns a probability score (0.0–1.0) for each attribute you explicitly request. You define thresholds in your own logic to decide what to act on.
• Tisane API returns structured instances of problematic content under an abuse array, each with a type, severity level (low / medium / high / extreme), the offending text span, character offset, length, an optional explanation, and optional tags for sub-classification. You filter or act based on type and severity rather than numerical thresholds.

This means Tisane gives you richer, more actionable output out of the box, but it does require adapting your threshold-based logic to severity-based logic. Similar to Perspective's attributes, you also need to choose what types are relevant for you.

Step 3 – Rewrite Your Request

Perspective API Request (before)

POST https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze?key=YOUR_KEY

{
  "comment": {
    "text": "You are a complete idiot."
  },
  "requestedAttributes": {
    "TOXICITY": {},
    "INSULT": {},
    "PROFANITY": {}
  }
}

Tisane API Request (after)

POST https://api.tisane.ai/parse
Header: Ocp-Apim-Subscription-Key: YOUR_KEY

{
  "language": "en",
  "content": "You are a complete idiot.",
  "settings": {}
}

Key differences:

• Replace comment.text → content
• Add a language field (ISO 639-1 code, e.g. "en", "de", "fr")
• Remove requestedAttributes – Tisane returns all detected abuse types by default
• Add a settings object to configure output (optional but recommended)
• The format setting (e.g. "dialogue", "review", "alias") helps Tisane apply context-appropriate analysis

Step 4 – Rewrite Your Response Handling

Perspective API Response (before)

{
  "attributeScores": {
    "TOXICITY": {
      "summaryScore": { "value": 0.92, "type": "PROBABILITY" }
    },
    "INSULT": {
      "summaryScore": { "value": 0.88, "type": "PROBABILITY" }
    }
  }
}

You would typically check: if (score > 0.7) { flag(); }

Tisane API Response (after)

{
  "text": "You are a complete idiot.",
  "abuse": [
    {
      "sentence_index": 0,
      "offset": 0,
      "length": 24,
      "text": "You are a complete idiot.",
      "type": "personal_attack",
      "severity": "high",
      "explanation": "Calling someone an idiot"
    }
  ]
}

You would typically check: if (abuse !== undefined && /* check if the types you need were found */ ) { flag(); }

Mapping severity to your old thresholds (suggested equivalents):

While the severity thresholds do not indicate probability, they may be used to prioritize decision making like the Perspective score.

Step 5 – Attribute Mapping

The table below maps each Perspective API attribute to its closest Tisane equivalent. Because Tisane uses a category + severity model rather than per-attribute scores, some Perspective attributes map to a Tisane type + severity filter combination.

Production Attributes

Experimental and New York Times Attributes

Tisane-Only Abuse Types (No Perspective Equivalent)

These types are available in Tisane but have no Perspective API counterpart, giving you additional moderation coverage:

Step 6 – Language Support

Perspective API supports a limited set of languages per attribute (e.g. TOXICITY supports English, Spanish, French, German, Portuguese, Italian, Russian).

Tisane API supports 30+ languages with uniform abuse detection across all of them, including Arabic, Chinese (Simplified & Traditional), Japanese, Korean, Thai, Hebrew, Persian, Indonesian, and more. Set the language field to the appropriate ISO 639-1 code.

Tisane API features built-in automatic language identification.

Step 7 – Advanced Settings

Tisane exposes several optional settings that have no Perspective equivalent but are useful for fine-tuning moderation:

"settings": {
  "abuse": true,
  "format": "alias",           // Context hint: "dialogue", "review", "proofread", "alias", and more
  "snippets": true,            // Return matching text snippets
  "explain": true,             // Return human-readable explanations
  "sentiment": false           // Omit sentiment analysis
}

As Tisane does not store or log submitted text, Perspective's doNotStore flag is not relevant. However, if you have particular data residency or security requirements, contact Tisane for the on-premises deployment option.

Quick Code Migration Examples

Python (before – Perspective)

import googleapiclient.discovery

client = googleapiclient.discovery.build("commentanalyzer", "v1alpha1", developerKey=API_KEY)

response = client.comments().analyze(body={
    "comment": {"text": text},
    "requestedAttributes": {"TOXICITY": {}, "INSULT": {}, "PROFANITY": {}}
}).execute()

toxicity_score = response["attributeScores"]["TOXICITY"]["summaryScore"]["value"]
if toxicity_score > 0.7:
    flag_content()

Python (after – Tisane)

import requests

headers = {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": API_KEY
}

response = requests.post("https://api.tisane.ai/parse", json={
    "language": "en",
    "content": text,
    "settings": {"abuse": True, "explain": True}
}, headers=headers)

data = response.json()
abuse_instances = data.get("abuse", [])

HIGH_SEVERITY = {"high", "extreme"}
should_flag = any(a["severity"] in HIGH_SEVERITY for a in abuse_instances)

if should_flag:
    flag_content()

JavaScript (before – Perspective)

const response = await fetch(
  `https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze?key=${API_KEY}`,
  {
    method: "POST",
    body: JSON.stringify({
      comment: { text },
      requestedAttributes: { TOXICITY: {}, INSULT: {} }
    })
  }
);
const data = await response.json();
const score = data.attributeScores.TOXICITY.summaryScore.value;
if (score > 0.7) flagContent();

JavaScript (after – Tisane)

const response = await fetch("https://api.tisane.ai/parse", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": API_KEY
  },
  body: JSON.stringify({
    language: "en",
    content: text,
    settings: { abuse: true }
  })
});
const data = await response.json();
const abuse = data.abuse || [];
const highSeverity = abuse.some(a => ["high", "extreme"].includes(a.severity));
if (highSeverity) flagContent();

Summary Checklist

• Sign up for Tisane and obtain API key
• Replace endpoint URL and authentication method
• Change comment.text → content, add language field
• Remove requestedAttributes from request body
• Add settings object with desired output flags
• Update response parsing from score-based to severity/type-based logic
• Map your threshold logic to Tisane severity levels (low, medium, high, extreme)
• Review Tisane-only types (e.g. criminal_activity, external_contact) for additional coverage
• Test with representative content samples across all languages you support
• Complete migration before Perspective API end-of-service in 2026