PHP image and video upload

Cloudinary provides an API for uploading images, videos, and any other kind of file to Cloudinary. Files uploaded to Cloudinary are stored safely in the cloud with optional secure backups and revision history. Cloudinary's APIs allow secure uploading from your servers, directly from your visitors' browsers or mobile applications, or fetched via remote public URLs.

Cloudinary's PHP Library wraps Cloudinary's upload API and simplifies the integration. PHP methods are available for easily performing PHP image and video uploads to Cloudinary and PHP view helper methods are available for uploading directly from a browser to Cloudinary.

This page covers common usage patterns for PHP image and video upload with Cloudinary.

For details on all available upload options and parameters, see the Media upload documentation, and the upload method of the Upload API Reference.

Cloudinary's Upload widget provides an alternative to using a Cloudinary SDK to add upload functionality to your application, eliminating the need to develop in-house interactive upload capabilities. The upload widget is an interactive, feature rich, simple-to-integrate user interface that enables you to add Cloudinary upload support to your website. The widget can be easily embedded in your web application with just a few lines of JavaScript code. See the Upload widget documentation for detailed information.

Upload widget main screen

Server-side upload

You can upload images, videos, or any other raw file to Cloudinary from your PHP code. Uploading is done over HTTPS using a secure protocol based on your account's api_key and api_secret parameters.

PHP image upload

Use the UploadApi class to upload assets to your account.

Copy to clipboard
use Cloudinary\Api\Upload\UploadApi;

The following method of the UploadApi class uploads an image to Cloudinary:

Copy to clipboard
public function upload($file, $options = [])

For example, uploading a local image file named 'my_image.jpg':

Copy to clipboard
(new UploadApi())->upload('my_image.jpg')

The file to upload can be specified as a local path, a remote HTTP or HTTPS URL, a whitelisted storage bucket (S3 or Google Storage) URL, a base64 data URI, or an FTP URL. For details, see File source options.

For details on all available upload options and parameters, see the Media upload documentation, and the upload method of the Upload API Reference.

PHP video upload

You upload videos in exactly the same way as images. The SDK also supports automatically uploading large files to Cloudinary in chunks if the file to upload is larger than a defined chunk_size parameter, by default 20000000 Bytes (= 20 MB).

The following example uploads dog.mp4 to Cloudinary in chunks of 6 MB, and stores it in a bi-level folder structure with the public ID dog_closeup. It also performs two eager transformations that resize the video to a square and a small rectangle.

