Get started with Perspective API

1. Before you begin

Perspective API is a free API that helps you host better conversations online. The API uses machine learning (ML) to analyze a string of text and predict the perceived impact that it might have on a conversation.

In this codelab, you set up Perspective API.

Note: Perspective API is meant to make content moderation easier. It's not meant to completely replace the work of human decision-makers.

What you'll learn

• An AI-Powered approach to moderation that flags content the moment that it's created.

What you'll need

• A Google Account for access to Google Cloud
• Decent internet speed

2. Get started

To begin, you need a Google Cloud project to authenticate your API requests.

1. In Google Cloud Console, use an existing project.
2. If necessary, follow these steps to create a new project:

• Sign in with your Google Account.
• Open Cloud Console.
• Click Create Project or open the Select a Project menu and then click New Project in the dialog.
• Name your project and then click Create.

The project now appears in the drop-down menu.

Request API access

• To request API access, complete this form.

Within an hour, you should receive an email that confirms that you can view and enable the API in Google Cloud.

Note: If you don't receive an email within one business day, complete the form again or contact the support team.

3. Enable the API

• In the Cloud Console, navigate to the Perspective API overview page and then click Enable.

4. Generate the API key

1. In the navigation menu, click APIs & Services > Credentials > Create credentials > API Key.

Note: If you make requests from a client-side language like JavaScript, your API key is exposed to all visitors. It's strongly recommended that you proxy the request through a server and apply key restrictions so that the key is hidden from browsers and only your server can use that key. For more information, see an example of how to proxy the request through a server and more API key security recommendations.

Your API key should work in a few minutes, but it can take up to an hour. Until then, you may receive an error message.

2. Copy the API key.

5. Sample Requests

You can generate API client libraries with the Google API Client Libraries. These examples show you how to set up your API library with some of the most common languages.

1. Make an AnalyzeComment request.
2. Run one of these sample API calls to get scores directly from Perspective API.

The AnalyzeComment method issues an API request to analyze the comment.text field for the requestedAttributes, in this case the TOXICITY model.

3. Paste your API key in the API_KEY field.

If you prefer, you can leverage the doNotStore flag to ensure that all submitted comments are automatically deleted after scores are returned.

4. Read the API reference documentation for details on all of the request and response fields, as well as the available values for requestedAttributes.

There are experimental attributes, such as OBSCENE, ATTACK_ON_COMMENTER, and SPAM that you may also use.

Python

This sample request and response uses the Python version of the Google API Client Libraries.

1. Install the Python client library.
2. Run these commands:

You should see something like this output:

Your friendly greeting received a low toxicity score.

Node.js

This sample request and response uses the Node.js version of the Google API Client Libraries.

1. Install the Node.js client library or install the npm package googleapis.
2. Run these commands:

You should see something like this output:

cURL

This sample request and response uses the cURL command. This command should work for most MacOS and Linux users. You may need to install cURL to run this command.

• Replace YOUR_KEY_HERE with your API key.

In this response, the attributeScores.TOXICITY.summaryScore.value field gives the toxicity model's score for the comment. The comment received a score of 0.9 out of 1.0.

6. Congratulations

You got Perspective API up and running!

Learn more

• The Perspective API website contains more information about the API, including case studies.
• The Perspective API developers website contains more information on attributes, languages, and methods. If you want to get started quickly, the Methods page describes how to use the AnalyzeComment and SuggestCommentScore methods.