Child pages
  • UAPI Functions - ImageManager::create_thumbnails
Skip to end of metadata
Go to start of metadata

Description

This function creates thumbnails from images. 

The function saves the new thumbnail images in a thumbnails subdirectory inside the original directory. The system prepends thumbnail filenames with tn_ (for example, tn_picture.jpg).

Important:

In cPanel & WHM version 76 and later, when you disable the WebServer role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/ImageManager/create_thumbnails?dir=images&width_percentage=25&height_percentage=25


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Create thumbnails from images in /public_html/images.
$create_thumbnails = $cpanel->uapi(
    'ImageManager', 'create_thumbnails',
    array(
        'dir'   			=> 'images',
        'width_percentage'  => '25',
		'height_percentage' => '25',
    )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Create thumbnails from images in /public_html/images.
my $create_thumbnails = $cpliveapi->uapi(
    'ImageManager', 'create_thumbnails',
    {
        'dir'    => 'images',
        'width_percentage'   => '25',
		'height_percentage'  => '25',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username ImageManager create_thumbnails dir=public_html/images width_percentage=25 height_percentage=25


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
    {
       "result" : {
          "warnings" : null,
          "data" : [
             {
                "thumbnail_file" : "/home/cptest1/public_html/thumbnail_work/thumbnails/tn_610_290.jpg",
                "file" : "/home/cptest1/public_html/thumbnail_work/610_290.jpg",
                "reason" : "too many pixels",
                "failed" : 1
             },
             {
                "thumbnail_file" : "/home/cptest1/public_html/thumbnail_work/thumbnails/tn_simpson_drooling.jpeg",
                "file" : "/home/cptest1/public_html/thumbnail_work/simpson_drooling.jpeg",
             }
          ],
          "errors" : null,
          "status" : 1,
          "messages" : null,
          "metadata" : {
             "transformed" : 1
          }
       }


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters 

ParameterTypeDescriptionPossible ValuesExample
dirstring

Required

The path to the directory where the image resides. 

When you pass this parameter, the function creates a thumbnail directory directly below the image directory.

  • A valid, absolute directory path.
  • A directory relative to the user's home directory.
images
width_percentageinteger

Required

The percentage by which to reduce the thumbnails' width.

A positive integer.25
height_percentageinteger

Required

The percentage by which to reduce the thumbnails' height.

A positive integer.25

Returns

ReturnTypeDescriptionPossible valuesExample

array of hashesAn array of hashes of thumbnail file information.Each hash contains the thumbnail_file and file, returns.

thumbnail_file

 
string

The thumbnail file that the function generated.

The function returns this value in the unnamed array of hashes.

An absolute filepath./home/cptest1/public_html/images/thumbnails/tn_610_290.jpg

file

 
string

The file from which the function generated the thumbnail file.

The function returns this value in the unnamed array of hashes.

An absolute filepath./home/cptest1/public_html/thumbnails/610_290.jpg

failed

 
Boolean

Whether the function failed to create the thumbnail file.

Note:

The function only returns this value if it doesn't create the thumbnail.

The function returns this value in the unnamed array of hashes.

1 is the only possible value.1 

reason

 
string

The reason that the function didn't create the thumbnail file.

Note:

The function only returns this value if it doesn't create the thumbnail.

The function returns this value in the unnamed array of hashes.

An error message.too many pixels