Uploading assets

Apps can upload assets, such as images or videos, to Canva's backend. The user can access these assets in the Canva editor, via the Uploads tab, and the app can add the assets to the user's design.

These are some examples of apps that can benefit from uploading assets:

• Stock photo libraries, such as Pixabay⁠(opens in a new tab or window)
• Digital asset management tools, such as Brandfolder⁠(opens in a new tab or window)
• Generative AI apps, such as Text to Image⁠(opens in a new tab or window)

When an app starts uploading an asset, the user can see the upload progress in the Uploads tab, and the asset's thumbnail is overlaid with a progress indicator. A toast notification appears when the upload is complete.

Upload an asset only with the user's explicit permission and intent, such as when the user clicks a button. It's better to show users a preview of the object to upload first, and then confirm with the user whether to proceed with the upload.

The asset counts against the user's storage quota. If the user has a Canva Pro⁠(opens in a new tab or window) account, their storage quota is 1TB. Otherwise, their storage quota is 5GB.

The uploaded asset is only available to the user who uploaded it.

Apps can upload the following types of assets to a user's media library:

• Audio
• Images
• Videos

There are limitations that apply to each type of assets, such as supported file formats and sizes.

Apps can upload the following types of audio files:

The maximum size of an audio file is 50MB.

Apps can upload the following types of image files:

The maximum size of an image file is 50MB, except for SVGs, which are limited to 3MB.

Apps can upload the following types of video files:

The maximum size of a video file is 100MB.

To allow the app to upload assets, enable the canva:asset:private:write permission via the Developer Portal. In the future, the Apps SDK will throw an error if the required permissions are not enabled.

To learn more, see Configuring permissions.

Import the upload method from the @canva/asset package:

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

When calling the method, the expected properties depend on the type of asset being uploaded:

const result = await upload({
  type: "audio",
  title: "Example audio",
  mimeType: "audio/mp3",
  url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
  aiDisclosure: "none",
});

const result = 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",
  aiDisclosure: "none",
});

const result = 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",
  aiDisclosure: "none",
});

In all cases:

• The URLs must be exposed via the internet and available to Canva's backend. This means localhost URLs won't work.
• For images and video, the MIME type must match the format of the uploaded asset. However, for audio, 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.

If the method call is successful, it returns a reference:

console.log("The reference for the upload is:", result.ref);

A reference is a unique identifier that points to an asset in Canva's backend. This reference lets an app interact with an asset before it has finished uploading.

The upload method can return an optional whenUploaded method that informs the user that their upload is complete and returns a Promise. By waiting for the Promise to resolve, the app can determine when an asset has finished uploading:

await result.whenUploaded();
console.log("The upload is complete.");

By default, uploading an asset only makes it available to a user via their Uploads tab. It doesn't add the asset to the user's design. To learn how to add assets to a design, see:

• Creating audio tracks
• Creating images
• Creating videos

This section describes the limitations that apps must consider when uploading SVGs.

For most users, the maximum file size for SVGs is 3MB. If a user is a contributor⁠(opens in a new tab or window), the maximum file size for SVGs is 10MB.

The SVG image should be downloadable from the server within 5 seconds.

Some SVG elements (tags) are not allowed and an upload will fail if the elements are present.

• animate
• animatemotion
• animatetransform
• discard
• mpath
• set

• altglyph
• altglyphdef
• altglyphitem
• cursor
• glyph
• glyphref
• missing-glyph
• tref

• font
• font-face
• font-face-format
• font-face-name
• font-face-src
• font-face-uri

• a
• foreignobject
• script
• switch

Some attributes are either not allowed in SVG files or have certain restrictions.

• crossorigin
• lang
• media
• onload
• ping
• referrerpolicy
• rel
• rendering-intent
• requiredextensions
• requiredfeatures
• systemlanguage
• tabindex
• transform-origin
• unicode
• vector-effect

• The href attribute of an image element only supports data URLs for PNG and JPEG images. Other image formats, such as SVGs, are not supported as data URLs.
• The URL in a href attribute must not point to a location that exists outside of the SVG.
• The style attribute must not use the mix-blend-mode property.

• All assets must comply with Canva's Acceptable Use Policy⁠(opens in a new tab or window).
• All assets must comply with Canva's Upload formats and requirements⁠(opens in a new tab or window).

• upload

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

export function App() {
  async function handleClick() {
    // Start uploading the media
    const result = await upload({
      type: "audio",
      title: "Example audio",
      mimeType: "audio/mp3",
      url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
      aiDisclosure: "none",
    });

    // Get the reference for the upload
    console.log("The reference for the upload is:", result.ref);

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

  return (
    <div>
      <button onClick={handleClick}>Upload audio</button>
    </div>
  );
}

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

export function App() {
  async function handleClick() {
    // Start uploading the media
    const result = 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",
      aiDisclosure: "none",
    });

    // Get the reference for the upload
    console.log("The reference for the upload is:", result.ref);

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

  return (
    <div>
      <button onClick={handleClick}>Upload image</button>
    </div>
  );
}

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

export function App() {
  async function handleClick() {
    // Start uploading the media
    const result = 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",
      aiDisclosure: "none",
    });

    // Get the reference for the upload
    console.log("The reference for the upload is:", result.ref);

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

  return (
    <div>
      <button onClick={handleClick}>Upload video</button>
    </div>
  );
}