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";// Start uploading the fileconst audio = await upload({type: "AUDIO",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 backendconsole.log("The asset reference is", audio.ref);// Wait for the upload to completeawait audio.whenUploaded();console.log("The upload is complete.");
Uploading images
import { upload } from "@canva/asset";// Start uploading the fileconst image = await upload({type: "IMAGE",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 backendconsole.log("The asset reference is", image.ref);// Wait for the upload to completeawait image.whenUploaded();console.log("The upload is complete.");
Uploading videos
import { upload } from "@canva/asset";// Start uploading the fileconst video = await upload({type: "VIDEO",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 backendconsole.log("The asset reference is", video.ref);// Wait for the upload to completeawait video.whenUploaded();console.log("The upload is complete.");
Permissions
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.
Parameters
The expected parameters depend on the type of asset being uploaded:
- Audio
- Images
- Videos
To upload audio, set the following parameters:
The options for configuring the audio to be uploaded.
The type of asset to upload. For audio, this must be "AUDIO"
.
A human-readable title that appears in the Canva editor.
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"
The duration of the audio, in milliseconds.
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 asaudio/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.
Returns
A Promise
that resolves with the following object:
The successful result of an upload.
A unique identifier that points to an asset in Canva's backend.
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.