This topic describes how to construct a request to call the Content Moderation API. This topic is intended for you if you initiate HTTP or HTTPS requests based on the API endpoint.

Note Content Moderation provides SDKs in multiple programming languages and supports third-party SDKs. You can use the SDKs without the need to construct API requests by yourself. For more information, see SDK overview.

Communication protocols

You can send requests over HTTP or HTTPS.

Request methods

All operations support the POST and GET methods.

Encoding

The request parameters and responses of all operations are encoded in UTF-8.

API request structure

Type Description Remarks
API endpoint The endpoint for the Content Moderation API. Example: http(https)://green.cn-shanghai.aliyuncs.com.
Common parameters The common parameters required in all API requests. For more information, see Common parameters.
Operation-specific parameters The parameters that are specific to each operation. For more information, see the definition of each operation.

API endpoint

To call the Content Moderation API to manage custom image libraries and custom text libraries, you must send a request to the following endpoint:
http(s)://green.cn-shanghai.aliyuncs.com
Notice Only the preceding endpoint is supported. Use the preceding endpoint to call the Content Moderation API in all regions of China. The server can automatically synchronize data if you initiate a request in a region other than the China (Shanghai) region.

Common parameters

Parameter Type Required Description
Action String Yes The operation that you want to perform. For more information, see List of operations by function.
AccessKeyId String Yes The AccessKey ID provided to you by Alibaba Cloud. The AccessKey is used to call API operations.
Signature String Yes The signature string of the current request. For more information, see Signature method.
SignatureMethod String Yes The encryption method of the signature string. Set the value to HMAC-SHA1.
SignatureVersion String Yes The version of the signature encryption algorithm. Set the value to 1.0.
SignatureNonce String Yes A unique, random number that is used to prevent replay attacks. We recommend that you use different numbers for different requests.
Timestamp String Yes The timestamp of the request. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Example: 2018-01-01T12:00:00Z.
Version String Yes The version number of the API. The value must be in the YYYY-MM-DD format. Set the value to 2017-08-23.
Format String No The format of the response parameters. Valid values:
  • json
  • xml. This is the default value.

Operation-specific parameters

Click an operation in the List of operations by function topic to query the specific parameters of the operation. For more information, see List of operations by function.

Signature method

You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Content Moderation implements symmetric encryption with an AccessKey pair to verify the identity of the request sender.

An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users that is similar to a logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

  1. Create a canonicalized query string.
    1. Arrange the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.
      Note If you use the GET method to send a request, the request parameters are included as a part of the request URL. The first parameter follows the question mark ( ?) in the URL, and the other parameters follow an ampersand ( &).
    2. Encode the request parameters and their values in UTF-8 based on RFC 3986. The following rules apply in the encoding process:
      • Uppercase letters, lowercase letters, digits, and some special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.
      • Other characters must be percent encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
      • Extended UTF-8 characters are encoded in the %XY%ZA… format.
      • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
        The preceding encoding method is similar to but slightly different from the application/x-www-form-urlencoded MIME-type encoding algorithm. If you use java.net.URLEncoder in the Java standard library, use percentEncode to encode request parameters and their values. In the encoded query string, replace the plus sign ( +) with %20, the asterisk ( *) with %2A, and %7E with a tilde ( ~). This way, you can obtain an encoded string that matches the preceding encoding rules.
        private static final String ENCODING = "UTF-8";
        private static String percentEncode(String value) throws UnsupportedEncodingException {
        return value ! = null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
        }
    3. Use equal signs (=) to connect the encoded request parameters and their values.
    4. Use ampersands (&) to connect the encoded request parameters. These parameters must be arranged in the same order as those in Step i.

    Then, a canonicalized query string (CanonicalizedQueryString) that follows the request structure is obtained.

  2. Create a string-to-sign from the encoded canonicalized query string.
    1. Create a string-to-sign (StringToSign). You can also use percentEncode to encode the canonicalized query string that is created in the previous step. Comply with the following rules to create a string-to-sign:
      StringToSign=
        HTTPMethod + "&" + //HTTPMethod: the HTTP method that is used to send a request, such as GET.
        percentEncode("/") + "&" + //percentEncode("/"): Encode the forward slash (/) in UTF-8 as %2F.
        percentEncode(CanonicalizedQueryString) //Encode the canonicalized query string created in Step 1.
    2. Calculate the HMAC-SHA1 value of StringToSign based on RFC 2104. The Java Base64 encoding method is used in this example.
      Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )
      Note When you calculate the signature, the key value that is specified by RFC 2104 is your AccessKey secret with an ampersand ( &) which has an ASCII value of 38.
    3. Encode the Signature parameter based on RFC 3986 and add it to the canonicalized query string.

