upload

API reference for the upload method.

This version of the API is in beta. Beta APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

This method creates a new asset upload task and adds it to the upload queue. It returns a asset reference, and a function called whenUploaded() that can be used to await the upload task completion.

Parameters

optionsAssetUploadOptions

REQUIRED

Options for uploading an asset to the user's private media library.

Options for uploading an image asset to the user's private media library.

typestring

REQUIRED

The type of asset.

This must be "image".

urlstring

REQUIRED

The URL of the image file to upload. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must return a 200 status code
Content-Type must match the file's MIME type
Must be publicly accessible (i.e. not a localhost URL)
Must not redirect
Must not contain an IP address
Maximum length: 4096 characters
Must not contain whitespace
Must not contain these characters: >, <, {, }, ^, backticks
Maximum file size: 50MB

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)

Requirements for SVGs:

Disallowed elements:
- a
- altglyph
- altglyphdef
- altglyphitem
- animate
- animatemotion
- animatetransform
- cursor
- discard
- font
- font-face
- font-face-format
- font-face-name
- font-face-src
- font-face-uri
- foreignobject
- glyph
- glyphref
- missing-glyph
- mpath
- script
- set
- switch
- tref
Disallowed attributes:
- 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.
The URL in the href attribute must not point to a location outside of the SVG.
The style attribute must not use the mix-blend-mode property.

mimeTypeImageMimeType

REQUIRED

The MIME type of the image file.

The available options include:

"image/jpeg"
"image/heic"
"image/png"
"image/svg+xml"
"image/webp"
"image/tiff"

thumbnailUrlstring

REQUIRED

The URL of a thumbnail image to display while the image is queued for upload. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Must be a PNG, JPEG, or SVG file
Maximum length: 4096 characters

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)

aiDisclosureAiDisclosure

REQUIRED

A disclosure identifying if the app generated this image using AI

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on an image using AI.

Required for the following cases (this list is not exhaustive):

Case	Reason
AI generates a new image from scratch	Creates new creative content
AI changes the style of the image e.g. makes it cartoon	Significantly alters the style
AI removes an object and replaces it with new content	Creates new creative content
AI changes the facial expression of a person in an image	Can alter content's original meaning
AI composites multiple images together	Significantly alters context
AI expands an image by generating new content to fill the edges	Creates new creative content
AI replaces background by generating new content	Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case	Reason
Asset comes from an asset library	Didn't generate the asset itself
AI corrects red eyes	A minor correction
AI removes background without replacement	Doesn't change original meaning by itself
AI changes the color of an object in an image	Doesn't change original meaning by itself
AI detects image defects and suggests manual fixes	Didn't change the asset itself
AI adjusts brightness and contrast on an image	Doesn't change original meaning by itself
AI upscales an image	Doesn't change original meaning by itself

The available options include:

"app_generated"
"none"

parentRefImageRef

OPTIONAL

The ref of the original asset from which this new asset was derived.

For example, if an app applies an effect to an image, parentRef should contain the ref of the original image.

widthnumber

SOMETIMES REQUIRED

A width, in pixels.

heightnumber

SOMETIMES REQUIRED

A height, in pixels.

Options for uploading a video asset to the user's private media library.

typestring

REQUIRED

The type of asset.

This must be "video".

urlstring

REQUIRED

The URL of the video file to upload.

Requirements:

Must use HTTPS
Must return a 200 status code
Content-Type must match the file's MIME type
Must be publicly accessible (i.e. not a localhost URL)
Must not redirect
Must not contain an IP address
Maximum length: 4096 characters
Must not contain whitespace
Must not contain these characters: >, <, {, }, ^, backticks
Maximum file size: 100MB

mimeTypeVideoMimeType

REQUIRED

The MIME type of the video file.

The available options include:

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

thumbnailImageUrlstring

REQUIRED

The URL of a thumbnail image to use as a fallback if thumbnailVideoUrl isn't provided. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Must be a PNG, JPEG, or SVG file
Maximum length: 4096 characters

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)

aiDisclosureAiDisclosure

