How to use the masking and restoration API

Activate the service

Go to the service activation page for AI Guardrails and activate AI Guardrails.

Grant permissions to a RAM user

Before you access the API, grant permissions to a Resource Access Management (RAM) user. You can create an AccessKey pair for your Alibaba Cloud account and RAM users. When you call Alibaba Cloud APIs, the AccessKey pair is used for identity verification. For information about authorization and AccessKey creation, see the official Alibaba Cloud documentation.

Install and integrate the SDK

For the SDK of AI Guardrails, see the SDK reference.

Complete the masking and restoration configuration in the console

Before you call the API, you need to complete the custom data masking and masked data restoration configuration in the AI Guardrails console. Only after the configuration is complete can you use the corresponding capabilities through the API. For details, see Configure custom data masking and restoration.

1. Log on to the AI Guardrails console, and go to Protection Configuration.

2. Open the service configuration through the configuration entry of the target service.

3. Turn on Custom Data Masking. Custom Data Masking requires you to configure the custom masking content in advance. You can configure the masking content in Knowledge Base Management > Masking Library Management. Currently, at most one masking keyword library can be configured, and each library can contain up to 1,000 keywords. You can also turn on Sensitive Content detection as needed. Sensitive Content is the built-in PII sensitive content rule detection of the system, which also supports masking and restoration. Turn it on as needed.

4. Note that the Restoration configuration is turned off by default, and whether to enable restoration is controlled by a separate switch. You need to enable it yourself in the Sensitive Content or Custom Data Masking configuration item.

Common invocation conventions

For the API signature, common request parameters, and invocation method, see the Multimodal API integration guide.

How it works

The typical call chain for masking and restoration is as follows:

1. Inbound masking: Submit the user input text to the masking operation, and include the mapping identifier desensitizeId and the request action parameter maskingAction in the request. The operation returns the masked text.

2. Call the LLM: Send the masked text to the large language model for processing.

3. Outbound restoration: Submit the model output to the restoration operation, and pass back the same desensitizeId and the request action parameter maskingAction used in the masking request. Based on the mapping relationship, the operation restores the masked content to the original information.

Request parameters

ServiceParameters contains the following fields related to custom data masking and restoration.

{
  "Service": "query_security_check",
  "ServiceParameters": {
    "content": "My name is Zhang San, my ID card number is 110101199001011234, and my company is Alibaba Cloud.",
    "desensitizeId": "biz-2026-05-27-uuid-xxxx",
    "sessionId": "sess-xxxx",
    "accountId": "uid-xxxx",
    "maskingAction": "desensitize"
  }
}

{
  "Service": "response_security_check",
  "ServiceParameters": {
    "content": "<model response, which may contain placeholders>",
    "desensitizeId": "biz-2026-05-27-uuid-xxxx",
    "maskingAction": "restore"
  }
}

Response parameters

Examples

{
  "Code": 200,
  "Data": {
    "desensitizeId": "biz-conversation-001",
    "Suggestion": "mask",
    "Detail": [
      {
        "Type": "customDesensitization",
        "Level": "high",
        "Suggestion": "mask",
        "Result": [
          {
            "Label": "customDesensitization",
            "Level": "high",
            "Description": "Custom data masking",
            "Ext": {
              "Desensitization": "Zhang San [Mobile phone number (Chinese mainland)#4c01], my company is [Company-ASDDSNC#4c01]"
            }
          }
        ]
      },
      {
        "Type": "sensitiveData",
        "Suggestion": "mask",
        "Result": [
          {
            "Label": "1814",
            "Level": "S2",
            "Description": "Mobile phone number (Chinese mainland)",
            "Ext": {
              "Desensitization": "Zhang San [Mobile phone number (Chinese mainland)], my company is Alibaba Cloud"
            }
          }
        ]
      }
    ]
  }
}

{
  "Code": 200,
  "Data": {
    "desensitizeId": "biz-conversation-001",
    "Suggestion": "pass",
    "Detail": [
      {
        "Type": "customDesensitization",
        "Level": "none",
        "Suggestion": "pass",
        "Result": [
          {
            "Label": "customDesensitization",
            "Level": "none",
            "Description": "Custom data masking restoration",
            "Ext": {
              "Restoration": "Zhang San 18293921392, my company is Alibaba Cloud"
            }
          }
        ]
      }
    ]
  }
}

Code description

Code = 200 indicates business success, and other values indicate business errors. For general descriptions of status codes, see the Code description in the API integration guide.