How to use the PHP SDK for the image OCR API-AI Guardrails(AI Guardrails)-阿里云帮助中心

Prerequisites

Before you begin, ensure that you have:

Activated the AI Guardrails service in the Alibaba Cloud console. If the service is not activated, API calls return error code 596.
Installed the AI Guardrails PHP SDK and its dependencies. See Installation for details.
A supported PHP version as specified in the Installation topic. Using an unsupported version causes operation calls to fail.
A Resource Access Management (RAM) user AccessKey pair (AccessKey ID and AccessKey secret) stored as environment variables.

Input requirements

The SDK accepts image URLs only. Local files and binary data are not supported.

Requirement	Detail
Protocol	Public HTTP or HTTPS
URL length	Up to 2,048 characters

Submit a synchronous OCR task

Use the ImageSyncScanRequest operation with the scenes parameter set to ocr to extract text from an image.

Supported regions: cn-shanghai, cn-beijing, cn-shenzhen, ap-southeast-1

The example below extracts text from the front of an ID card. To detect other card or certificate types, change the card value in the extras parameter.

Important

Store your AccessKey ID and AccessKey secret as environment variables rather than hard-coding them in your source code. Hard-coded credentials are a security risk.

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Green\Green;

try {
    // Reuse this client instance across requests to avoid repeated connections.
    AlibabaCloud::accessKeyClient(
            getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
            getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        )
        ->timeout(10)          // Request timeout: 10 seconds (client default)
        ->connectTimeout(3)    // Connection timeout: 3 seconds (client default)
        ->regionId('cn-shanghai')
        ->asDefaultClient();

    // Each task requires a dataId (business data identifier) and a url (image URL).
    $task1 = array(
        'dataId' => '<your-data-id>',
        'url'    => '<your-image-url>'
    );

    // Specify the card or certificate type to recognize.
    // Example: front of an ID card
    $extras = array('card' => 'id-card-front');

    /**
     * One image = one task. To detect multiple images, create multiple tasks.
     *
     * Batch detection takes longer on average than single-image detection.
     * The more images in a batch, the higher the probability of increased
     * response time.
     */
    $result = Green::v20180509()->imageSyncScan()
        ->timeout(10)          // Request timeout: 10 seconds (overrides client default)
        ->connectTimeout(3)    // Connection timeout: 3 seconds (overrides client default)
        ->body(json_encode(array(
            'tasks'  => array($task1),
            'scenes' => array('ocr'),
            'extras' => $extras
        )))
        ->request();

    print_r($result->toArray());

} catch (Exception $exception) {
    echo $exception->getMessage() . PHP_EOL;
}

Replace the following placeholders with your values:

Placeholder	Description	Example
`<your-data-id>`	A unique identifier for the image in your business system	`img-20260216-001`
`<your-image-url>`	A publicly accessible HTTP or HTTPS URL of the image	`https://example.com/id-card.jpg`

Billing

OCR detection is billed per image based on the unit price for the detected card or certificate type. For pricing details, see the AI Guardrails pricing page.

Performance tips

Reuse the client instance. Creating a new client per request adds connection overhead. Initialize the client once and reuse it across calls.
Use single-image detection for latency-sensitive workloads. Batch detection averages a longer response time than single-image detection, and response time increases with batch size.

Image OCR