> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# Create design generation job

<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 `402` 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 API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/get-design-generation-job/).
</Note>

## HTTP method and URL path

POST https\://api.canva.com/rest/v1/generations

### Rate limit

This operation's rate limit depends on your app type:

<table layout="fixed">
  <thead>
    <tr>
      <th width="55%">App type</th>
      <th width="45%">Rate limit</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Public or private apps** (acts on behalf of a user using the OAuth authorization code flow)</td>
      <td>20 requests per minute for each user of your app</td>
    </tr>

    <tr>
      <td>**Service apps** (acts on behalf of your app itself using the OAuth client credentials flow)</td>
      <td>100 requests per minute for your app</td>
    </tr>
  </tbody>
</table>

## Authentication and authorization

This endpoint requires a valid OAuth access token. For more information, see [Generate an access token](/docs/apps/rest-apis/reference/authentication/generate-access-token).

### Scopes

The access token must have the following [scopes](/docs/apps/rest-apis/scopes) (permissions), depending on your app type:

<table layout="fixed">
  <thead>
    <tr>
      <th width="55%">App type</th>
      <th width="45%">Required scopes</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Public or private apps** (acts on behalf of a user using the OAuth authorization code flow)</td>

      <td>
        * `design:content:write`
      </td>
    </tr>

    <tr>
      <td>**Service apps** (acts on behalf of your app itself using the OAuth client credentials flow)</td>

      <td>
        * `service:design:content:write`
      </td>
    </tr>
  </tbody>
</table>

### Capabilities

Capabilities only apply to public or private apps, which act on behalf of a user. The user must have at least one of the following [capabilities](/docs/apps/rest-apis/capabilities/):

* `design_generation`

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string" required>
    Provides credentials to authenticate the request, in the form of a `Bearer` token.

    For example: `Authorization: Bearer {token}`
  </Prop>

  <Prop name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/json`.

    For example: `Content-Type: application/json`
  </Prop>
</Prop.List>

## Body parameters

<Prop.List>
  <Prop name="brief" type="string" required>
    A description of the design to generate, including its subject, purpose,
    required wording, tone, and visual direction.

    <Prop.Extras>
      **Minimum length:** `1`

      **Maximum length:** `5000`
    </Prop.Extras>
  </Prop>

  <Prop name="design_type" type="object" required>
    The preset Canva design type to generate. Supports `doc` and `presentation`.

    <PillAccordion title={<>Properties of <strong>design_type</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="type" type="string" required>
          The kind of design type to generate.

          <Prop.Extras>
            **Available values:** The only valid value is `preset`: A preset Canva design type..
          </Prop.Extras>
        </Prop>

        <Prop name="name" type="string" required>
          The name of the design type to generate.

          <Prop.Extras>
            **Available values:**

            * `doc`: A [Canva doc](https://www.canva.com/docs/); a document for Canva's online text editor.
            * `presentation`: A [presentation](https://www.canva.com/presentations/); lets you create and collaborate for presenting to an audience.
          </Prop.Extras>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>

  <Prop name="outline" type="object">
    The slide structure to follow. This property is supported only when
    `design_type.name` is `presentation`.

    <PillAccordion title={<>Properties of <strong>outline</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="sections" type="DesignGenerationOutlineSectionV2[]" required>
          One slide in a presentation outline.

          <Prop.Extras>
            **Minimum items:** `1`

            **Maximum items:** `100`
          </Prop.Extras>

          <PillAccordion title={<>Properties of <strong>sections</strong></>}>
            <Prop.List>
              <Prop name="title" type="string" required>
                The slide title.

                <Prop.Extras>
                  **Minimum length:** `1`

                  **Maximum length:** `255`
                </Prop.Extras>
              </Prop>

              <Prop name="description" type="string">
                A short description of what the slide should cover.

                <Prop.Extras>
                  **Minimum length:** `1`

                  **Maximum length:** `2000`
                </Prop.Extras>
              </Prop>

              <Prop name="points" type="string[]">
                Optional individual points the slide should make.

                <Prop.Extras>
                  **Maximum items:** `50`
                </Prop.Extras>
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/generations` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request POST 'https://api.canva.com/rest/v1/generations' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "brief": "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
      "design_type": {
        "type": "preset",
        "name": "presentation"
      }
    }'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");

    fetch("https://api.canva.com/rest/v1/generations", {
      method: "POST",
      headers: {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        "brief": "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
        "design_type": {
          "type": "preset",
          "name": "presentation"
        }
      }),
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/rest/v1/generations"))
                .header("Authorization", "Bearer {token}")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"brief\": \"A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.\", \"design_type\": {\"type\": \"preset\", \"name\": \"presentation\"}}"))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests

    headers = {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json"
    }

    data = {
        "brief": "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
        "design_type": {
            "type": "preset",
            "name": "presentation"
        }
    }

    response = requests.post("https://api.canva.com/rest/v1/generations",
        headers=headers,
        json=data
    )
    print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Post,
      RequestUri = new Uri("https://api.canva.com/rest/v1/generations"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
      },
      Content = new StringContent(
        "{\"brief\": \"A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.\", \"design_type\": {\"type\": \"preset\", \"name\": \"presentation\"}}",
        Encoding.UTF8,
        "application/json"
      ),
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    	"strings"
    )

    func main() {
    	payload := strings.NewReader(`{
    	  "brief": "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
    	  "design_type": {
    	    "type": "preset",
    	    "name": "presentation"
    	  }
    	}`)

    	url := "https://api.canva.com/rest/v1/generations"
    	req, _ := http.NewRequest("POST", url, payload)
    	req.Header.Add("Authorization", "Bearer {token}")
    	req.Header.Add("Content-Type", "application/json")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/rest/v1/generations",
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
        'Content-Type: application/json',
      ),
      CURLOPT_POSTFIELDS => json_encode([
        "brief" => "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
        "design_type" => [
          "type" => "preset",
          "name" => "presentation"
        ]
      ])
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/rest/v1/generations')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request['Authorization'] = 'Bearer {token}'
    request['Content-Type'] = 'application/json'
    request.body = <<REQUEST_BODY
    {
      "brief": "A 3-slide pitch deck for a solar-panel startup with an energetic, modern, blue-and-white visual direction.",
      "design_type": {
        "type": "preset",
        "name": "presentation"
      }
    }
    REQUEST_BODY

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

