Type to search...

Default image serving - set placeholder images for your website


Referring to a non-existent image (public ID or remote content) there is the option to provide a reserve public ID, therefore avoiding the error 404 response for the URL, e.g.: displaying a placeholder in accordance with the overall design.

The above could provide useful when the deletion of the image was not successful; when the image is no longer in the Shardimage system, but there is a URL reference to it. Additionally, you can employ it when the client does not handle the unsuccessful image upload properly and acts if the image had been uploaded. Also, it is useful for remote contents (e.g.: http links), since the remote content might simply have ceased to exist.

If the referenced content still exists, the provided default public ID will not be checked. This can prove important for the following reason: the service should be tested when first used with an error as well, so you can avoid the problem of a mistyped default public ID.


  • it won’t correct the error in the generated URL, so the URL needs to be correct in its syntax as well
  • if there is no default public ID and no provided public ID, the response will still be URL 404
  • it does not work with the layer transformations’ public ID
  • the provided default public ID need to be in the specified cloud and the cloud cannot be a previously deleted one
  • the account needs to have an active balance
  • public ID only corrects the cannot be found error, it is not suitable for “fixing” firewall and other error

Use case

Let’s think about a forum where users’ avatar images are stored in Shardimage system as an example. In cases like these, there is always a default avatar image that we give to users who do not upload own images. This default image can also be included in the avatar URL generation, providing extra protection to the images and making sure that there are no empty “holes” in the page in case of any errors.


/d/{default public ID} - prefix /d/ - default public ID - ID of an existing image.


  • /d/olivia
  • existing public ID - https://img.shardimage.com/5ow354rT/s-b3:jfxTL2DX2fraljFGXO_w2ulya7qN_FMv00/o-strictSecureHash/wh:100/v/1596631530/d/olivia/i/crowd
  • not existing public ID - https://img.shardimage.com/5ow354rT/s-b3:cK9LPcqMvj8467vrWaW9Jr9Pz-Bwr0s900/o-strictSecureHash/wh:100/v/1596631530/d/olivia/i/crowd-not-exists
  • existing remote - https://img.shardimage.com/5ow354rT/s-b3:cwfjeYk4UOIF4VaUcgbe5hAyByBzB-N500/o-strictSecureHash/h:100/d/olivia/r/http/https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fen%2F6%2F6b%2FYii-logo-transparent.png
  • not existing remote - https://img.shardimage.com/5ow354rT/s-b3:ojJskS-i9TXb9oP5KbjHJbw0mh2iMmyR00/o-strictSecureHash/wh:100/d/olivia/r/http/https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fen%2F6%2F6b%2FYii-logo-transparent-no-exists.png


$client = new Client([       //we will use this configured $client for the further examples
    'apiKey' => '<apiKey>',
    'apiSecret' => '<apiSecret>',
    'imageSecret' => '<imageSecret>',
    'cloudId' => '<cloudId>',
$params = [
    'cloudId' => '<cloudId>',
    'publicId' => '<publicId>',
$optParams = [    //optional
    'default_public_id' => '<default_public_id>',
$url = $client->getUrlService()->create($params, $optParams);
Table of contents