remoteProcess

API reference for the "remoteProcess" method.

Sends the user's image to a backend server for remote image processing. You can only call this method when an editing extension's Extension type is Remote image processing.

Notes

  • If the /editing/image/process or /editing/image/process/get endpoint returns an error, the remoteProcess method throws an error with the same error code.

  • You can control the maximum dimensions of the user's image via the Max image dimensions field in the Developer Portal. The maximum value is 4096 pixels on the longest side.

  • You can't call the remoteProcess method from the onPresetsRequest callback.

  • If you await on the remoteProcess method from the onReady callback, the onReady callback will likely time out.

Usage

const { imageHelpers } = window.canva;
const canva = window.canva.init();
canva.onReady(async (opts) => {
// Convert the CanvaElement into a CanvaImageBlob
const image = await imageHelpers.fromElement(opts.element);
// Convert the CanvaImageBlob into an HTMLCanvasElement
const canvas = await imageHelpers.toCanvas(image);
// Render the HTMLCanvasElement
document.body.appendChild(canvas);
// Render the extension's rich controls
renderControls();
});
canva.onControlsEvent(async (event) => {
// Show the loading spinner
canva.toggleSpinner("preview", true);
// Remotely process the user's image
const result = await canva.remoteProcess();
const image = await imageHelpers.fromUrl(result.previewImage.url);
// Get the HTMLCanvasElement
const canvas = document.querySelector("canvas");
const context = canvas.getContext("2d");
// Render the processed image
const img = await imageHelpers.toImageElement(image);
context.drawImage(img, 0, 0, canvas.width, canvas.height);
// Hide the loading spinner
canva.toggleSpinner("preview", false);
});
function renderControls() {
const controls = [
canva.create("button", {
id: "startRemoteImageProcessing",
label: "Start remote image processing...",
}),
];
canva.updateControlPanel(controls);
}

Parameters

Name

Type

Required

Description

opts

object

No

Options for remotely processing the user's image.

opts.blobs

Map<string, Blob>

No

Blobs the extension needs to process the user's image. The key is an ID for the Blob. The value is the Blob.

opts.settings

string

No

Settings the extension needs to process the user's image, such as the the dimensions of the viewport. You can use the JSON.stringify function to pass a JSON object via this parameter.

Returns

Promise<RemoteProcessOutput>

Types

RemoteProcessOutput

Represents the output of remote image processing.

Signature

type RemoteProcessOutput = {
image?: CanvaImageBlob;
fullImage?: CanvaImageUrl;
previewImage?: CanvaImageUrl;
blobUrls?: ReadonlyMap<string, string>;
metadata?: string;
};

Properties

Name

Type

Required

Description

image (deprecated)

CanvaImageBlob

No

The user's image.

fullImage

CanvaImageUrl

No

The full-resolution version of the user's image.

previewImage

CanvaImageUrl

No

The medium-resolution version of the user's image.

blobUrls

Map<string, string>

No

The Blobs returned by the server. The key is the ID of the Blob. The value is the URL of the Blob.

metadata

string

No

Arbitrary metadata returned by the server.