DocsICP FilingConsole
官方文档
首页

Moderation Agent synchronous detection API

更新时间：
复制 MD 格式
产品详情
我的收藏

You can use the Moderation Agent service to configure custom detection capabilities in the console and call the API to retrieve results. This guide explains how to integrate the synchronous Moderation Agent API.

Get started

  1. Register for an Alibaba Cloud account: Register now.

  2. Activate pay-as-you-go for Content Moderation: Activate the service. Activation is free, and you are automatically billed based on your API usage. For more information, see Billing.

  3. Create an AccessKey: Create an AccessKey. If you use an AccessKey from a RAM user, your root account must grant the AliyunYundunGreenWebFullAccess permission to that RAM user. For more information, see RAM authorization.

  4. Develop and integrate: Use an SDK to make API calls. For more information, see Moderation Agent service SDK reference.

API reference

Call this API to create a detection task. You can make direct calls by constructing HTTP requests or use prebuilt requests from the SDK. For more information, see Moderation Agent service SDK reference.

  • API operation: MultiModalAgent.

  • Supported regions and endpoints:

    Region

    Public endpoint

    Internal endpoint

    China (Shanghai)

    https://green-cip.cn-shanghai.aliyuncs.com

    https://green-cip-vpc.cn-shanghai.aliyuncs.com

  • Billing:

    This API is billable. Only requests with an HTTP status code of 200 are billed; requests that return other codes are not. For more information, see Billing.

  • Data requirements:

    • Text:

      • Text is limited to 2,000 characters per request.

    • Image:

      • A single request supports a maximum of one image.

      • Supported image formats include PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC (the longest side must be less than 8,192 pixels), GIF (only the first frame is processed), and ICO (only the last image is processed).

      • The image size cannot exceed 20 MB. The height or width cannot exceed 16,384 pixels, and the total number of pixels cannot exceed 167 million. For best detection results, use images with a resolution of at least 200x200 pixels.

      • The image must download within 3 seconds, or the request will time out.

    • Image-text multimodality:

      • The preceding text and image limits apply.

QPS limits

The QPS limit for a single user is 10 requests per second. Calls that exceed this limit are throttled, which may impact your business. Plan your calls accordingly. If you require a higher QPS limit, contact your account manager.

Debugging

Before integrating the API, you can use the Alibaba Cloud OpenAPI Portal to debug the Moderation Agent API online. You can view sample code and SDK dependencies to get an overview of how to use the API and its parameters.

Important

The online debugger makes API calls by using your logged-in account. These calls are billable.

Request parameters

The request body is a JSON object with the following fields:

Parameter

Type

Required

Example

Description

AppID

String

Yes

txt_check_agent_01

The application ID of the Moderation Agent. The system generates a unique AppId in the console when you create an agent, based on the selected modality. The supported modalities are:

  • Text: The format is txt_check_agent_xx. Example: txt_check_agent_01

  • Image: The format is img_check_agent_xx. Example: img_check_agent_01

  • Image-text multimodality: The format is img_txt_check_agent_xx. Example: img_txt_check_agent_01

ServiceParameters

JSONString

Yes

-

The parameter set for the moderation service, provided as a JSON string. For field descriptions, see Table 1. ServiceParameters.

Table 1. ServiceParameters

Parameter

Type

Required

Example

Description

content

String

No

Note

This parameter is required when the modality is Text or Image-text multimodality.

This is the text content to be moderated.

The text content to moderate. The text is limited to 2,000 characters per call.

images

JSONArray

No

Note

This parameter is required when the modality is Image or Image-text multimodality.

https://aliyun.com/240308/test001.jpg

The image content to moderate. A maximum of one image is allowed per request. For more information, see Table 2. images.

dataId

String

No

MultiModal****

The data ID of the object to moderate.

The ID can be a string of up to 128 characters in length that consists of uppercase letters, lowercase letters, digits, underscores (_), hyphens (-), and periods (.). You can use this ID to uniquely identify your business data.

Table 2. images

Parameter

Type

Required

Example

Description

imageUrl

String

Yes

http://www.aliyundoc.com/a.flv

The URL of the object to be moderated. Make sure that the URL is publicly accessible and does not exceed 2,048 characters in length.

Response data

Parameter

Type

Example

Description

RequestId

String

ABCD1234-1234-1234-1234-123****

The unique ID of the request, generated by Alibaba Cloud. Use this ID for troubleshooting.

