upload

API reference for the upload method.

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

Usage

Uploading audio

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

// Start uploading the file
const 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 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";

// Start uploading the file
const 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 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";

// Start uploading the file
const 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 backend
console.log("The asset reference is", video.ref);

// Wait for the upload to complete
await 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:

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

To upload an image, set the following parameters:

#optionsobject

Required

The options for configuring the image to be uploaded.

#options.typestring

Required

The type of asset to upload. For images, this must be "IMAGE".

#options.mimeTypestring

Required

The MIME type of the full-size image. The MIME type must match the format of the uploaded asset.

The supported MIME types include:

"image/heic": HEIC files are not supported for thumbnail images.
"image/jpeg"
"image/png"
"image/svg+xml": Limitations apply for SVG files. See SVG limitations.
"image/tiff": TIFF files are not supported for thumbnail images.
"image/webp"

#options.urlstring

Required

The external URL or data URL of the full-size image file.

If the value is an external URL, it 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 image, such as image/jpeg
Be accessible to Canva's backend — that is, exposed to the internet

If the value is an external URL, it must not:

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

If the value is a data URL, it must:

Point to an image with the same MIME type that's specified in the mimeType property
Include ;base64 if the data is Base64 encoded

If the value is a data URL, it must not:

Exceed 10MB (10 × 1024 × 1024) characters

The maximum file size of an image is 25MB.

#options.thumbnailUrlstring

Required

The external URL or data URL of a thumbnail image.

An external URL must:

Use HTTPS
Point to a lower-resolution version of the full-size image file
Point to an image file that has the same aspect ratio as the full-size image
Point to a PNG, JPEG, or SVG file — HEIC and TIFF thumbnails are not supported
Support Cross-Origin Resource Sharing
Not exceed 4096 characters

A data URL must:

Point to an image file that has the same aspect ratio as the full-size image
Ideally, point to a lower-resolution version of the full-size image file, but you can use the full-size image as the thumbnail
Include ;base64 if the data is Base64 encoded
Point to a PNG, JPEG, or SVG file — HEIC and TIFF thumbnails are not supported
Not exceed 10MB (10 × 1024 × 1024) characters

#options.widthnumber

Sometimes required

The width of the thumbnail, in pixels.

If a width isn't provided, Canva infers the width from the width of the thumbnail. This requires a GET or HEAD request, which is slower than manually providing a width.

If the width is set, the height must also be set, and vice versa.

#options.heightnumber

Sometimes required

The height of the thumbnail, in pixels.

If a height isn't provided, Canva infers the height from the height of the thumbnail. This requires a GET or HEAD request, which is slower than manually providing a height.

If the height is set, the width must also be set, and vice versa.

#parentRefstring

Optional

A unique identifier that points to an image in Canva's backend, indicating that the image being uploaded was derived from the specified image.

To upload a video, set the following parameters:

#optionsobject

Required

The options for configuring the video to be uploaded.

#options.typestring

Required

The type of asset to upload. For videos, this must be "VIDEO".

#options.mimeTypestring

Required

The MIME type of the full-size video file. The MIME type must match the format of the uploaded asset.

The supported MIME types include:

"video/avi"
"image/gif"
"video/x-m4v"
"video/x-matroska"
"video/quicktime"
"video/mp4"
"video/mpeg"
"video/webm"
"application/json"

#options.urlstring

Required

The URL of the full-size video file.

The URL must:

Use HTTPS
Return a 200 status code
Point to a video with the same MIME type that's specified in the mimeType property
Have a Content-Type that matches the MIME type of the video, such as video/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 a video file is 100MB.

#options.thumbnailImageUrlstring

Required

The URL of a thumbnail image. This image is shown while the user drags the video into their design if a thumbnail video can't be used or if a thumbnail video isn't defined.

The URL must:

Use HTTPS
Point to a thumbnail that is an accurate representation of the video
Point to an image file that has the same aspect ratio as the full-size video
Point to a PNG, JPEG, or SVG file — HEIC thumbnails are not supported
Support Cross-Origin Resource Sharing
Not exceed 4096 characters

#options.thumbnailVideoUrlstring

Optional

The URL of a low-resolution video file. If supplied, this is used while the full-size video is still being uploaded. If not supplied, the image from the thumbnailImageUrl is used instead.

The URL must:

Use HTTPS
Point to a lower-resolution version of the full-size video file
Point to a video file that has the same aspect ratio as the full-size video
Point to a file with a MIME type of "video/webm" or "video/mpeg"
Support Cross-Origin Resource Sharing
Not exceed 4096 characters

#options.widthnumber

Sometimes required

The width of the thumbnail, in pixels.

If a width isn't provided, Canva infers the width from the width of the thumbnail. This requires a GET or HEAD request, which is slower than manually providing a width.

If the width is set, the height must also be set, and vice versa.

#options.heightnumber

Sometimes required

The height of the thumbnail, in pixels.

If a height isn't provided, Canva infers the height from the height of the thumbnail. This requires a GET or HEAD request, which is slower than manually providing a height.

If the height is set, the width must also be set, and vice versa.

#parentRefstring

Optional

A unique identifier that points to a video in Canva's backend, indicating that the video being uploaded was derived from the specified video.

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.