---
title: "Create a mockup generation task"
method: POST
path: "/mockup-generator/create-task/{id}"
tags: ["Mockup Generator API"]
---

# Create a mockup generation task

`POST /mockup-generator/create-task/{id}`

Creates an asynchronous mockup generation task.
Generation result can be retrieved using mockup generation task retrieval endpoint.<br>
**Rate limiting**: Up to 10 requests per 60 seconds for established stores;
2 requests per 60 seconds for new stores. Currently available rate is returned in response headers.
A 60 seconds lockout is applied if request count is exceeded. We also limit the number of files that may
be generated to 20,000 files per account in a 24-hour period.

## Path parameters

- `id` integer, required

## Headers

- `X-PF-Store-Id` string

## Request body

- object — Mockup generation data.
  - `variant_ids` integer[] — List of variant ids you want to generate.
  - `format` 'jpg' | 'png' — Generated file format. PNG will have a transparent background, JPG will have a smaller file size.
  - `width` integer — Width of the resulting mockup images (min 50, max 2000, default is 1000)
  - `product_options` object — Key-value list of product options (embroidery thread, stitch colors). Product options can be found in Catalog API endpoint. [See examples](#tag/Common/Options)
  - `option_groups` string[] — List of option group names you want to generate. Product's option groups can be found in printfile API request.
  - `options` string[] — List of option names you want to generate. Product's options can be found in printfile API request.
  - `files` GenerationTaskFile[]
    - `placement` string — Placement identifier (front, back, etc.).
    - `image_url` string — Public URL where your file is stored.
    - `position` GenerationTaskFilePosition — Position
      - `area_width` integer, nullable — Positioning area width on print area in pixels
      - `area_height` integer, nullable — Positioning area height on print area in pixels
      - `width` integer — Width of the image in given area in pixels
      - `height` integer — Height of the image in given area in pixels
      - `top` integer — Image top offset in given area in pixels
      - `left` integer — Image left offset in given area in pixels
    - `options` FileOption[] — Array of additional options for this file [See examples](#tag/Common/Options)
      - `id` string, required — Option id
      - `value` string, required — Option value
  - `product_template_id` integer — Product template ID. Use instead of files parameter.

## Response `200`

OK

- object
  - `code` integer — Response status code `200`
  - `result` GenerationTask — GenerationTask
    - `task_key` string — Task identifier you will use to retrieve generated mockups.
    - `status` 'pending' | 'completed' | 'failed' — Status of the generation task.
    - `error` string — If task has failed, reason will be provided here.
    - `mockups` GenerationTaskMockup[] — If task is completed, list of mockups will be provided here.
      - `placement` string — Placement identifier.
      - `display_name` string — This is a name that can be displayed to end customers.
      - `variant_ids` integer[] — List of variant ids this mockup is used for. One mockup can be used for multiple variants.
      - `extra` GenerationTaskExtraMockup[] — Optional extra mockups.
        - `title` string — Display name of the extra mockup.
        - `url` string — Temporary URL of the mockup.
        - `option` string — Style option name
        - `option_group` string — Style option group name
    - `printfiles` GenerationTaskTemplateFile[] — If task is completed, list of printfiles will be provided here.
      - `variant_ids` integer[] — List of variant IDs associated with printfiles.
      - `placement` string — Placement identifier (front, back, etc.).
      - `url` string — Public URL where your file is stored.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/printful/apis/api-documentation-printful.md) · [All operations](https://skmtc.net/printful/apis/api-documentation-printful/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/printful/api-documentation-printful/revisions/18e2f2e178dd/schema)