POST /editing/image/process
API reference for the "/editing/image/process" endpoint.
If an editing extension supports remote image processing, Canva sends a
POST request to the following endpoint when the extension calls the remoteProcess method:<base_url>/editing/image/process
The purpose of this request is to send the user's image to a server for server-side processing. If the server returns the processed image before the request times out, Canva returns the image to the
remoteProcess method. (The current timeout duration is 30 seconds for China and 15 seconds for the rest of the world.)To handle longer running image processing tasks, the endpoint must initiate polling and implement the
/editing/image/process/get endpoint.- When sending this request, Canva replaces
<base_url>with the extension's Base URL. You can configure the Base URL via the Developer Portal.
POST <base_url>/editing/image/process
Property | Type | Required | Description |
|---|---|---|---|
X-Canva-Signatures | string | Yes | A comma-separated list of request signatures. The name of this header is sometimes lowercase (e.g. x-canva-signatures). |
X-Canva-Timestamp | string | Yes | The UNIX timestamp (in seconds) of when Canva sent the request. The name of this header is sometimes lowercase (e.g. x-canva-timestamp). |
Property | Type | Required | Description |
|---|---|---|---|
user | string | Yes | The ID of the user. |
brand | string | Yes | The ID of the user's team. |
imageUrl | string | Yes | The URL of the full-resolution version of the user's image. |
blobs | No | Blobs passed from the JavaScript client to process the user's image. | |
settings | string | No | Settings passed from the JavaScript client to process the user's image. |
{
"user": "<user>",
"brand": "<brand>",
"imageUrl": "<image_url>"
}
The response an extension provides when it can immediately respond with the user's processed image. After receiving this response, Canva doesn't send any further requests. An extension can only provide this response if the image processing task takes less than 15 seconds (or less than 30 seconds if the app is released in China).
Property | Type | Required | Description |
|---|---|---|---|
type | "SUCCESS" | Yes | The type of response. |
resource | object | Yes | The processed image. |
resource.type | string | Yes | The file type of the processed image. Enum: "JPG", "PNG", "SVG" |
resource.url | string | Yes | The URL of the processed image. |
resource.width | integer | Yes | The width of the processed image , in pixels. |
resource.height | integer | Yes | The height of the processed image , in pixels. |
resource.blobs | No | Any Blobs the client-side code needs to process the user's image. This array is limited to 3 items. | |
resource.metadata | string | No | Any metadata the client-side code needs to process the user's image. |
{
"resource": {
"width": 0,
"height": 0,
"type": "<type>",
"url": "<url>"
},
"type": "SUCCESS"
}
The response an extension provides when it can't respond with the user's processed image in less than 15 seconds (or less than 30 seconds if the app is released in China). After receiving this response, Canva polls /editing/image/process/get until it receives the user's processed image or until the polling times out. The current timeout duration for polling is 60 seconds.
Property | Type | Required | Description |
|---|---|---|---|
type | "SUCCESS" | Yes | The type of response. |
id | string | Yes | The ID of the image being processed. |
{
"type": "SUCCESS",
"id": "<id>"
}
Property | Type | Required | Description |
|---|---|---|---|
type | "ERROR" | Yes | The type of response. |
errorCode | string | Yes | An error code that describes what went wrong. |
{
"type": "ERROR",
"errorCode": "<error_code>"
}
An extension must verify the request signature and timestamp of all incoming requests. When an extension can't verify either of these values, it must reject the request with a
401 status code.Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | A unique ID of the Blob. |
type | string | Yes | The file type of the Blob. Enum: "BIN", "JPG", "JSON", "PNG", "SVG" |
url | string | Yes | The URL of the Blob. |
{
"id": "<id>",
"type": "<type>",
"url": "<url>"
}