Sign in
image_generation

<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 generate an image from a plain-text prompt. When the image is generated, you can download it using the URL provided. The download URL is only valid for 24 hours.

The request requires a prompt and an idempotency key. Call this API with a user access token that has the asset:write scope.

To also save the generated image to the user's Canva account as an image asset, set asset_upload to type: upload. The job then returns the asset alongside the download URL. Saving the asset requires a user access token.

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.

<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 generation jobs created with this API using the Get image generation job API.

</Note>
post/v1/image-generations

Request body

promptstring required

A plain-text description of the image to generate.

aspect_ratio'square' | 'landscape' | 'portrait'

The aspect ratio of the generated image.

model'lucid_origin' | 'z_image_turbo'

The model to use for image generation. If omitted, Canva selects the best available model for the request. If the requested model can't serve the request, the job fails. Canva never uses a different model to serve the request.

idempotency_keystring uuid required

A key to make create requests idempotent. Retrying with the same key returns the original job without creating a duplicate, even if the other request parameters differ. Keys are held for 24 hours from job creation.

Example request

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "asset_upload": {
    "asset_name": "Red apple on a wooden table"
  }
}

Response

OK

Example response

{
  "job": {
    "result": {
      "image": {
        "asset": {
          "type": "image",
          "id": "Msd59349ff",
          "name": "My Awesome Upload",
          "tags": [
            "image",
            "holiday",
            "best day ever"
          ],
          "created_at": 1377396000,
          "updated_at": 1692928800,
          "thumbnail": {
            "width": 595,
            "height": 335,
            "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
          }
        },
        "width": 1024,
        "height": 1024
      }
    }
  }
}

Changes

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