---
title: "POST /v1/image-to-design-imports"
method: POST
path: "/v1/image-to-design-imports"
tags: ["design_import"]
---

# POST /v1/image-to-design-imports

`POST /v1/image-to-design-imports`

<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 convert an image into an editable design in Canva, using [Magic Layers](https://www.canva.com/magic-layers/). Elements in the image become separate editable layers in the resulting design.

Provide the image as an asset that is already in the user's Canva account.

The image must be a standard photo or graphic file, such as a PNG or JPEG. Vector-based formats such as SVG, EPS, or AI files, are not supported. Video assets are not supported.

This conversion is designed for flat, non-photographic images such as posters, flyers, banners, and social graphics.

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 using the [Get image-to-design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-image-to-design-import-job/) doesn't consume any of the allowance.

Use this API when the user wants to edit the contents of the image, such as changing its text, colors, or individual elements. If you only need to place the image into a design as a single flat image, use the [Create design API](https://www.canva.dev/docs/apps/rest-apis/reference/designs/create-design/) with an `asset_id` instead. The Create design API doesn't consume AI credits.

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

</Note>

## Request body

- CreateImageToDesignImportJobRequest
  - `image` ImageSource, required — The image to convert into a design.
    - `asset_id` string, required — The ID of an image asset in the user's Canva account. The asset must be one of the following image types: `png`, `jpeg`, `gif`, `webp`, `heic`, `heif`, `avif`, `tiff`, `jp2`, `jpx`, `jpm`, or `jxr`. Video assets are not supported.
  - `title` string — A title for the created design. If not provided, Canva generates a title.

## Response `200`

OK

- CreateImageToDesignImportJobResponse
  - `job` ImageToDesignImportJob, required — The status and result of an image-to-design import job.
    - `id` string, required — The ID of the image-to-design import job.
    - `status` 'failed' | 'in_progress' | 'success', required — The status of the design import job.
    - `result` ImageToDesignImportJobResult
      - `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` ImageToDesignImportError — If the import job fails, this object provides details about the error.
      - `code` 'bad_input' | 'moderation_error' | 'quota_exceeded' | 'design_creation_throttled' | 'internal_error', required — A short string about why the import failed. This field can be used to handle errors programmatically.
      - `message` string, required — A human-readable description of what went wrong.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `default` — Error Response

## Changes

- **2026-09-21** `ded190b8f3ba` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/canva/apis/canva-connect-api/changes/v1/image-to-design-imports/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/bfef8d5a788a?raw)