Manage custom image libraries

Prerequisites

Before you begin, ensure that you have:

• Java dependencies installed. See Installation for the required Java version. Using a different version causes operation call failures.

• (Required for local images and binary image streams only) The Extension.Uploader utility class downloaded and imported into your project.

Operations overview

Custom image library management covers two groups of operations:

Library management

• Query custom image libraries — list all libraries, including custom and feedback-based

• Create a custom image library — create a new library for a specific moderation scene

• Update a custom image library — rename a library or change its scene or business type

• Delete a custom image library — permanently remove a library and all its images

Image management

• Query images in a library — list images with pagination

• Add an image to a library — upload and register an image in three steps

• Remove images from a library — delete one or more images by ID

For details about library creation parameters, see Create an image library.

Query custom image libraries

The following example queries all image libraries associated with your account, then separates them by source type.

DescribeImageLibRequest describeImageLibRequest = new DescribeImageLibRequest();
describeImageLibRequest.setServiceModule("open_api");

try {
    // Returns all libraries: both custom (MANUAL) and feedback-based (FEEDBACK).
    DescribeImageLibResponse describeImageLibResponse = client.getAcsResponse(describeImageLibRequest);

    List<DescribeImageLibResponse.ImageLib> allLibs = describeImageLibResponse.getImageLibList();
    List<DescribeImageLibResponse.ImageLib> customImageLibs = new ArrayList<DescribeImageLibResponse.ImageLib>();

    for (DescribeImageLibResponse.ImageLib imageLib : allLibs) {
        String source = imageLib.getSource();

        if ("MANUAL".equals(source)) {
            // Custom image library — created and managed manually.
            customImageLibs.add(imageLib);
        }
        if ("FEEDBACK".equals(source)) {
            // Feedback-based image library — built from moderation feedback.
            customImageLibs.add(imageLib);
        }
    }

    System.out.println(JSON.toJSONString(customImageLibs));
} catch (ClientException e) {
    e.printStackTrace();
}

Response fields

Each ImageLib object includes:

• source — Library origin: "MANUAL" for custom image libraries, "FEEDBACK" for feedback-based image libraries.

Create a custom image library

The following example creates a pornography detection blacklist. Set name, scene, and category to match your use case.

CreateImageLibRequest createImageLibRequest = new CreateImageLibRequest();
createImageLibRequest.setServiceModule("open_api");
createImageLibRequest.setName("Pornography detection blacklist");
createImageLibRequest.setScene("PORN");
createImageLibRequest.setCategory("BLACK");