Copy to clipboard
(new UploadApi())->upload('dog.mp4', [
  'resource_type' => 'video',
  'public_id' => 'myfolder/mysubfolder/dog_closeup',
  'chunk_size' => 6000000,
  'eager' => [
    ['width' => 300, 'height' => 300, 'crop' => 'pad'], 
    ['width' => 160, 'height' => 100, 'crop' => 'crop', 'gravity' => 'south']], 
  'eager_async' => true, 
  'eager_notification_url' => '']

Upload response

By default, uploading is performed synchronously. Once finished, the uploaded image or video is immediately available for transformation and delivery. An upload call returns a Hash with content similar to the following:

Copy to clipboard
  [public_id] => c87hg9xfxrd4itiim3t0
  [version] => 1571218607
  [signature] => f8645b000be7d717599affc89a068157e4748276
  [width] => 864
  [height] => 576
  [format] => jpg
  [resource_type] => image
  [created_at] => 2017-06-23T13:59:18Z
  [bytes] => 120253
  [type] => upload
  [url] =>
  [secure_url] =>

The response includes HTTP and HTTPS URLs for accessing the uploaded media asset as well as additional information regarding the uploaded asset: The Public ID, resource type, width and height, file format, file size in bytes, a signature for verifying the response and more.

Related topics

  • For more information on uploading media assets, see the Media upload documentation.
  • For details on all available upload parameters, see the upload method of the Upload API Reference.

Direct uploading from the browser

The upload sample mentioned above allows your server-side PHP code to upload media assets to Cloudinary. In this flow, if you have a web form that allows your users to upload images or videos, the media file's data is first sent to your server and only then uploaded to Cloudinary.

A more efficient and powerful option is to allow your users to upload images and videos in your client-side code directly from the browser to Cloudinary instead of going through your servers. This method allows for faster uploading and a better user experience. It also reduces load from your servers and reduces the complexity of your PHP applications.

You can upload directly from the browser using signed or unsigned calls to the upload endpoint, as shown in the Upload multiple files using a form examples.

Alternatively, you can use Cloudinary's jQuery plugin as described in the following sections.

For a full working example of using the jQuery upload plugin, see the Photo Album sample project, though note that this uses the legacy PHP SDK, so you would need to adapt it for the latest PHP SDK.

For signed uploads from your client-side code, a secure signature must be generated in your server-side PHP code. You can use the api_sign_request method to generate SHA signatures:

Copy to clipboard
ApiUtils::signParameters($params_to_sign, $api_secret);

jQuery uploading environment setup

Start by including the required JavaScript files: Cloudinary's jQuery plugin as well as the jQuery-File-Upload plugin it depends on. These are available in the js folder of Cloudinary's JavaScript library.

You can directly include the JavaScript files:

Copy to clipboard
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="jquery.ui.widget.js"></script>
<script type="text/javascript" src="jquery.iframe-transport.js"></script>
<script type="text/javascript" src="jquery.fileupload.js"></script>
<script type="text/javascript" src="jquery.cloudinary.js"></script>

Cloudinary's jQuery plugin requires your cloud_name and additional configuration parameters.

Never expose your api_secret in public client-side code.

To automatically set-up Cloudinary's configuration, include the following line in your view or layout:

Copy to clipboard
<?php echo new JsConfigTag(); ?>

The Cloudinary jQuery library utilizes the Blueimp File Upload library to support uploading media directly from the browser. You must explicitly initialize this library:

Copy to clipboard
$(function() {
  if($.fn.cloudinary_fileupload !== undefined) {

Direct uploading from the browser is performed using XHR (Ajax XMLHttpRequest‎) CORS (Cross Origin Resource Sharing) requests. To support older browsers that do not support CORS, the jQuery plugin gracefully degrades to an iframe based solution. This solution requires placing cloudinary_cors.html in the public folder of your PHP application. This file is available in the html folder of Cloudinary's JavaScript library. The following code builds a URL of the local cloudinary_cors.html file:

Copy to clipboard
if (array_key_exists('REQUEST_SCHEME', $_SERVER)) {   
  $cors_location = $_SERVER["REQUEST_SCHEME"] . "://" . $_SERVER["SERVER_NAME"] .
    dirname($_SERVER["SCRIPT_NAME"]) . "/cloudinary_cors.html";
} else {
  $cors_location = "https://" . $_SERVER["HTTP_HOST"] . "/cloudinary_cors.html";

jQuery upload file tag

Embed a file input tag in your HTML pages using one of the following methods:

  • UploadTag: images or videos

Directly uploading an image

The following example adds a file input field for images to your form. Selecting or dragging a file to this input field automatically initiates uploading from the browser to Cloudinary.

Copy to clipboard
<form action="uploaded.php" method="post">
  <?php echo UploadTag('image_id'); ?>

When uploading is completed, the identifier of the uploaded image is set as the value of a hidden input field of your selected name (e.g., 'image_id' in the example above).

You can now display a directly uploaded image in the same way you would display any other Cloudinary hosted image:

Copy to clipboard
<?php echo (new ImageTag (new Image ($photo['public_id'])))
   ->resize(Resize::fill(120, 80)); ?>

Directly uploading a video

The following example renders a direct file upload input field using the UploadTag helper method. AssetType is explicitly defined as VIDEO, asynchronous eager transformations are added to generate adaptive bitrate streaming content, and setAttribute is used to include standard HTML parameters (in this case, an id attribute) in the generated tag.

Copy to clipboard
(new UploadTag(
    'eager' => [
      [ 'streaming_profile' => 'full_hd',
        'format' => 'm3u8']],
    'eager_async' => true,
    'eager_notification_url' => '',
  'id', 'my_upload_tag'

Additional jQuery library features

Cloudinary's jQuery library also enables an enhanced uploading experience with options like showing a progress bar, displaying a thumbnail of the uploaded image, drag & drop support, uploading multiple files and more.

For example, bind to Cloudinary's cloudinarydone event if you want to be notified when an upload to Cloudinary has completed. You will have access to the full details of the uploaded image and you can display a cloud-generated thumbnail of the uploaded images using Cloudinary's jQuery plugin. The following code creates a 150x100 thumbnail of an uploaded image and updates an input field with the public ID of this image.

Copy to clipboard
$('.cloudinary-fileupload').bind('cloudinarydone', function(e, data) {  
      { format: data.result.format, version: data.result.version, 
        crop: 'fill', width: 150, height: 100 })
  return true;

You can find more details and options in the jQuery documentation.

See also

  • For more information on uploading media assets, see the Media upload documentation.
  • For details on all available upload parameters, see the upload method of the Upload API Reference.
  • Get an overview of the PHP SDK, and the various configuration options.
  • See examples of powerful image and video transformations using PHP code
    and see our image transformations and video transformation docs.
  • Check out Cloudinary's asset administration capabilities, for example, renaming and deleting assets, adding tags and metadata to assets, and searching for assets.
  • See the PHP SDK Migration guide for more information on migrating to version 2 of the PHP SDK.

✔️ Feedback sent!

Rate this page: