Sign in
image_transformation

<Warning>

This API is currently provided as a preview. Be aware of the following:

  • There might be unannounced breaking changes.
  • Any breaking changes to preview APIs won't produce a new API version.
  • Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
</Warning>

Starts a new asynchronous job to apply one or more transformations to an image asset. A successful job produces a single new image asset with all of the requested transformations applied. The source asset isn't modified, and intermediate results aren't returned.

The request requires the ID of the source asset and at least one transformation. The source asset must be an image asset, such as one created using the Asset upload APIs.

Transformations are applied in the order provided, with each one stacked on the result of the previous one.

Starting a job consumes the user's AI credit allowance. If the user has reached their AI allowance limit, the request returns a 429 error with the credit_quota_exceeded code. Polling for the result of a job using the Get image transformation job API doesn't consume any of the allowance.

<Note>

For more information on the workflow for using asynchronous jobs, see API requests and responses. You can check the status and get the results of image transformation jobs created with this API using the Get image transformation job API.

</Note>
post/v1/image-transformations

Request body

asset_idstring required

The ID of the source asset to transform. The asset must be an image asset; referencing any other asset type (such as a video) fails with an unsupported_content_type error.

The asset must also have finished uploading. An asset that is still uploading has no image to transform yet and fails with an asset_not_ready error. If you've just created the asset, poll its upload job — for example with the Get asset upload job endpoint — until it returns a success status before starting a transformation.

namestring

A name for the new image asset that the job produces. Canva doesn't localize this value, so provide a name in the user's language. When omitted, the new asset inherits the name of the source asset.

Example request

{
  "asset_id": "Msd59349ff",
  "name": "My Awesome Upload with the background removed",
  "transformations": [
    {
      "type": "background_removal"
    }
  ]
}

Response

OK

Example response

{
  "job": {
    "result": {
      "asset": {
        "type": "image",
        "id": "Msd59349ff",
        "name": "My Awesome Upload",
        "tags": [
          "image",
          "holiday",
          "best day ever"
        ],
        "import_status": {
          "state": "success"
        },
        "created_at": 1377396000,
        "updated_at": 1692928800,
        "owner": {
          "user_id": "auDAbliZ2rQNNOsUl5OLu",
          "team_id": "Oi2RJILTrKk0KRhRUZozX"
        },
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        },
        "metadata": {
          "width": 1920,
          "height": 1080,
          "smart_tags": [
            "landscape",
            "sunset",
            "mountains",
            "nature"
          ]
        }
      }
    }
  }
}

Changes

Changed in 1 of the 16 revisions of this API.1