---
title: "POST /v1/image-generations"
method: POST
path: "/v1/image-generations"
tags: ["image_generation"]
---

# POST /v1/image-generations

`POST /v1/image-generations`

<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](https://www.canva.dev/docs/apps/rest-apis/versions/).
- 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](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) 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](https://www.canva.com/help/ai-access/). 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](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of image generation jobs created with this API using the [Get image generation job API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/get-image-generation-job/).

</Note>

## Request body

- CreateImageGenerationJobRequest
  - `prompt` string, 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_key` string, 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.
  - `asset_upload` union — Whether to save the generated image as an image asset in the user's Canva account. Omitting `asset_upload` (or using `type: none`) returns only a download URL. Saving the asset (`type: upload`) requires a user access token.
    - NoneImageGenerationAssetUpload — Don't save the generated image. The result contains only its download URL.
      - `type` 'none', required
    - UploadImageGenerationAssetUpload — Save the generated image as an image asset in the user's Canva account. The asset appears in the user's Uploads, and the generated image in the result includes the `asset` alongside its download `url`.
      - `type` 'upload', required
      - `asset_name` string — A name for the image asset. Canva doesn't localize this value, so provide a name in the user's language. If omitted, Canva generates a name for the asset.

## Response `200`

OK

- CreateImageGenerationJobResponse
  - `job` ImageGenerationJob, required — Details about the image generation job. If the job status is `success`, the job's `result` is present.
    - `id` string, required — The image generation job ID.
    - `status` 'failed' | 'in_progress' | 'success', required — The status of the image generation job. A newly created job will be `in_progress` and will eventually become `success` or `failed`. If the status is `success`, the job's `result` is present.
    - `result` ImageGenerationJobResult — Result of the image generation job. Only present if job status is `success`.
      - `image` GeneratedImage, required — A generated image.
        - `url` string, required — A download URL for the generated image. The download URL is only valid for 24 hours.
        - `asset` AssetSummary — An object representing an asset with associated metadata.
          - `type` 'image' | 'video', required — Type of an asset.
          - `id` string, required — The ID of the asset.
          - `name` string, required — The name of the asset.
          - `tags` string[], required — The user-facing tags attached to the asset. Users can add these tags to their uploaded assets, and they can search their uploaded assets in the Canva UI by searching for these tags. For information on how users use tags, see the [Canva Help Center page on asset tags](https://www.canva.com/help/add-edit-tags/).
          - `created_at` integer, required — When the asset was added to Canva, as a Unix timestamp (in seconds since the Unix Epoch).
          - `updated_at` integer, required — When the asset was last updated in Canva, as a Unix timestamp (in seconds since the Unix Epoch).
          - `thumbnail` Thumbnail — A thumbnail image representing the object.
            - `width` integer, required — The width of the thumbnail image in pixels.
            - `height` integer, required — The height of the thumbnail image in pixels.
            - `url` string, required — A URL for retrieving the thumbnail image. This URL expires after 15 minutes. This URL includes a query string that's required for retrieving the thumbnail.
        - `width` integer, required — The width of the generated image in pixels.
        - `height` integer, required — The height of the generated image in pixels.
    - `error` ImageGenerationError — If the image generation job fails, this object provides details about the error. Only present if status is `failed`.
      - `code` 'unsafe_input' | 'timeout' | 'model_not_available' | 'model_retired' | 'internal_error', required — Error code indicating what went wrong with the image generation.
      - `message` string, required — A human-readable description of what went wrong.
  - `quota_usage` CreditQuotaSuccessInfo — Credit quota usage information returned on a successful generation request.
    - `used_percentage` integer — The percentage of the caller's credit quota that has been consumed in the current billing interval, from 0 to 100.
    - `resets_at` integer — Unix timestamp (seconds from the Unix epoch) of when the credit quota resets for the caller.
    - `using_bonus_credits` boolean — Whether the caller is currently consuming bonus credits (credits beyond their base plan allocation).
    - `usage_review_link` string — A URL to the Canva credit usage dashboard where the caller can review their current credit consumption. Not present if unavailable.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Credit Quota Exceeded
- `default` — Error Response

## Changes

- **2026-10-02** `328682d29ec4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/canva/apis/canva-connect-api/changes/v1/image-generations/post.md)

---

[API](https://skmtc.dev/canva/apis/canva-connect-api.md) · [All operations](https://skmtc.dev/canva/apis/canva-connect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/canva/apis/canva-connect-api/revisions/328682d29ec4?raw)