Perspective Getting Started: Setup and First API Request (2026)

Getting started overview

To begin using the Perspective API, developers typically follow a structured process that involves setting up a Google Cloud project, enabling the Perspective API within that project, obtaining API credentials, and then constructing an API request. The API is designed to analyze text and provide scores for various attributes, such as toxicity, insult, and profanity, which can be used for content moderation purposes Perspective API documentation.

The core functionality revolves around the Comment Analyzer API, which takes text input and returns a JSON object containing attribute scores. For initial integration, developers often use client libraries available in languages such as Python and Node.js, which abstract the underlying HTTP request details Perspective API sample code.

This guide outlines the steps required to move from initial setup to a successful first API call, focusing on the practical aspects of obtaining credentials and executing a basic request.

Here is a quick reference for the getting started process:

Create an account and get keys

Accessing the Perspective API requires a Google Account and a Google Cloud project. If you do not have a Google Account, you can create a new Google Account. Once you have a Google Account, you will need to set up a project within the Google Cloud Console.

1. Create or Select a Google Cloud Project

Navigate to the Google Cloud Console. From the project selector dropdown at the top, you can either create a new project or select an existing one. Creating a new project provides a clean environment for your API integration.

2. Enable the Perspective API

After selecting your project, use the navigation menu to go to "APIs & Services" > "Library." In the API Library, search for "Perspective API" (also known as "Comment Analyzer API"). Click on the API and then click the "Enable" button enable Perspective API. This step ensures that your project has permission to make calls to the Perspective API.

3. Generate API Credentials

With the API enabled, you need to create credentials to authenticate your requests. Go to "APIs & Services" > "Credentials" in the Google Cloud Console Google Cloud Credentials management. Click "Create Credentials" and select "API Key."

• API Key: This is a simple credential that can be used for public data access. For server-side applications, it is crucial to restrict the API key to prevent unauthorized use. You can restrict the key by IP address or HTTP referrer to specify which applications can use it. Keep your API key secure and do not embed it directly in client-side code that could be publicly exposed.

Once generated, copy your API key. This key will be included in your API requests to authenticate with the Perspective API.

Your first request

With your API key in hand, you can now make your first request to the Perspective API. This example uses Python, leveraging the official client library, which simplifies the process of interacting with the API.

1. Install the Python Client Library

If you haven't already, install the Google API client library for Python:

pip install google-api-python-client

2. Write the Python Code

Create a Python file (e.g., perspective_test.py) and add the following code. Replace YOUR_API_KEY with the API key you generated.

import googleapiclient.discovery

def analyze_comment(text, api_key):
    client = googleapiclient.discovery.build(
        "commentanalyzer",
        "v1alpha1",
        developerKey=api_key,
        discoveryServiceUrl="https://commentanalyzer.googleapis.com/$discovery/rest?version=v1alpha1",
        static_discovery=False,
    )

    analyze_request = {
        'comment': {'text': text},
        'requestedAttributes': {'TOXICITY': {}}
    }

    response = client.comments().analyze(body=analyze_request).execute()
    return response

if __name__ == '__main__':
    api_key = "YOUR_API_KEY"  # Replace with your actual API key
    comment_to_analyze = "You are an idiot."
    result = analyze_comment(comment_to_analyze, api_key)
    print(result)

3. Run the Code

Execute the Python script from your terminal:

python perspective_test.py

4. Interpret the Response

A successful response will be a JSON object containing the analysis. For the example text "You are an idiot." and requesting TOXICITY, you might see output similar to this:

{
  "attributeScores": {
    "TOXICITY": {
      "summaryScore": {
        "value": 0.9234567,
        "type": "PROBABILITY"
      },
      "spanScores": [
        {
          "begin": 0,
          "end": 16,
          "score": {
            "value": 0.9234567,
            "type": "PROBABILITY"
          }
        }
      ]
    }
  },
  "languages": [
    "en"
  ]
}

The summaryScore.value field indicates the probability that the comment is toxic, with values closer to 1.0 indicating higher toxicity. The spanScores provide toxicity scores for specific segments of the text.

Common next steps

After successfully making your first request, consider these common next steps to further integrate and optimize your use of the Perspective API:

• Explore Additional Attributes: The Perspective API can analyze text for various attributes beyond toxicity, such as INSULT, PROFANITY, THREAT, and SEXUALLY_EXPLICIT. Experiment with requesting multiple attributes in a single call to get a more comprehensive content analysis Perspective API attribute list.
• Implement Error Handling: Integrate robust error handling into your application to manage API rate limits, invalid requests, and other potential issues. The API returns standard HTTP status codes and error messages that can guide your error handling logic.
• Secure Your API Key: For production environments, avoid hardcoding your API key directly into your application code. Instead, use environment variables or a secure configuration management system. Additionally, apply API key restrictions in the Google Cloud Console to limit its use to specific IP addresses or HTTP referrers. This is a standard security practice for cloud APIs, as highlighted in Google Cloud API key best practices.
• Monitor Usage: Regularly monitor your API usage in the Google Cloud Console to stay within your free tier limits and understand your billing. Usage metrics and dashboards provide insights into your request volume and response times.
• Review Pricing: Understand the Perspective API pricing model. While there is a free tier for up to 10,000 requests per month, subsequent usage is tiered, starting at $0.75 per 1,000 requests. Plan your usage according to your application's needs.
• Explore Client Libraries: If you are not using Python, investigate the official client libraries for other supported languages like Node.js, Java, or Go. These libraries streamline API interactions and often provide idiomatic ways to integrate the API into your codebase Perspective API client library examples.
• Consider Asynchronous Processing: For applications handling high volumes of comments, consider implementing asynchronous processing for API calls to avoid blocking your main application thread and improve responsiveness.

Troubleshooting the first call

When making your first API call, you might encounter common issues. Here are some troubleshooting steps:

• Invalid API Key: Double-check that you have copied the API key correctly and that there are no leading or trailing spaces. Ensure the API key you are using is associated with the Google Cloud project where the Perspective API is enabled.
• API Not Enabled: Verify that the "Comment Analyzer API" (Perspective API) is enabled for your Google Cloud project in the API Library. If it's not enabled, you will receive an error indicating that the service is unavailable.
• Billing Not Enabled: While there is a free tier, Google Cloud APIs often require a billing account to be linked to the project, even if you are operating within the free limits. Ensure your project has an active billing account Google Cloud billing account verification.
• Network Issues: Ensure your development environment has an active internet connection and is not blocked by a firewall from accessing commentanalyzer.googleapis.com.
• Incorrect Request Format: Review the API request body to ensure it matches the expected JSON structure outlined in the Perspective API reference documentation. Pay close attention to attribute names and their casing (e.g., TOXICITY instead of toxicity).
• Rate Limit Exceeded: If you are making many requests in a short period, you might hit rate limits. The Perspective API has default quotas. Check your project's quotas in the Google Cloud Console under "APIs & Services" > "Quotas" and request an increase if necessary.
• Client Library Version: Ensure your Google API client library is up to date. Outdated libraries might have bugs or lack support for recent API changes.
• Error Messages: Carefully read any error messages returned by the API. They often contain specific clues about what went wrong, such as "API key not valid" or "Requested attribute not supported."