Canva Developers logo
Content
Getting started
Content

queueMediaUpload

API reference for the queueMediaUpload method.

Imports media files from a URL, directly into the user's media library.

The main benefit of this method is that it uploads media via Canva's backend, which is faster and more efficient than uploading the media via the user's browser.

For a complete walkthrough of using this method, see Uploading media.

Usage

Uploading images

import { getContent } from "@canva/content";


(async () => {
  const content = getContent();


  const upload = await content.queueMediaUpload({
    type: "IMAGE",
    mimeType: "image/jpeg",
    id: "P3z7hP2",
    url: "https://i.imgur.com/P3z7hP2.jpg",
    thumbnailUrl: "https://i.imgur.com/Bh4gjjL.png",
  });


  if (upload.type === "done") {
    console.log("The upload has been queued!");
  } else {
    console.log(`Something went wrong: ${upload.reason.type}`);
  }
})();

Uploading videos

import { getContent } from "@canva/content";


(async () => {
  const content = getContent();


  const upload = await content.queueMediaUpload({
    type: "VIDEO",
    mimeType: "video/mp4",
    id: "video",
    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",
  });


  if (upload.type === "done") {
    console.log("The upload has been queued!");
  } else {
    console.log(`Something went wrong: ${upload.reason.type}`);
  }
})();

Parameters

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

  • Images
  • Videos

To upload an image, set the following parameters:

options

Options for configuring the media to be uploaded.

Type
object
options.type

This must be set to "IMAGE".

Type
string
options.id

A unique ID for the image. Do not reuse this ID for any subsequent uploads.

The ID must:

  • Only contain alphanumeric characters — that is, numbers and letters
  • Not exceed 100 characters
Type
string
options.url

The URL of the full-sized image file.

The URL must:

  • Use HTTPS
  • Return a 200 status code
  • Point 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, not a local development server

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 image is 25MB.

Type
string
options.mimeType

The MIME type of the full-sized image file.

The supported MIME types include:

  • "image/heic"
  • "image/jpeg"
  • "image/png"
  • "image/svg+xml"

When working with SVG files, limitations apply. To learn more, see SVG limitations.

Type
string
options.thumbnailUrl

The URL of a thumbnail image.

The URL must:

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

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, so it's less performant than providing a width.

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

Type
number
options.height

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, so it's less performant than providing a height.

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

Type
number

Returns

Returns a Promise. The contents of this Promise depends on whether or not the provided options are valid.

If Canva can queue the media upload, the following result is returned;

result

An object that represents a successful result.

Type
object
result.type

This is always set to "done".

Type
string
result.ref

A unique ID that points to the media item in the user's media library.

Type
string
result.whenUploaded

An asynchronous method that apps can use to detect when the media has finished uploading. To learn more, see whenUploaded.

Type
function

If Canva can't queue the media upload, the following result is returned:

result

An object that represents an unsuccessful result.

Type
object
result.type

This is always set to "failed".

Type
string
result.reason

The reason for the error.

Type
object
result.reason.type

An error code that identifies what went wrong.

Type
string

Error codes

The following error codes may appear in the reason.type property:

invalid_dimensions

One or more of the following statements are true:

  • The width and height are not positive integers
  • The app provided a width but not a height (or vice-versa)
  • The image resolution exceeds 250 megapixels

invalid_id

The id property contains an invalid value.

invalid_media_type

The type property contains an unrecognized value.

invalid_options

The app provided an argument that is not an object.

invalid_thumbnail_url

The thumbnailUrl property contains an invalid URL.

invalid_url

The url property contains an invalid URL.

mismatched_mime_type

The value of the mimeType property doesn't match the MIME type of the file or the Content-Type of the media when it's fetched from the URL.

offline

The user is not connected to the internet.

quota_exceeded

The user doesn't have enough storage space in their media library to upload the file.

unavailable_thumbnail

Canva was not able to download the thumbnail specified in the thumbnailUrl property.

unsupported_mime_type

The mimeType property contains an invalid MIME type.

unknown_error

Something went wrong, but Canva wasn't able to determine the reason for the error.