upload

API reference for the upload method.

Uploads an asset, such as an image or video file, to Canva's backend.

To learn more, see Uploading assets.

Usage

Uploading audio

import { upload } from "@canva/asset";

(async () => {
  // Start uploading the file
  const audio = await upload({
    type: "AUDIO",
    id: "uniqueidgoeshere",
    title: "Example audio",
    mimeType: "audio/mp3",
    durationMs: 86047,
    url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
  });

  // Get a reference to the asset in Canva's backend
  console.log("The asset reference is", audio.ref);

  // Wait for the upload to complete
  await audio.whenUploaded();
  console.log("The upload is complete.");
})();

Uploading images

import { upload } from "@canva/asset";

(async () => {
  // Start uploading the file
  const image = await upload({
    type: "IMAGE",
    id: "uniqueidgoeshere",
    mimeType: "image/jpeg",
    url: "https://www.canva.dev/example-assets/image-import/image.jpg",
    thumbnailUrl:
      "https://www.canva.dev/example-assets/image-import/thumbnail.jpg",
  });

  // Get a reference to the asset in Canva's backend
  console.log("The asset reference is", image.ref);

  // Wait for the upload to complete
  await image.whenUploaded();
  console.log("The upload is complete.");
})();

Uploading videos

import { upload } from "@canva/asset";

(async () => {
  // Start uploading the file
  const video = await upload({
    type: "VIDEO",
    id: "uniqueidgoeshere",
    mimeType: "video/mp4",
    url: "https://www.canva.dev/example-assets/video-import/video.mp4",
    thumbnailImageUrl:
      "https://www.canva.dev/example-assets/video-import/thumbnail-image.jpg",
    thumbnailVideoUrl:
      "https://www.canva.dev/example-assets/video-import/thumbnail-video.mp4",
  });

  // Get a reference to the asset in Canva's backend
  console.log("The asset reference is", video.ref);

  // Wait for the upload to complete
  await video.whenUploaded();
  console.log("The upload is complete.");
})();

Parameters

The expected parameters depend on the type of asset being uploaded:

Audio
Images
Videos

To upload audio, set the following parameters:

#optionsobject

Required

The options for configuring the audio to be uploaded.

#options.typestring

Required

The type of asset to upload. For audio, this must be "AUDIO".

#options.idstring

Required

A unique identifier for the audio. The same identifier should always refer to the same file as Canva uses the identifier to avoid duplicate files in Canva's backend.

#options.titlestring

Required

A human readable title that appears in the Canva editor.

#options.mimeTypestring

Required

The MIME type of the audio file. Inexact MIME types are allowed for assets that belong to the same format. For example, you can use audio/mpeg for an audio/mp3 file, but audio/wav will not work.

#options.durationMsnumber

Required

The duration of the audio, in milliseconds.

#options.urlstring

Required

The URL of the audio file.

Returns

A Promise that resolves with the following object:

#resultobject

Required

The successful result of an upload.

#result.refstring

Required

A unique identifier that points to an asset in Canva's backend.

#result.whenUploadedfunction

Required

An asynchronous method that returns a Promise. This Promise resolves when the upload is complete. You can use this method to check when the asset has finished uploading. Ensure whenUploaded is called after adding the element to the page (such as using addNativeElement) in your app's code.