try {
    CreateImageLibResponse createImageLibResponse = client.getAcsResponse(createImageLibRequest);
    // A non-null requestId indicates the library was created successfully.
    String requestId = createImageLibResponse.getRequestId();
    System.out.println(JSON.toJSONString(createImageLibResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

Update a custom image library

The following example renames a library and reassigns it to a business type. Replace 12345 with the ID of the library to update.

UpdateImageLibRequest updateImageLibRequest = new UpdateImageLibRequest();
// Replace 12345 with the ID of your custom image library.
updateImageLibRequest.setId(12345);
updateImageLibRequest.setName("New name of the custom image library");
updateImageLibRequest.setBizTypes(JSON.toJSONString(Arrays.asList("comment")));
updateImageLibRequest.setCategory("WHITE");
updateImageLibRequest.setScene("PORN");

try {
    UpdateImageLibResponse updateImageLibResponse = client.getAcsResponse(updateImageLibRequest);
    // A non-null requestId indicates the library was updated successfully.
    String requestId = updateImageLibResponse.getRequestId();
    System.out.println(JSON.toJSONString(updateImageLibResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

Delete a custom image library

Replace 12345 with the ID of the library to delete.

DeleteImageLibRequest deleteImageLibRequest = new DeleteImageLibRequest();
// Replace 12345 with the ID of the custom image library to delete.
deleteImageLibRequest.setId(12345);

try {
    DeleteImageLibResponse deleteImageLibResponse = client.getAcsResponse(deleteImageLibRequest);
    // A non-null requestId indicates the library was deleted successfully.
    String requestId = deleteImageLibResponse.getRequestId();
    System.out.println(JSON.toJSONString(deleteImageLibResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

Query images in a custom image library

The following example retrieves the first page of images from a library. Replace 1519 with your library ID and adjust pageSize and currentPage as needed.

DescribeImageFromLibRequest describeImageFromLibRequest = new DescribeImageFromLibRequest();
// Replace 1519 with your library ID.
describeImageFromLibRequest.setImageLibId(1519);
describeImageFromLibRequest.setPageSize(20);
describeImageFromLibRequest.setCurrentPage(1);

try {
    DescribeImageFromLibResponse describeImageFromLibResponse = client.getAcsResponse(describeImageFromLibRequest);

    for (DescribeImageFromLibResponse.ImageFromLib imageFromLib : describeImageFromLibResponse.getImageFromLibList()) {
        imageFromLib.getId();        // Primary key ID of the image.
        imageFromLib.getImage();     // URL of the full-size image.
        imageFromLib.getThumbnail(); // URL of the image thumbnail.
    }

    System.out.println(JSON.toJSONString(describeImageFromLibResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

Response fields

• totalCount — Total number of images in the library.

• currentPage — Current page number returned.

• pageSize — Number of images per page.

• imageFromLibList — List of images on the current page. Each entry includes:

  • id — Primary key ID of the image.

  • image — URL of the full-size image.

  • thumbnail — URL of the image thumbnail.

Add an image to a custom image library

Adding an image requires three steps: get an upload credential, upload the image file, then register the image path with the server.

DescribeUploadInfoRequest describeUploadInfoRequest = new DescribeUploadInfoRequest();
describeUploadInfoRequest.setBiz("customImageLib");

DescribeUploadInfoResponse describeUploadInfoResponse = null;
try {
    describeUploadInfoResponse = client.getAcsResponse(describeUploadInfoRequest);
    System.out.println(JSON.toJSONString(describeUploadInfoResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

CustomLibUploader customLibUploader = new CustomLibUploader();
String object = null;
try {
    object = customLibUploader.uploadFile(
        describeUploadInfoResponse.getHost(),
        describeUploadInfoResponse.getFolder(),
        describeUploadInfoResponse.getAccessid(),
        describeUploadInfoResponse.getPolicy(),
        describeUploadInfoResponse.getSignature(),
        "<path-to-your-image>"   // Replace with the absolute path to your image file.
    );
} catch (Exception e) {
    e.printStackTrace();
}

if (org.apache.commons.lang.StringUtils.isNotBlank(object)) {
    UploadImageToLibRequest imageToLibRequest = new UploadImageToLibRequest();
    // Replace 1519 with the ID of your custom image library.
    imageToLibRequest.setImageLibId(1519);
    imageToLibRequest.setImages(JSON.toJSONString(Arrays.asList(object)));

    try {
        UploadImageToLibResponse uploadImageToLibResponse = client.getAcsResponse(imageToLibRequest);
        // A non-null requestId indicates the image was added successfully.
        String requestId = uploadImageToLibResponse.getRequestId();
        System.out.println(JSON.toJSONString(uploadImageToLibResponse));
    } catch (ClientException e) {
        e.printStackTrace();
    }
}

Remove images from a library

The following example removes one or more images by their primary key IDs. Replace 669310 with the IDs of the images to remove.

DeleteImageFromLibRequest deleteImageFromLibRequest = new DeleteImageFromLibRequest();
// Replace 669310 with the primary key ID(s) of the images to remove.
deleteImageFromLibRequest.setIds(JSON.toJSONString(Arrays.asList(669310)));

try {
    DeleteImageFromLibResponse deleteImageFromLibResponse = client.getAcsResponse(deleteImageFromLibRequest);
    // A non-null requestId indicates the images were removed successfully.
    String requestId = deleteImageFromLibResponse.getRequestId();
    System.out.println(JSON.toJSONString(deleteImageFromLibResponse));
} catch (ClientException e) {
    e.printStackTrace();
}

What's next

• Create an image library — API reference for library creation parameters

• Installation — Set up AI Guardrails SDK for Java