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.

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.");
})();
ts
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.");
})();
ts
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.");
})();
ts

Before an app that uses this method can be submitted for review, the canva:asset:private:write permission must be enabled via the Developer Portal. To learn more, see Configuring permissions.

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

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 ID must only contain alphanumeric characters and not exceed 100 characters.

#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.

The supported MIME types include:

  • "audio/mp3"
  • "audio/mp4"
  • "audio/mpeg"
  • "audio/ogg"
  • "audio/wav"
  • "audio/webm"
  • "audio/x-m4a"
  • "audio/x-wav"
#options.durationMsnumber
Required

The duration of the audio, in milliseconds.

#options.urlstring
Required

The URL of the audio file.

The URL must:

  • Use HTTPS
  • Return a 200 status code
  • Point to an image with the same MIME type that's specified in the mimeType property
  • Have a Content-Type that matches the MIME type of the audio, such as audio/mp4
  • Be accessible to Canva's backend — that is, exposed to the internet

The URL must not:

  • Redirect to a different URL
  • Contain an IP address
  • Exceed 4096 characters
  • Contain whitespace
  • Contain the following characters: >, <, {, }, ^, or backticks

The maximum file size of an audio file is 50MB.

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.