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

# POST /v1/generations

`POST /v1/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 integrations 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 a Canva design from a text brief. A successful job includes metadata for the generated design, which is saved to the user's Canva account.

You can generate a document or presentation. For presentations, you can also provide an outline of the slides to generate.

Requires the `design_generation` capability. You can check whether the user has this capability using the [Get user capabilities API](https://www.canva.dev/docs/apps/rest-apis/reference/users/get-user-capabilities/).

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. Polling for the result of a job doesn't consume any of the allowance.

<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 jobs created with this API using the [Get design generation job v2 API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/get-design-generation-job/).

</Note>

## Request body

- CreateDesignGenerationJobRequestV2 — The brief, design type, and optional presentation outline for generation.
  - `brief` string, required — A description of the design to generate, including its subject, purpose, required wording, tone, and visual direction.
  - `design_type` PresetDesignTypeInput, required — Provide the common design type.
    - `type` 'preset', required
    - `name` 'doc' | 'email' | 'presentation' | 'whiteboard', required — The name of the design type.
  - `outline` DesignGenerationOutlineV2 — The ordered slide structure for a generated presentation.
    - `sections` DesignGenerationOutlineSectionV2[], required
      - `title` string, required — The slide title.
      - `description` string — A short description of what the slide should cover.
      - `points` string[] — Optional individual points the slide should make.

## Response `200`

OK

- CreateDesignGenerationJobResponseV2
  - `job` DesignGenerationJobV2, required — The status and result of a public design generation job.
    - `id` string, required — The public design generation job ID.
    - `status` 'failed' | 'in_progress' | 'success', required — The public status of the job. `result` is present only for `success`, and `error` is present only for `failed`.
    - `result` DesignGenerationJobResultV2 — Present only when the job status is `success`.
      - `design` DesignSummary, required — Basic details about the design, such as the design's ID, title, and URL.
        - `id` string, required — The design ID.
        - `title` string — The design title.
        - `url` string — URL of the design.
        - `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.
        - `urls` DesignLinks, required — A temporary set of URLs for viewing or editing the design.
          - `edit_url` string, required — A temporary editing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows. NOTE: This is not a permanent URL, it is only valid for 30 days.
          - `view_url` string, required — A temporary viewing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows. NOTE: This is not a permanent URL, it is only valid for 30 days.
        - `created_at` integer, required — When the design was created in Canva, as a Unix timestamp (in seconds since the Unix Epoch).
        - `updated_at` integer, required — When the design was last updated in Canva, as a Unix timestamp (in seconds since the Unix Epoch).
        - `page_count` integer — The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
    - `error` DesignGenerationJobErrorV2 — Details about a failed design generation job.
      - `code` 'content_not_allowed' | 'generation_failed', required — The reason the design generation job failed.
      - `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
- `404` — Not Found
- `429` — Credit Quota Exceeded
- `default` — Error Response

## Changes

- **2026-10-02** `328682d29ec4` — 2 warning
  - removed the request property `brand_templates`
  - removed the request property `images`
- **2026-10-01** `bfef8d5a788a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/canva/apis/canva-connect-api/changes/v1/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)