AI Guardrails:Custom face retrieval

How it works

1. Submit an image URL along with a groupId to specify which person group to search.

2. The imageSyncScan API scans the image against the person group using the sface-n scene.

3. The API returns the top 5 matching persons from the group, sorted by similarity score.

Prerequisites

Before you begin, ensure that you have:

• The PHP SDK installed using the PHP version specified in the Install PHP dependencies topic. Using an unsupported version causes subsequent API calls to fail.

• Your AccessKey ID and AccessKey secret from your RAM user, stored as environment variables.

• The AI Guardrails endpoint for your region. See Endpoints.

• A person group created with faces indexed before running a retrieval task. See API operation for custom face retrieval.

Submit a face retrieval task

The request requires two parameters: the URL of the image to match (url) and the ID of the person group to search (groupId). Pass groupId inside the extras object of the task.

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;
use AlibabaCloud\Green\Green;

try {
    // Initialize the client. Reuse this instance across requests to improve
    // performance and avoid repeated connection overhead.
    AlibabaCloud::accessKeyClient(
        getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
        getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
        ->timeout(10)         // Request timeout: 10 seconds
        ->connectTimeout(3)   // Connection timeout: 3 seconds
        ->regionId('cn-shanghai')
        ->asDefaultClient();

    // Build the retrieval task.
    $task = [
        'dataId' => '<your-data-id>',
        'url'    => '<image-url>',
        'extras' => ['groupId' => '<group-id>'],
    ];

    // Submit the task using the sface-n scene (custom face retrieval).
    $result = Green::v20180509()->imageSyncScan()
        ->timeout(10)
        ->connectTimeout(3)
        ->body(json_encode([
            'tasks'  => [$task],
            'scenes' => ['sface-n'],
        ]))
        ->request();

    print_r($result->toArray());

} catch (ClientException $e) {
    echo $e->getMessage() . PHP_EOL;
} catch (ServerException $e) {
    echo $e->getMessage() . PHP_EOL;
    echo $e->getErrorCode() . PHP_EOL;
    echo $e->getRequestId() . PHP_EOL;
    echo $e->getErrorMessage() . PHP_EOL;
}

Replace the following placeholders before running the code:

What's next

• Review the full list of request and response parameters: API operation for custom face retrieval

• Find the correct endpoint for your region: Endpoints