Data

Object

-

The multimodal content moderation results.

Code

String

200

The status code, which matches the HTTP status code. For more information, see Status codes.

Message

String

OK

The response message for the request.

Table 1. Data

Parameter

Type

Example

Description

DataId

String

Multimodal0424***

The data ID of the moderated object.

Important

If you passed a DataId in the request, it is returned here.

RiskLevel

String

high

The risk level of the entire post. Valid values:

  • high: high risk

  • none: no risk detected

Result

JSONArray

-

The moderation results. For more information, see Table 2. Result.

Usage

Object

-

Call usage statistics. For more information, see Table 3. Usage.

Table 2. Result

Parameter

Type

Example

Description

Label

String

AdComplianceViolations

The risk label.

Note

  1. If a risk is detected, this field returns the detection label that you configured in the console. If multiple agents detect violations, all corresponding risk labels are returned.

  2. If no risk is detected, this field returns nonLabel.

Description

String

Ad Compliance Agent

A description of the risk label.

Note

  1. This field returns the name of the agent as configured in the console, such as "Ad Compliance Agent". This name is customizable in the console.

  2. If multiple agents are configured, a result object is returned for each agent.

Table 3. Usage

Parameter

Type

Example

Description

PromptLength

Integer

1039

The total character length of the prompts. If you call multiple agents, the system sums the prompt lengths. This parameter affects metering.

ContentLength

Integer

56

The character length of the text to be moderated. This parameter affects metering.

AgentDetail

JSON

-

Usage details for each agent. For more information, see the examples.

Examples

Request examples

  • Text modality

{
	"AppID": "txt_check_agent_01",
	"ServiceParameters": {
		"content": "This is the text content to be moderated.",
		"DataId": "data123***"
	}
}

  • Image modality

{
	"AppID": "img_check_agent_01",
	"ServiceParameters": {
		"images": [
			{
				"imageUrl": "https://aliyun.com/240308/test001.jpg"
			}
		],
		"DataId": "data123***"
	}
}

  • Image-text multimodality

{
	"AppID": "img_txt_check_agent_01",
	"ServiceParameters": {
		"content": "This is the text content to be moderated.",
		"images": [
			{
				"imageUrl": "https://aliyun.com/240308/test001.jpg"
			}
		],
		"DataId": "data123***"
	}
}

Response examples

  • When a risk is detected

{
	"Msg": "success",
	"Code": 200,
	"Data": {
		"DataId": "123****",
		"TaskId": "TASK1234-1234-1234-1234-123***",
		"Result": [
			{
				"Label": "CustomViolationLabelOne",
				"Description": "agent1"
			},
			{
				"Label": "CustomViolationLabelTwo",
				"Description": "agent2"
			}
		],
		"RiskLevel": "high",
		"usage": {
			"promptLength": 1379,
			"contentLength": 1376,
			"AgentDetail": {
				"agent1": {
					"promptLength": 789,
					"contentLength": 1376
				},
				"agent2": {
					"promptLength": 587,
					"contentLength": 1376
				}
			}
		}
	},
	"RequestId": "ABCD1234-1234-1234-1234-123****"
}

  • When no risk is detected

{
	"Msg": "success",
	"Code": 200,
	"Data": {
		"DataId": "123****",
		"TaskId": "TASK1234-1234-1234-1234-123***",
		"Result": [
			{
				"Label": "nonLabel",
				"Description": "agent1"
			},
			{
				"Label": "nonLabel",
				"Description": "agent2"
			}
		],
		"RiskLevel": "none",
		"usage": {
			"promptLength": 1379,
			"contentLength": 1376,
			"AgentDetail": {
				"agent1": {
					"promptLength": 789,
					"contentLength": 1376
				},
				"agent2": {
					"promptLength": 587,
					"contentLength": 1376
				}
			}
		}
	},
	"RequestId": "EFCH1234-1234-1234-1234-123****"
}

Status codes

This table describes the Code values returned by the API. Only requests that return a Code of 200 are billed.

Code

Description

200

The request is successful.

400

The request parameters are empty.

401

Invalid request parameters.

402

A request parameter's length is invalid. Check the parameter and try again.

408

The account is not authorized to call this API. This can be due to an inactive service, overdue payments, or insufficient permissions.

500

Internal system error.

Previous：Moderation Agent: Introduction and pricingNext：Moderation Agent SDK