Content Safety Service

Azure AI Content Safety detects harmful user-generated and AI-generated content in applications and services. Azure AI Content Safety includes text, image, and multimodal APIs which allows you to detect material that is potentially offensive, risky, or otherwise undesirable. We also have an Interactive Studio that allows you to view, explore and try out for detecting harmful content across different modalities.

For more detailed information, please refer to this product document (link).

Detect Groundedness

A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.

Select the testing console in the region where you created your resource:

Open API testing console

Request URL

Request headers

string
Media type of the body sent to the API.
string
Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Request body

The text groundedness detection request.

{
  "domain": "Generic",
  "task": "Summarization",
  "qna": {
    "query": "string"
  },
  "text": "string",
  "groundingSources": [
    "string"
  ],
  "reasoning": true,
  "llmResource": {
    "resourceType": "AzureOpenAI",
    "azureOpenAIEndpoint": "string",
    "azureOpenAIDeploymentName": "string"
  }
}
{
  "type": "object",
  "description": "The request of groundedness detection.",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain of the text for analysis. Allowed values: Medical, Generic.\nThis field is optional, with a default value of Generic.",
      "default": "Generic",
      "enum": [
        "Generic",
        "Medical"
      ],
      "x-ms-enum": {
        "name": "GroundednessDomain",
        "modelAsString": true,
        "values": [
          {
            "name": "Generic",
            "value": "Generic"
          },
          {
            "name": "Medical",
            "value": "Medical"
          }
        ]
      }
    },
    "task": {
      "type": "string",
      "description": "The task type for the text analysis. Type of task: QnA, Summarization.\nThis field is optional, with a default value of Summarization.",
      "default": "Summarization",
      "enum": [
        "Summarization",
        "QnA"
      ],
      "x-ms-enum": {
        "name": "GroundednessTask",
        "modelAsString": true,
        "values": [
          {
            "name": "Summarization",
            "value": "Summarization"
          },
          {
            "name": "QnA",
            "value": "QnA"
          }
        ]
      }
    },
    "qna": {
      "type": "object",
      "description": "The user's question input in a QnA scenario.\nThis field is optional, but if the task type is set to QnA, it becomes required.",
      "properties": {
        "query": {
          "type": "string",
          "description": "The user's question input in a QnA scenario.",
          "maxLength": 7500
        }
      },
      "required": [
        "query"
      ]
    },
    "text": {
      "type": "string",
      "description": "The specific text that needs to be checked.",
      "maxLength": 7500
    },
    "groundingSources": {
      "type": "array",
      "description": "Leverages a vast array of grounding sources to validate AI-generated text.\nLimit: Restrictions on the total amount of grounding sources that can be analyzed in a single request are 55K characters.",
      "items": {
        "type": "string"
      }
    },
    "reasoning": {
      "type": "boolean",
      "description": "A value indicating if the output includes an explanation for the identified groundedness.\nThis field is optional, with a default value of false."
    },
    "llmResource": {
      "type": "object",
      "description": "Connection details for the LLM resource. \nThis field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored.",
      "properties": {
        "resourceType": {
          "type": "string",
          "description": "LLM resource type. The default value is AzureOpenAI.",
          "default": "AzureOpenAI",
          "enum": [
            "AzureOpenAI"
          ],
          "x-ms-enum": {
            "name": "LLMResourceType",
            "modelAsString": true,
            "values": [
              {
                "name": "AzureOpenAI",
                "value": "AzureOpenAI",
                "description": "Azure OpenAI resource type."
              }
            ]
          }
        },
        "azureOpenAIEndpoint": {
          "type": "string",
          "description": "Endpoint for Azure OpenAI resource."
        },
        "azureOpenAIDeploymentName": {
          "type": "string",
          "description": "Deployment model name."
        }
      },
      "required": [
        "azureOpenAIEndpoint",
        "azureOpenAIDeploymentName"
      ]
    }
  },
  "required": [
    "text",
    "groundingSources"
  ]
}

Response 200

The request has succeeded.

{
  "ungroundedDetected": true,
  "ungroundedPercentage": 0.0,
  "ungroundedDetails": [
    {
      "text": "string",
      "offset": {
        "utf8": 0,
        "utf16": 0,
        "codePoint": 0
      },
      "length": {
        "utf8": 0,
        "utf16": 0,
        "codePoint": 0
      },
      "reason": "string"
    }
  ]
}
{
  "type": "object",
  "description": "The response of groundedness detection.",
  "properties": {
    "ungroundedDetected": {
      "type": "boolean",
      "description": "Indicates whether the text exhibits ungroundedness."
    },
    "ungroundedPercentage": {
      "type": "number",
      "format": "float",
      "description": "Specifies the proportion of the text identified as ungrounded, \nexpressed as a decimal between 0 and 1,\nwhere 0 indicates no grounded content and 1 indicates entirely grounded content.."
    },
    "ungroundedDetails": {
      "type": "array",
      "description": "Provides insights into ungrounded content with specific examples and percentages.",
      "items": {
        "type": "object",
        "description": "The detailed information about a text identified as ungroundedness.",
        "properties": {
          "text": {
            "type": "string",
            "description": "The grounded text."
          },
          "offset": {
            "type": "object",
            "description": "The offset when grounded text starts.",
            "properties": {
              "utf8": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index when encoding is UTF-8."
              },
              "utf16": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index when encoding is UTF-16."
              },
              "codePoint": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index with code point format."
              }
            },
            "required": [
              "utf8",
              "utf16",
              "codePoint"
            ]
          },
          "length": {
            "type": "object",
            "description": "The length of the grounded text.",
            "properties": {
              "utf8": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index when encoding is UTF-8."
              },
              "utf16": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index when encoding is UTF-16."
              },
              "codePoint": {
                "type": "integer",
                "format": "int64",
                "description": "Indicate the index with code point format."
              }
            },
            "required": [
              "utf8",
              "utf16",
              "codePoint"
            ]
          },
          "reason": {
            "type": "string",
            "description": "The explanation for detected ungroundedness, enhancing understanding.\nOnly when the 'reasoning' field in the input is set to true 'reason' field will be returned."
          }
        },
        "required": [
          "text",
          "offset",
          "length"
        ]
      },
      "x-ms-identifiers": []
    }
  },
  "required": [
    "ungroundedDetected",
    "ungroundedPercentage",
    "ungroundedDetails"
  ]
}

Response 500

An unexpected error response.

Code samples

@ECHO OFF

curl -v -X POST "https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}" 

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            var uri = "https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview&" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview");


            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Content-Type", "application/json");
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}


<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview&" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Content-Type","application/json");
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Content-Type' => 'application/json',
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('switzerlandnorth.api.cognitive.microsoft.com')
    conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('switzerlandnorth.api.cognitive.microsoft.com')
    conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://switzerlandnorth.api.cognitive.microsoft.com/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview')


request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json'
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body