Upload Media Assets v1.0.0+

To upload an media asset, you can use this.$cloudinary.upload (within a component), or context.$cloudinary.upload (for plugins, asyncData, fetch, nuxtServerInit and middleware).

upload(file, options, callback)

• file
  • Type: String
  • required
  • Path to the target asset file for uploading
• options
  • Type: Object
  • Configuration options to apply to the target asset during uploading to Cloudinary.
• callback
  • Type: Function
  • A callback method to trigger once the upload is completed. It is not needed if you are using ES6 async/await or Promise API.
• Returns a Promise<Asset | Error>

Cloudinary module offers two types of upload API - server and client, which are wrapped inside upload method, with the same signature. Depending on the current environment (client or server) upload is executed, it will automatically trigger the appropriate API behind the scene.

However, there are different parameters required per use case. Below are the notes for each use case:

Server-side Upload (Secured)

For server-side, the module use signed upload API for secured and authenticated uploading. Its secure protocol is based on cloudName, apiKey and apiSecret.

Once resolved sucessfully, the method returns an Asset containing information about the uploaded asset, or an Error otherwise.

/* Upload to folder `content` and rename the asset to `Example` */
const instance = this.$cloudinary.upload("m-target-file-path", {
  public_id: "Example",
  folder: "content",
});

Client-side Upload (Unsecured)

To avoid exposing our apiKey and apiSecret, we can't use the same server-side upload API for client-side. Instead, the module will use the unsigned upload API.

Client-side upload receives options parameter with the following properties:

• upload_preset
  • Type: String
  • required
  • Unsigned upload preset defined for your Cloudinary account.
• public_id
  • Type: String
  • The identifier for accessing the uploaded asset.
• folder
  • Type: String
  • Folder name where the uploaded asset will be store.
• tags
  • Type: Array<String>
  • List of tag names to assign to the uploaded asset, such as ['animal', 'dog']
• context
  • Type: Array<Object>
  • List of key-value pairs of general textual contet metadata to attach to the uploaded asset.
• face_coordinates
  • Type: Array<Array>
  • For images only
  • List of array of coordinates ([ x, y, width, height ]) of faces contained in the uploaded asset. This is for overriding the automatically detected faces.
• custom_coordinates
  • Type: Array<Array>
  • For images only
  • List of array of coordinates ([ x, y, width, height ]) of single region contained in the uploaded asset. It is relevant only if you are planning to crop images using custom gravity.

Once resolved sucessfully, the method returns an Asset containing information about the uploaded asset, or an Error otherwise.

/* Upload to folder `content` and rename the asset to `Example` */
const instance = this.$cloudinary.upload("m-target-file-path", {
  public_id: "Example",
  folder: "content",
  upload_preset: "example_preset",
});

Client-side Upload (Pre-signed)

It's possible to secure client-side uploads by generating a signature beforehand, that we pass to the upload request. These uploads do not require you to pass an upload preset, but you may still include one if you are using signed upload presets.

To generate a valid signature, at the bare minimum you need to pass a unix timestamp. If successful, the signature you receive will be valid for ** 1 hour** after you generated it.

If you plan on passing any additional parameters to your upload (such as public_id, tags, etc.), you must include them in the signature request.

Once you have successfully generated a signature, you need to pass that signature, along with the timestamp and your Cloudinary API key to the upload request.

/* An example of sending a request to an API to generate
a signature, and then performing an upload */
const options = {
  timestamp: Date.now(),
  public_id: "media/cat.png",
  tags: ["animal", "cat"],
};

const signature = await this.$axios.$post(
  "/api/generate-cloudinary-signature",
  options
);

if (signature) {
  const asset = await this.$cloudinary.upload("m-target-file-path", {
    ...options,
    signature,
    api_key: this.$config.cloudinaryApiKey,
  });
}

Upload Preset

Upload preset is a preset consist of upload parameters defined as default behavior for your uploads. Preset is useful in avoid repeatedly passing these same parameters in options every time you call upload.

The upload parameters can be tags, pre-generate or on-the-fly transformations, etc.

You can create an upload preset from Settings page of Cloudinary Console - Upload Tab as below:

There are two modes for an upload preset: signed and unsigned. Signed upload preset is generally used for secured upload (server-side), while unsigned upload preset allows uploading directly from browser (client-side).

Asset

This is the read-only object containing an asset's information, which is returned after the asset is uploaded using upload or requested using explicit.

Below are some main properties:

• public_id
  • Type: String
  • The asset's public identifier (path to the asset stored in Cloudinary)
• asset_id
  • Type: String
  • Asset's hashed id
• format
  • Type: String
  • Original format, such as .png, .jpg, etc.
• secure_url
  • Type: String
  • Original delivery URL using HTTPS
• url
  • Type: String
  • Original unsecured delivery URL (HTTP)
• type
  • Type: String
  • Asset's delivery type, can be fetch, upload, authenticated, private, etc.
• version
  • Type: String
  • Current version of the asset
• height
  • Type: Number
  • Asset's height
• width
  • Type: Number
  • Asset's width
• eager
  • Type: Array<Object>
  • Pre-generate assets' info based on the eager transformations passed
• placeholder
  • Type: Boolean
  • Whether there is a placeholder generated
• tags
  • Type: Array
  • All the tags assigned to the asset
• original_filename
  • Type: String
  • The original filename when uploading
• overwritten
  • Type: Boolean
  • Whether it is overwritten (for upload)

Example of a returned asset:

{
 public_id: 'sample',
 version: '1312461204',
 width: 864,
 height: 564,
 format: 'jpg',
 created_at: '2017-08-10T09:55:32Z',
 resource_type: 'image',
 tags: [],
 bytes: 9597,
 type: 'upload',
 etag: 'd1ac0ee70a9a36b14887aca7f7211737',
 url: 'http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg',
 secure_url: 'https://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg',
 signature: 'abcdefgc024acceb1c1baa8dca46717137fa5ae0c3',
 original_filename: 'sample'
}