General Image OCR-AI Guardrails(AI Guardrails)-阿里云帮助中心

This topic describes how to call the General Image OCR API to recognize text in images.

Features

General Image OCR recognizes text in images and returns the text content and its location.

Service

Description

Service name: General Image OCR

Service: generalOcr

Recognizes Chinese and English text.
Returns the content and location of text lines.

Billing

General Image OCR (Advanced) supports pay-as-you-go and resource plans.

Pay-as-you-go

After you activate the Content Moderation (Advanced) service, the default billing method is pay-as-you-go. You are charged daily based on your actual usage.

Moderation type	Supported service	Unit price
Image Recognition Advanced (image_advanced)	General Image OCR: generalOcr	CNY 30 per 10,000 calls Note Each call to a supported service is counted as one transaction. You are charged based on the actual number of calls. For example, if you call the General Image OCR service 100 times, the fee is CNY 0.3.

Note

The billing frequency for pay-as-you-go Content Moderation Enhanced Edition is once per hour. In the billing details, the moderationType field indicates the moderation type. You can view the billing details.

Resource plans

If you have a large or consistent volume of recognition requests, we recommend that you purchase a resource plan in advance. Larger resource plans offer greater discounts. You can purchase and use multiple resource plans at the same time. For more information, see Purchase a Content Moderation (Advanced) resource plan.

This resource plan is for Content Moderation (Advanced) usage and is separate from the resource plan for Content Moderation 1.0. The deduction ratios are as follows:

Moderation type

Supported service

Deduction ratio

Image Recognition Advanced (image_advanced)

General Image OCR: generalOcr

4:1. For each successful API call, 4 calls are deducted from your resource plan.

For example, if you purchase a resource plan with a capacity of 10 calls and make one successful API call, 4 calls are deducted from the plan, leaving a balance of 6 calls.

After you purchase a resource plan, usage from Image Moderation (Advanced) API calls is first deducted from the plan. If the plan's capacity is insufficient, the system automatically switches to pay-as-you-go billing. Monitor your resource plan balance and pay-as-you-go bills. You can set up low-balance alerts on the Resource Plan Management page in the Alibaba Cloud Billing Management console.

Getting started

Sign up for an Alibaba Cloud account and follow the instructions to complete the registration.
Activate Content Moderation. Make sure you have activated the service. Activation is free. After you integrate the API, the system automatically charges you based on your usage. For more information, see Billing. You can also purchase a resource plan. Resource plans offer tiered discounts compared to pay-as-you-go and are suitable for users with predictable or high usage.
Create an AccessKey pair. Ensure you have created an AccessKey pair using RAM. If you are using an AccessKey pair of a RAM user, you must use your Alibaba Cloud account to grant the AliyunYundunGreenWebFullAccess permission to the RAM user. For detailed instructions, see Grant permissions to a RAM user.
Develop and integrate. We recommend calling the API using an SDK. For details, see SDKs and getting started guide for Image Moderation-Enhanced Edition 2.0.

API reference

Usage notes

You can call this operation to create an image moderation task. For information about how to construct an HTTP request, see Getting Started. Alternatively, use an SDK to call the API without manually constructing HTTP requests. For more information, see SDK reference.

API operation: ImageModeration
Supported regions and endpoints:

Region	Public endpoint	Internal endpoint	Supported services
China (Shanghai)	https://green-cip.cn-shanghai.aliyuncs.com	https://green-cip-vpc.cn-shanghai.aliyuncs.com	generalOcr
China (Hangzhou)	https://green-cip.cn-hangzhou.aliyuncs.com	https://green-cip-vpc.cn-hangzhou.aliyuncs.com
China (Beijing)	https://green-cip.cn-beijing.aliyuncs.com	https://green-cip-vpc.cn-beijing.aliyuncs.com
China (Shenzhen)	https://green-cip.cn-shenzhen.aliyuncs.com	https://green-cip-vpc.cn-shenzhen.aliyuncs.com

Billing: This is a paid API. You are charged only for requests that return an HTTP status code of 200. You are not charged for requests that return other error codes. For more information about billing, see Billing.
Image requirements:

Supported image formats: PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC (the longest side must be less than 8,192 pixels), GIF (the first frame is used), and ICO (the last frame is used).
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 results, the image resolution should be greater than 200 × 200 pixels. Low resolution may affect the performance of the moderation algorithm.
The image must be downloaded within 3 seconds. If the download time exceeds 3 seconds, the API returns a timeout error.

QPS limits

The queries-per-second (QPS) limit for this API is 100 per Alibaba Cloud account. If you exceed this limit, the system throttles your API calls, which may affect your business. If you require a higher QPS limit, contact your business manager.

Debug the API

Before you integrate the API, you can use the Alibaba Cloud OpenAPI Explorer to debug the Image Moderation-Enhanced Edition API online, view sample code, and check SDK dependencies. This helps you get an overview of how to use the API and its parameters.

Important

The online debugging feature calls the Content Moderation API based on your current logon account. These calls are included in your billable usage.

Request parameters

For the common request parameters required in each request, see SDKs and getting started guide for Image Moderation-Enhanced Edition 2.0.

The request body is a JSON object that contains the following fields:

Parameter

Type

Required

Example

Description

Service

String

Yes

generalOcr

The Image Moderation (Advanced) service to use. Valid value:

generalOcr : General Image OCR

ServiceParameters

JSONString

Yes

Parameters for the detection target, formatted as a JSON string. For details, see ServiceParameters.

Table 1. ServiceParameters

Parameter	Type	Required	Example	Description
imageUrl	String	Yes. You must use one of the following methods to specify the image: Use an image URL. Specify the `imageUrl` parameter. Use an authorized OSS object. You must specify the `ossBucketName`, `ossObjectName`, and `ossRegionId` parameters. Use a local image. Uploading a local image does not use your OSS storage. The system stores the file for only 30 minutes, and the SDKs have built-in support for this feature. For code samples, see SDKs and getting started guide for Image Moderation-Enhanced Edition 2.0.	https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png	The URL of the target image. Ensure that the URL is publicly accessible. The URL cannot exceed 2,048 characters in length. Note The URL cannot contain Chinese characters. Each request can contain only one URL.
ossBucketName	String		bucket_01	The name of the authorized OSS bucket. Note To use the internal endpoint of an OSS image, you must first log in to your Alibaba Cloud account and grant permissions on the Cloud Resource Access Authorization page.
ossObjectName	String		2023/04/24/test.jpg	The full path of the authorized OSS object.
ossRegionId	String		cn-beijing	The region where the OSS bucket is located.
dataId	String	No	img123****	A custom data ID for the target image. It can consist of uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.). The ID can be up to 64 characters long and allows you to identify your business data.
referer	String	No	www.aliyun.com	The Referer request header, used for scenarios such as hotlink protection. The length cannot exceed 256 characters.

Response parameters

Parameter	Type	Example	Description
RequestId	String	70ED13B0-BC22-576D-9CCF-1CC12FEAC477	The unique ID generated by Alibaba Cloud for the request. You can use this ID to troubleshoot issues.
Data	Object		The image moderation results. For more information, see Data.
Code	Integer	200	The status code. For more information, see Status code descriptions.
Msg	String	OK	The response message for the request.

Table 2. Data

Parameter	Type	Example	Description
Ext	Object		The OCR detection results. For more information, see Ext.
DataId	String	img123******	The data ID of the detected object. Note If you included a dataId in your request, the same dataId is returned here.
Result	Array		The results of the image moderation, including risk labels and confidence scores. For more information, see Result. Note You can ignore this return value when using General Image OCR.

Table 3. Ext

Parameter	Type	Example	Description
OcrResult	Array		The OCR results. For more information, see OcrResult.

Table 4. OcrResult

Parameter	Type	Example	Description
Text	String	OCR Result Line 1	A single line of recognized text.
Location	Object		Information about the text line and its coordinates. For more information, see Location.

Table 5. Location

Parameter	Type	Example	Description
X	Float	41	The x-coordinate of the top-left corner of the text area, with the top-left corner of the image as the origin. Unit: pixels.
Y	Float	84	The y-coordinate of the top-left corner of the text area, with the top-left corner of the image as the origin. Unit: pixels.
W	Float	83	The width of the text area. Unit: pixels.
H	Float	26	The height of the text area. Unit: pixels.

Table 6. Result

Parameter	Type	Example	Description
Label	String	nonLabel	The label returned after image moderation. The default value `nonLabel` is returned for General Image OCR. You can ignore this label.
Confidence	Float	99.99	The confidence score, ranging from 0 to 100, with two decimal places. No confidence score is returned for the `nonLabel` label.

Examples

Sample request

{
    "Service": "generalOcr",
    "ServiceParameters": {
        "imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
        "dataId": "img123****"
    }
}

Sample response

Sample response when text is detected in the image:

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel"
            }
        ],
        "Ext": {
            "OcrResult": [
                {
                    "Text": "OCR Result Line 1",
                    "Location": {
                        "H": 26,
                        "W": 83,
                        "X": 41,
                        "Y": 84
                    }
                },
                {
                    "Text": "OCR Result Line 2",
                    "Location": {
                        "H": 25,
                        "W": 95,
                        "X": 78,
                        "Y": 114
                    }
                }
            ]
        }
    },
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ"
}

Sample response when no text is detected in the image:

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel"
            }
        ],
        "Ext": null
    },
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ"
}

Note

The sample requests and responses in this topic are formatted for readability. Actual responses do not include line breaks or indentation.

Status codes

This section describes the status codes returned by the API. You are charged only for requests that return the status code 200.

Code	Description
200	The request was successful.
400	A request parameter is empty.
401	A request parameter is invalid.
402	The length of a request parameter does not meet the API requirements. Check and modify the parameter.
403	The request exceeds the QPS limit. Check and adjust the call frequency.
404	An error occurred while downloading the specified image. Check the image URL and retry.
405	The download of the specified image timed out, possibly because the image URL is unreachable. Check the image URL and retry.
406	The specified image is too large. Check the image size and retry.
407	The format of the specified image is not supported. Check the image format and retry.
408	The account does not have permission to call this API. This may be because the service is not activated, the account has an overdue payment, or the calling account is not authorized.
500	An internal error occurred.