AI Guardrails:Video moderation

Operations overview

Supported regions: cn-shanghai (China, Shanghai), cn-beijing (China, Beijing), cn-shenzhen (China, Shenzhen), ap-southeast-1 (Singapore).

Prerequisites

Before you begin, ensure that you have:

• Installed the PHP dependencies using the correct PHP version. See Install PHP dependencies.

Usage notes

• Only public video URLs are accepted. Local files and binary data are not supported.

• URLs must use HTTP or HTTPS and must not exceed 2,048 characters.

• Reuse the instantiated client across requests to improve performance and avoid repeated connections.

Submit an asynchronous video moderation task (recommended)

VideoAsyncScanRequest sends a video URL to AI Guardrails for moderation. Moderation runs asynchronously — AI Guardrails returns a task ID immediately and delivers results via a callback URL when moderation completes.

Supported moderation scenarios: pornography (porn), terrorist content (terrorism), advertisement (ad), undesirable scene, and logo detection.

<?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.
    // Credentials are read from environment variables to avoid hardcoding secrets.
    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();

    $task = [
        'dataId' => '<your-business-data-id>',  // Your internal identifier for this video; returned in the callback payload so you can correlate results with your records
        'url'    => '<public-video-url>',        // Public HTTP/HTTPS URL, max 2,048 characters
    ];

    $result = Green::v20180509()->videoAsyncScan()
        ->timeout(10)
        ->connectTimeout(3)
        ->body(json_encode([
            'tasks'    => [$task],
            'scenes'   => ['porn', 'terrorism'],  // Specify one or more moderation scenarios
            'callback' => '<your-webhook-url>',   // AI Guardrails POSTs results here when moderation completes
            'seed'     => '<random-string>',      // Used to verify the authenticity of callback requests
        ]))
        ->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;
}

Key parameters:

When callback is set, AI Guardrails delivers results to your webhook automatically. If callback is omitted, poll for results using VideoAsyncScanResultsRequest.

Query asynchronous moderation results

Use VideoAsyncScanResultsRequest to poll for results if you did not set a callback URL when submitting the task. Pass an array of task IDs returned by videoAsyncScan().

Setting a callback URL when submitting the task is the preferred approach. Polling adds latency and requires managing retry logic on your side.

<?php

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

try {
    AlibabaCloud::accessKeyClient(
        getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
        getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
        ->timeout(10)
        ->connectTimeout(3)
        ->regionId('cn-shanghai')
        ->asDefaultClient();

    // Pass an array of task IDs to retrieve results for multiple tasks at once.
    $result = Green::v20180509()->videoAsyncScanResults()
        ->timeout(10)
        ->connectTimeout(3)
        ->body(json_encode(['<task-id>']))
        ->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;
}

Submit a synchronous video moderation task

VideoSyncScanRequest moderates a sequence of video frames and returns results immediately. Use this operation when you already have individual frame images extracted from a video.

Synchronous moderation accepts only sequences of video frames, not full video files. To moderate full videos, use VideoAsyncScanRequest instead.

<?php

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

try {
    AlibabaCloud::accessKeyClient(
        getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
        getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
        ->timeout(10)
        ->connectTimeout(3)
        ->regionId('cn-shanghai')
        ->asDefaultClient();

    // Each frame requires an offset and a public URL.
    $task = [
        'frames' => [
            ['offset' => '0', 'url' => '<url-of-frame-1>'],
            ['offset' => '1', 'url' => '<url-of-frame-2>'],
            ['offset' => '2', 'url' => '<url-of-frame-3>'],
        ],
    ];

    $result = Green::v20180509()->videoSyncScan()
        ->timeout(10)
        ->connectTimeout(3)
        ->body(json_encode([
            'tasks'   => [$task],
            'scenes'  => ['porn', 'terrorism'],
            'bizType' => '<your-business-scenario>',  // Optional: your business scenario identifier
        ]))
        ->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;
}

Submit feedback on moderation results

If a moderation result is incorrect, use VideoFeedbackRequest to submit a correction. AI Guardrails adds the affected video frames to the similar image blacklist or whitelist based on your feedback. Future submissions of similar frames return results consistent with your correction.

For the full parameter reference, see Give feedback on moderation results.

<?php

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

try {
    AlibabaCloud::accessKeyClient(
        getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
        getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
        ->timeout(10)
        ->connectTimeout(3)
        ->regionId('cn-shanghai')
        ->asDefaultClient();

    $feedback = [
        'taskId'     => '<video-moderation-task-id>',
        'dataId'     => '<your-business-data-id>',
        'url'        => '<url-of-the-video>',
        'frames'     => [
            ['url' => '<url-of-frame-1>', 'offset' => '100'],
            ['url' => '<url-of-frame-2>', 'offset' => '200'],
        ],
        'suggestion' => 'block',              // 'pass' = content is acceptable; 'block' = content is a violation
        'scenes'     => ['ad', 'terrorism'],
        'note'       => '<optional-notes>',
    ];

    $result = Green::v20180509()->videoFeedback()
        ->timeout(10)
        ->connectTimeout(3)
        ->body(json_encode($feedback))
        ->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;
}

Key parameters:

What's next

• Asynchronous video moderation — parameter reference

• Synchronous video moderation — parameter reference

• Give feedback on moderation results