REQUIRED

A disclosure identifying if the app generated this video using AI.

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on a video using AI.

Required for the following cases (this list is not exhaustive):

Case	Reason
AI generates a new video from scratch	Creates new creative content
AI changes the style of the video e.g. makes it cartoon	Significantly alters the style
AI adds subtitles that rely on subjective interpretation	Creates new creative content
AI expands a video by generating new content to fill the edges	Creates new creative content
AI animates an image	Creates new creative content
AI fixes defects e.g. blur in a video by generating details	Creates new creative content
AI generates a talking head presenter	Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case	Reason
Asset comes from an asset library	Didn't generate the asset itself
AI corrects red eyes	A minor correction
AI adjusts brightness and contrast on a video	Doesn't change original meaning by itself
AI creates a slow motion effect in a video	Doesn't change original meaning by itself
AI adds AI word-by-word transcribed subtitles to a video	Doesn't change original meaning by itself

The available options include:

"app_generated"
"none"

parentRefVideoRef

OPTIONAL

The ref of the original asset from which this new asset was derived.

For example, if an app applies an effect to a video, parentRef should contain the ref of the original video.

thumbnailVideoUrlstring

OPTIONAL

The URL of a thumbnail video to display while the video is queued for upload.

Requirements:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Maximum length: 4096 characters

widthnumber

SOMETIMES REQUIRED

A width, in pixels.

heightnumber

SOMETIMES REQUIRED

A height, in pixels.

Options for uploading an audio asset to the user's private media library.

typestring

REQUIRED

The type of asset.

This must be "audio".

urlstring

REQUIRED

The URL of the audio file to upload to the user's private media library.

Requirements:

Must use HTTPS
Must return a 200 status code
Content-Type must match the file's MIME type
Must be publicly accessible (i.e. not a localhost URL)
Must not redirect
Must not contain an IP address
Maximum length: 4096 characters
Must not contain whitespace
Must not contain these characters: >, <, {, }, ^, backticks
Maximum file size: 50MB

mimeTypeAudioMimeType

REQUIRED

The MIME type of the audio file.

The available options include:

"audio/mpeg"
"audio/mp4"
"audio/x-m4a"
"audio/mp3"
"audio/ogg"
"audio/wav"
"audio/x-wav"
"audio/wave"
"audio/vnd.wave"
"audio/x-pn-wav"
"audio/webm"

titlestring

REQUIRED

A human-readable title for the audio asset.

This title is displayed in the Canva editor.

durationMsnumber

REQUIRED

The initial playback duration of the audio file, in milliseconds.

aiDisclosureAiDisclosure

REQUIRED

A disclosure identifying if the app generated this audio using AI.

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on an audio asset using AI.

Required for the following cases (this list is not exhaustive):

Case	Reason
AI generates a music track from scratch	Creates new creative content
AI generates sounds from scratch e.g. animal sounds	Creates new creative content
AI converts text to speech	Creates new creative content
AI changes the mood or genre of audio/music	Significantly alters context
AI adjusts pitch or tempo for a creative purpose	Significantly alters context

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case	Reason
Asset comes from an asset library	Didn't generate the asset itself
AI balances audio across speakers	A minor correction

The available options include:

"app_generated"
"none"

Returns

An asset that's queued for upload to the user's private media library. This is a Promise that resolves with the following object:

An image asset that's queued for upload to the user's private media library.

refImageRef

A unique identifier that points to an image asset in Canva's backend.

whenUploadedfunction

Returns a Promise that resolves when the asset has finished uploading.

Returns

Promise<void>

A video asset that's queued for upload to the user's private media library.

refVideoRef

A unique identifier that points to a video asset in Canva's backend.

whenUploadedfunction

Returns a Promise that resolves when the asset has finished uploading.

Returns

Promise<void>

An audio asset that's queued for upload to the user's private media library.

refAudioRef

A unique identifier that points to the audio asset in Canva's backend.

whenUploadedfunction

Returns a Promise that resolves when the asset has finished uploading.

Returns

Promise<void>