upload

API reference for the upload method.

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.

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

#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):

CaseReason
AI generates a new image from scratchCreates new creative content
AI changes the style of the image e.g. makes it cartoonSignificantly alters the style
AI removes an object and replaces it with new contentCreates new creative content
AI changes the facial expression of a person in an imageCan alter content's original meaning
AI composites multiple images togetherSignificantly alters context
AI expands an image by generating new content to fill the edgesCreates new creative content
AI replaces background by generating new contentCreates 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):

CaseReason
Asset comes from an asset libraryDidn't generate the asset itself
AI corrects red eyesA minor correction
AI removes background without replacementDoesn't change original meaning by itself
AI changes the color of an object in an imageDoesn't change original meaning by itself
AI detects image defects and suggests manual fixesDidn't change the asset itself
AI adjusts brightness and contrast on an imageDoesn't change original meaning by itself
AI upscales an imageDoesn't change original meaning by itself

The available options include:

  • "app_generated"
  • "none"
#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:

Requirements for data URLs:

  • Must include ;base64 for base64-encoded data
  • Maximum size: 10MB (10 × 1024 × 1024 characters)
#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.
#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.

#heightnumber
Sometimes required

A height, in pixels.

#widthnumber
Sometimes required

A width, in pixels.

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>