If successful, the endpoint returns a `200` response with a JSON body with the following parameters:

<Prop.List>
  <Prop name="job" type="DesignGenerationJobV2" required mode="output">
    The status and result of a public design generation job.

    <PillAccordion title={<>Properties of <strong>job</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="id" type="string" required mode="output">
          The public design generation job ID.
        </Prop>

        <Prop name="status" type="string" required mode="output">
          The public status of the job. `result` is present only for `success`, and
          `error` is present only for `failed`.

          <Prop.Extras>
            **Available values:**

            * `failed`: The design couldn't be generated.
            * `in_progress`: The design is still being generated.
            * `success`: The design was generated and saved to the user's Canva account.
          </Prop.Extras>
        </Prop>

        <Prop name="result" type="DesignGenerationJobResultV2" mode="output">
          Present only when the job status is `success`.

          <PillAccordion title={<>Properties of <strong>result</strong></>}>
            <Prop.List>
              <Prop name="design" type="DesignSummary" required mode="output">
                Basic details about the design, such as the design's ID, title, and URL.

                <PillAccordion title={<>Properties of <strong>design</strong></>}>
                  <Prop.List>
                    <Prop name="id" type="string" required mode="output">
                      The design ID.
                    </Prop>

                    <Prop name="urls" type="DesignLinks" required mode="output">
                      A temporary set of URLs for viewing or editing the design.

                      <PillAccordion title={<>Properties of <strong>urls</strong></>}>
                        <Prop.List>
                          <Prop name="edit_url" type="string" required mode="output">
                            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.
                          </Prop>

                          <Prop name="view_url" type="string" required mode="output">
                            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.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="created_at" type="integer" required mode="output">
                      When the design was created in Canva, as a Unix timestamp (in seconds since the Unix
                      Epoch).
                    </Prop>

                    <Prop name="updated_at" type="integer" required mode="output">
                      When the design was last updated in Canva, as a Unix timestamp (in seconds since the
                      Unix Epoch).
                    </Prop>

                    <Prop name="title" type="string" mode="output">
                      The design title.
                    </Prop>

                    <Prop name="url" type="string" mode="output">
                      URL of the design.
                    </Prop>

                    <Prop name="thumbnail" type="Thumbnail" mode="output">
                      A thumbnail image representing the object.

                      <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                        <Prop.List>
                          <Prop name="width" type="integer" required mode="output">
                            The width of the thumbnail image in pixels.
                          </Prop>

                          <Prop name="height" type="integer" required mode="output">
                            The height of the thumbnail image in pixels.
                          </Prop>

                          <Prop name="url" type="string" required mode="output">
                            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.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="page_count" type="integer" mode="output">
                      The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
                    </Prop>
                  </Prop.List>
                </PillAccordion>
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="error" type="DesignGenerationJobErrorV2" mode="output">
          Details about a failed design generation job.

          <PillAccordion title={<>Properties of <strong>error</strong></>}>
            <Prop.List>
              <Prop name="code" type="string" required mode="output">
                The reason the design generation job failed.

                <Prop.Extras>
                  **Available values:**

                  * `content_not_allowed`: The brief or generated content didn't pass Canva's content-safety checks.
                  * `generation_failed`: Canva couldn't complete the design generation job.
                </Prop.Extras>
              </Prop>

              <Prop name="message" type="string" required mode="output">
                A human-readable description of what went wrong.
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example response

### Accepted job

```json
{
  "job": {
    "id": "f81b26fd-a33d-4c2d-9e8c-4a7aca798b17",
    "status": "in_progress"
  }
}
```

## Error responses

### 400 Bad Request

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### The request contains an invalid field

```json
{
  "code": "invalid_field",
  "message": "The presentation outline can only be used with the presentation design type."
}
```

##### An attachment is invalid or unsupported

```json
{
  "code": "invalid_field",
  "message": "The specified attachment must identify a supported image or brand template."
}
```

##### Too many generation inputs

```json
{
  "code": "invalid_field",
  "message": "At most 20 inputs are allowed across images and brand_templates combined."
}
```

##### The design type isn't supported for generation

```json
{
  "code": "invalid_field",
  "message": "Design generation supports doc, presentation, and whiteboard presets."
}
```

### 401 Unauthorized

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### The OAuth client credentials are invalid

```json
{
  "code": "invalid_client",
  "message": "Client {clientId} not available"
}
```

##### Access token could not be decoded or signature could not be verified.

```json
{
  "code": "invalid_access_token",
  "message": "Access token is invalid"
}
```

##### Client credentials or body auth are missing from the request

```json
{
  "code": "invalid_client",
  "message": "Client credentials or body auth are missing from the request."
}
```

##### Authorization header has wrong number of components

```json
{
  "code": "invalid_access_token",
  "message": "Malformed Authorization header: wrong number of components"
}
```

##### Authorization header has invalid mode

```json
{
  "code": "invalid_access_token",
  "message": "Malformed Authorization header: invalid mode"
}
```

##### Token couldn't be introspected

```json
{
  "code": "invalid_access_token",
  "message": "Token couldn't be introspected"
}
```

##### Access token is revoked

```json
{
  "code": "revoked_access_token",
  "message": "Access token is revoked"
}
```

##### Missing Authorization header

```json
{
  "code": "invalid_access_token",
  "message": "Missing Authorization header"
}
```

##### Malformed Authorization header

```json
{
  "code": "invalid_access_token",
  "message": "Malformed Authorization header"
}
```

### 402 Payment Required

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### User has reached their credit quota limit

```json
{
  "code": "credit_quota_exceeded",
  "message": "User has exceeded their credit quota"
}
```

##### App has reached its credit quota limit

```json
{
  "code": "app_credit_quota_exceeded",
  "message": "App has exceeded its credit quota"
}
```

### 403 Forbidden

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### Design generation isn't available to the user

```json
{
  "code": "permission_denied",
  "message": "Design generation isn't available for this user."
}
```

##### The user can't access an attachment

```json
{
  "code": "permission_denied",
  "message": "The user doesn't have access to the specified attachment."
}
```

### 404 Not Found

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error response

##### An attachment wasn't found

```json
{
  "code": "not_found",
  "message": "The specified attachment wasn't found."
}
```