Image only

Import images into Canva with a content extension.

A content extension can support one of two types of content:

When a content extension supports images, it can provide users with JPEG, PNG, and SVG files. These files appear in the side panel and can be dragged into the user's design.

They will then appear in the user's Uploads tab and count against their upload limit.

If you'd like to create a content extension that supports images, check out the quick start guide.

Enabling images

For a content extension to support images, it must be configured via the Developer Portal.

To enable support for images:

  1. Navigate to an app via the Developer Portal.

  2. From the Extensions page, expand the Content panel.

  3. From the Content type dropdown, select Image only.

A content extension can't support images and embeds. It can only support one or the other.

Supported image types

The images a content extension adds to the side panel must meet Canva's Upload formats and requirements.

For JPEG, PNG, and HEIC images, this means:

  • Under 25MB in size

  • Not more than 100 million total pixels (width x height)

For SVG images, this means:

  • Under 10MB in size

  • Between 150 to 200 pixels wide

  • Saved with an SVG Profile of "SVG 1.1"

In addition, the following elements are stripped from SVG images:

  • script

  • metadata

  • style

If a user drags an unsupported image into their design, an error will occur and the user will not be able to save their design until the unsupported image is removed.

Animated GIFs are handled as embeds, rather than images.

Receiving image requests

When a content extension supports images, Canva will retrieve the images by sending a POST request to the following URL:

<base_url>/content/resources/find

<base_url> is a placeholder that will be replaced by the extension's Base URL. You can configure this URL via the Developer Portal. The /content/resources/find path is not configurable.

The body of this request is a JSON object that contains the following properties:

Name

Type

Description

brand

string

The ID of the user’s brand.

containerId?

string

The ID of the selected container.

continuation?

string

A token used for pagination.

label

string

The type of extension that triggered the request.

limit

integer

The maximum number of images to return in a response.

locale?

string

The user’s locale as an IETF BCP 47 language tag.

query?

string

A search query, provided by the user.

type

string

user

string

The ID of the user.

This is an example of an IMAGE request:

{
"user": "AUQ2RUzug9pEvgpK9lL2qlpRsIbn1Vy5GoEt1MaKRE=",
"brand": "AUQ2RUxiRj966Wsvp7oGrz33BnaFmtq4ftBeLCSHf8=",
"label": "CONTENT",
"limit": 100,
"type": "IMAGE",
"locale": "en-US"
}

Responding to image requests

After receiving the "IMAGE" request from Canva, your extension should return a "SUCCESS" response that includes the images that will appear in the side panel.

The body of this response must contain the following properties:

Name

Type

Description

continuation?

string

A token used for pagination.

resources

array

The images to show in the side panel.

type

string

The type of response.

Each object in the resources array must contain the following properties:

Name

Type

Description

contentType?

string

The MIME type of the image.

id

string

A unique ID for the image.

name

string

A human readable name for the image.

thumbnail

object

A thumbnail image.

type

string

The type of resource.

url

string

The URL of the full-sized image.

The id should always refer to the same image. This prevents Canva from repeatedly uploading the same image to Canva's servers, which provides a faster experience for your app's users.

The thumbnail object must contain the following properties:

Name

Type

Description

height?

number

The height of the thumbnail, in pixels.

url

string

The URL of the thumbnail.

width?

number

The width of the thumbnail, in pixels.

For thumbnail images, we recommend a minimum width and height of 150 pixels.

This is an example of a "SUCCESS" response:

{
"type": "SUCCESS",
"resources": [
{
"id": "12345",
"name": "MacBook Air",
"type": "IMAGE",
"thumbnail": {
"url": "https://i.picsum.photos/id/2/200/200.jpg"
},
"url": "https://i.picsum.photos/id/2/200/200.jpg",
"contentType": "image/jpeg"
}
]
}

If possible, we always recommend providing the height and width properties for the thumbnail. This will improve the rendering speed of the thumbnail.

Error handling

If your extension is unable to return the requested images, it should return an "ERROR" response:

{
"type": "ERROR",
"errorCode": "INVALID_REQUEST"
}

For a complete list of valid error codes, refer to the API reference.