Sample code

  • Example 1: Concatenate parameters

    The following example describes how to call the DescribeKeywordLib operation to query custom text libraries. Assume that AccessKeyID is set to testid and AccessKeySecret is set to testsecret.
    1. Create a canonicalized query string.
      AccessKeyId=testid&Action=DescribeKeywordLib&Format=XML&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&Timestamp=2016-02-23T12:46:24Z&Version=2014-05-26&ServiceModule=open_api
    2. Create a string-to-sign.
      GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeKeywordLib%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf%26SignatureVersion%3D1.0%26Timestamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26%26ServiceModule%3Dopen_api
    3. Calculate the signature. The key value that is used for calculation is testsecret& because AccessKeySecret is set to testsecret. The calculated signature is OLeaidS1JvxuMvnyHOwuJ+uX5qY=. The Java Base64 encoding method is used in this example.
      Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )
    4. Add Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D that has been encoded based on RFC 3986 to the URL in Step i.
      http://green.cn-shanghai.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeKeywordLib&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%253A46%253A24Z&ServiceModule=open_api

    You can use a browser or tools such as cURL and Wget to initiate an HTTP request based on the new URL. The HTTP request calls the DescribeKeywordLib operation to query custom text libraries.

  • Example 2: Use the standard library of the programming language

    The following example describes how to call the DescribeKeywordLib operation to query custom text libraries. Assume that AccessKeyID is set to testid and AccessKeySecret is set to testsecret, and all request parameters are placed in a Java Map<String, String> object.
    1. Predefine the encoding method.
      private static final String ENCODING = "UTF-8";
      private static String percentEncode(String value) throws UnsupportedEncodingException {
        return value ! = null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
      }
    2. Predefine the time format for the Timestamp parameter. Set the Timestamp parameter in the ISO 8601 format. The time must be in UTC+0.
      private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";
      private static String formatIso8601Date(Date date) {
        SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT);
        df.setTimeZone(new SimpleTimeZone(0, "GMT"));
        return df.format(date);
      }
    3. Create a request string.
      final String HTTP_METHOD = "GET";
      Map parameters = new HashMap();
      // Specify request parameters.
      parameters.put("Action", "DescribeKeywordLib");
      parameters.put("Version", "2017-08-23");
      parameters.put("AccessKeyId", "testid");
      parameters.put("Timestamp", formatIso8601Date(new Date()));
      parameters.put("SignatureMethod", "HMAC-SHA1");
      parameters.put("SignatureVersion", "1.0");
      parameters.put("SignatureNonce", UUID.randomUUID().toString());
      parameters.put("Format", "XML");
      parameters.put("ServiceModule", "open_api");
      // Arrange the request parameters.
      String[] sortedKeys = parameters.keySet().toArray(new String[]{});
      Arrays.sort(sortedKeys);
      final String SEPARATOR = "&";
      // Create a string-to-sign.
      StringBuilder stringToSign = new StringBuilder();
      stringToSign.append(HTTP_METHOD).append(SEPARATOR);
      stringToSign.append(percentEncode("/")).append(SEPARATOR);
      StringBuilder canonicalizedQueryString = new StringBuilder();
      for(String key : sortedKeys) {
      // Encode the key and value.
        canonicalizedQueryString.append("&")
        .append(percentEncode(key)).append("=")
        .append(percentEncode(parameters.get(key)));
      }
      // Encode the canonicalized query string.
      stringToSign.append(percentEncode(
        canonicalizedQueryString.toString().substring(1)));
    4. Calculate the signature. The key value that is used for calculation is testsecret&amp; because AccessKeySecret is set to testsecret. The calculated signature is OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D.
      // The following sample code demonstrates how to calculate the signature.
      final String ALGORITHM = "HmacSHA1";
      final String ENCODING = "UTF-8";
      key = "testsecret&";
      Mac mac = Mac.getInstance(ALGORITHM);
      mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
      byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
      String signature = new String(Base64.encodeBase64(signData));
      Encode the Signature parameter based on RFC 3986 and add the parameter to the URL. The following URL is obtained:
      http://green.cn-shanghai.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeKeywordLib&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%253A46%253A24Z
    5. Use browsers or tools such as cURL and Wget to send HTTP requests and obtain the response.

API response

Click an operation in the List of operations by function topic to query the response of the operation. For more information, see List of operations by function.