openapi: 3.0.3

info:
  title: Mockupanda API
  description: |
    Put artwork into realistic mockup templates: framed wall art and posters in rooms,
    t-shirts, hoodies, mugs, tote bags and more. Send a design as a file or a public URL
    with one or more template IDs, and get full resolution mockup images back.

    Built for print on demand sellers and developers who automate listing images for
    Etsy, Shopify and other shops. Full guides: https://www.mockupanda.com/docs/api-reference

    ## Authentication

    Every endpoint needs an API key from
    [mockupanda.com/dashboard/api-keys](https://www.mockupanda.com/dashboard/api-keys),
    sent in the `Authorization` header:

    ```
    Authorization: Bearer mk_your_api_key_here
    ```

    ## Billing

    Each rendered mockup is charged to your API balance. A batch is charged per template
    that actually renders. Listing templates, listing sets and adding library templates
    are free. New API accounts start with free credit. Prices are on
    [mockupanda.com/mockup-api](https://www.mockupanda.com/mockup-api).

    ## Request IDs

    Every response from `POST /mockups/generate` carries an `X-Request-Id` header, and
    JSON responses repeat it as `request_id`. Each request shows up under that id in
    Dashboard > Logs. Include it when you contact support.
  version: "1.1.0"
  termsOfService: https://www.mockupanda.com/terms
  contact:
    name: Mockupanda
    url: https://www.mockupanda.com/mockup-api
    email: hello@mockupanda.com
  x-logo:
    url: https://www.mockupanda.com/Mockupanda-mark.svg

externalDocs:
  description: API reference and guides
  url: https://www.mockupanda.com/docs/api-reference

servers:
  - url: https://www.mockupanda.com/api/v1
    description: Production

security:
  - ApiKeyAuth: []

tags:
  - name: Templates
    description: Find mockup templates, and add library templates to your account.
  - name: Sets
    description: Named, ordered groups of templates saved in your account, rendered in one call.
  - name: Mockups
    description: Render mockups from your artwork.

paths:

  /templates:
    get:
      operationId: listTemplates
      tags: [Templates]
      summary: List templates
      description: |
        Returns the template library plus your own templates (those of the account that
        owns the API key), newest first. Free.

        Search with `q`, which matches meaning as well as words, so `beige bedroom` or
        `shop front` find the right scenes even when those words are not in the name.
        Results then come back ranked by relevance (`relevance_ranked: true`).

        To get only the templates shaped for a piece of artwork, pass `artwork_url` (or
        `artwork_width` and `artwork_height`). The artwork's own ratio becomes the
        filter. Ratio filtering applies to print templates only: product templates
        (apparel, mugs, tote bags) wrap the artwork onto a surface, so any ratio filter
        narrows the results to `type=print`, and combining one with `type=product` is
        rejected.
      parameters:
        - name: q
          in: query
          description: Search that matches meaning as well as words. Searches the library and your own templates, ranked by relevance.
          schema:
            type: string
          example: beige bedroom
        - name: search
          in: query
          description: Older substring match on template name and category only. Prefer `q`.
          schema:
            type: string
        - name: category
          in: query
          description: Only templates in this category (case insensitive). The `categories` field of the response lists every value.
          schema:
            type: string
        - name: type
          in: query
          description: |
            `print` for flat prints (frames, posters, canvases), `product` for products
            the artwork wraps onto (t-shirts, hoodies, mugs, tote bags).
          schema:
            type: string
            enum: [print, product]
        - name: source
          in: query
          description: |
            `library` for our ready-made scenes, `custom` for templates in your account.
            Omit to list both.
          schema:
            type: string
            enum: [library, custom]
        - name: ratio
          in: query
          description: |
            Aspect ratio filter, written the way you would say it: `2:3`, `4:5`, `square`,
            `portrait`, `landscape`, `A4`, a print size like `8x10`, or a decimal like
            `0.667`. Comma-separate to accept several. Print templates only. Wins over the
            artwork's ratio when both are given.
          schema:
            type: string
          example: "2:3,4:5"
        - name: artwork_url
          in: query
          description: Public URL of an image. Its ratio becomes the filter, and its measured size comes back in `artwork`.
          schema:
            type: string
            format: uri
        - name: artwork_width
          in: query
          description: Artwork width in pixels. Send with `artwork_height` to match by size without a download.
          schema:
            type: number
            minimum: 1
        - name: artwork_height
          in: query
          description: Artwork height in pixels. Send with `artwork_width`.
          schema:
            type: number
            minimum: 1
        - name: ratio_tolerance
          in: query
          description: How far from the target ratio still counts as a match, in percent.
          schema:
            type: number
            minimum: 0
            maximum: 25
            default: 3
        - name: page
          in: query
          description: Page number, starting at 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Templates per page.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
      responses:
        "200":
          description: A page of templates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateListResponse"
              example:
                templates:
                  - id: bedroom-poster-01
                    name: Bedroom Poster
                    category: Wall Art
                    thumbnail_url: https://pub-2702811b4e0b4173a4fd7e0de9e0b474.r2.dev/thumbnails/bedroom-poster-01.jpg
                    frame_count: 1
                    blending_mode: normal
                    size: null
                    aspect_ratio: 0.667
                    aspect_ratio_name: "2:3"
                    orientation: portrait
                    render_mode: corners
                    surface_type: null
                    is_product_template: false
                    supports_product_color: false
                    is_user_template: false
                    source: library
                pagination:
                  page: 1
                  limit: 50
                  total: 11
                  total_pages: 1
                categories: [Apparel, My templates, Wall Art]
                ratios:
                  - name: "2:3"
                    orientation: portrait
                    label: 2:3 portrait
                    aspect_ratio: 0.667
                    count: 11
                ratio_filter:
                  requested: ["2:3"]
                  tolerance_percent: 3
                  applied_to: print
                artwork:
                  width: 4000
                  height: 6000
                  format: png
                  ratio: 0.667
                  name: "2:3"
                  orientation: portrait
                  label: 2:3 portrait
                relevance_ranked: false
        "400":
          description: A filter could not be read, for example an unknown ratio, half an artwork size, an artwork URL that is not an image, or a ratio filter with `type=product`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: Ratio filtering applies to print templates only.
                hint: Product templates (apparel, mugs, tote bags) warp artwork onto a surface, so they have no fixed artwork ratio. Drop the ratio/artwork parameters, or use type=print.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

    post:
      operationId: addLibraryTemplate
      tags: [Templates]
      summary: Add a library template to your account
      description: |
        Copies a library template into your account. The copy gets its own ID and
        `source: custom`: edits you make to it in the dashboard save onto that ID, while the
        library ID keeps rendering the original, so nothing you already call changes. Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from_template_id]
              properties:
                from_template_id:
                  type: string
                  description: "ID of a library template (`source` is `library`)."
                  example: bedroom-poster-01
                name:
                  type: string
                  description: Name for the copy. Defaults to the library template's name.
      responses:
        "201":
          description: The new template in your account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    $ref: "#/components/schemas/Template"
        "400":
          description: Missing `from_template_id`, a body that is not JSON, or a key that is not tied to an account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: The ID is not a library template. Your own templates are already yours.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: abc is not a library template.
                code: TEMPLATE_NOT_FOUND
                hint: "Only library templates can be added. Your own templates are already yours: edit them in the dashboard."
        "500":
          $ref: "#/components/responses/InternalError"

  /sets:
    get:
      operationId: listSets
      tags: [Sets]
      summary: List template sets
      description: |
        Lists the template sets saved in your account, most recently updated first. A set
        is a named, ordered group of template IDs, created in the Mockupanda app. Pass its
        `id` as `set_id` to `POST /mockups/generate` to render the whole group. Free.
      responses:
        "200":
          description: Your sets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sets:
                    type: array
                    items:
                      $ref: "#/components/schemas/TemplateSet"
                  count:
                    type: integer
                    example: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /sets/{set_id}:
    get:
      operationId: getSet
      tags: [Sets]
      summary: Get a template set
      description: One of your template sets. Free.
      parameters:
        - name: set_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The set.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateSet"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: No set with this ID in your account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: Set not found
                code: SET_NOT_FOUND
        "500":
          $ref: "#/components/responses/InternalError"

  /mockups/generate:
    post:
      operationId: generateMockup
      tags: [Mockups]
      summary: Generate mockups
      description: |
        Places your artwork into one or more templates and returns the rendered images.
        Rendering is synchronous: the response comes back when the images are ready.

        **Artwork.** Send JSON with a public `artwork_url`, or `multipart/form-data` with
        the file in `artwork`. Templates with several frames (diptychs, triptychs) take
        one image per frame: `artwork_urls` in JSON, or `artwork_0`, `artwork_1`, ... in
        multipart.

        **Templates.** Use `template_id` for one mockup, `template_ids` for several (up
        to 12), or `set_id` to render a saved set. They can be combined: the set renders
        first in its saved order, extra IDs follow, and duplicates are collapsed. More than
        one template is a batch, and a batch needs `response_format=json`.

        **Output.** By default the response is the image itself. With
        `response_format=json` it is JSON with the image as base64; a batch returns a
        `results` array.

        **Billing.** Each template that renders is charged to your API balance. Template
        IDs stored in a set that no longer exist are skipped, listed in
        `skipped_template_ids`, and not charged. IDs you send directly still return 404
        when unknown.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateMockupJsonBody"
            examples:
              single:
                summary: One mockup, image returned as the response body
                value:
                  template_id: bedroom-poster-01
                  artwork_url: https://example.com/my-artwork.png
                  format: jpeg
                  width: 2000
              batch:
                summary: Several templates in one request
                value:
                  template_ids: [bedroom-poster-01, frame-wall-02, tshirt-flat-01]
                  artwork_url: https://example.com/my-artwork.png
                  response_format: json
              set:
                summary: Every template in a saved set
                value:
                  set_id: 2bed1943-2880-4d40-b3d6-3296aa71e11e
                  artwork_url: https://example.com/my-artwork.png
                  response_format: json
              multi_frame:
                summary: A different image in each frame
                value:
                  template_id: wall-diptych-01
                  artwork_urls:
                    "0": https://example.com/artwork-left.png
                    "1": https://example.com/artwork-right.png
              product_color:
                summary: A t-shirt recolored to navy
                value:
                  template_id: tshirt-flat-01
                  artwork_url: https://example.com/my-artwork.png
                  product_color: "#1f2a44"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/GenerateMockupFormData"
            encoding:
              artwork:
                contentType: image/png, image/jpeg, image/webp
      responses:
        "200":
          description: |
            The rendered mockup. Without `response_format` the body is the image itself
            (`image/jpeg` or `image/png`). With `response_format=json` it is JSON: one image
            for a single template, a `results` array for a batch or a set.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            X-Template-Id:
              description: Template that was rendered (image responses only).
              schema:
                type: string
            X-Duration-Ms:
              description: Rendering time in milliseconds (image responses only).
              schema:
                type: integer
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/GenerateMockupJsonResponse"
                  - $ref: "#/components/schemas/GenerateMockupBatchJsonResponse"
              examples:
                single:
                  summary: One template, response_format=json
                  value:
                    success: true
                    image: /9j/4AAQSkZJRg...
                    format: jpeg
                    content_type: image/jpeg
                    size_bytes: 523481
                    template_id: bedroom-poster-01
                    duration_ms: 1460
                    request_id: 3f6c1a52-8c1e-4b7a-9d3e-2a1f0c9b7e41
                set:
                  summary: A set, with one stored ID that no longer exists
                  value:
                    success: true
                    results:
                      - template_id: bedroom-poster-01
                        image: /9j/4AAQSkZJRg...
                        format: jpeg
                        content_type: image/jpeg
                        size_bytes: 184270
                      - template_id: living-room-03
                        image: /9j/4AAQSkZJRg...
                        format: jpeg
                        content_type: image/jpeg
                        size_bytes: 242630
                    count: 2
                    total_size_bytes: 426900
                    duration_ms: 1840
                    set_id: 2bed1943-2880-4d40-b3d6-3296aa71e11e
                    set_name: Warm bedrooms
                    skipped_template_ids: [wall-diptych-01]
                    request_id: 3f6c1a52-8c1e-4b7a-9d3e-2a1f0c9b7e41
        "400":
          description: |
            The request could not be used. `code` says why: `MISSING_TEMPLATE_ID`,
            `MISSING_ARTWORK`, `TOO_MANY_TEMPLATE_IDS`, `BATCH_REQUIRES_JSON_RESPONSE`,
            `SET_EMPTY`, `INVALID_JSON`, `INVALID_ARTWORK_URL`, `INVALID_ARTWORK_URLS`,
            `INVALID_TEMPLATE_IDS`, `INVALID_SET_ID`, `INVALID_PRODUCT_COLOR`,
            `INVALID_ARTWORK_SOURCE`, `INVALID_IMAGE_FILE`, `IMAGE_URL_NOT_FOUND` or
            `IMAGE_URL_UNREACHABLE`.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                too_many_templates:
                  value:
                    error: Too many templates in one request (max 12).
                    code: TOO_MANY_TEMPLATE_IDS
                    details:
                      max_template_ids: 12
                    hint: Split into multiple requests with up to 12 template IDs each.
                    request_id: 3f6c1a52-8c1e-4b7a-9d3e-2a1f0c9b7e41
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          description: Not enough API balance for this request. Nothing was charged.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: Insufficient account balance. Add funds in Billing to continue.
                code: INSUFFICIENT_CREDITS
                details:
                  required_cents: 1
                  balance_cents: 0
                hint: Top up your API wallet from Dashboard > Billing and retry.
                request_id: 3f6c1a52-8c1e-4b7a-9d3e-2a1f0c9b7e41
        "404":
          description: A template ID you sent (`TEMPLATE_NOT_FOUND`) or the `set_id` (`SET_NOT_FOUND`) does not exist in the library or your account.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: "Template not found: bedroom-poster-99"
                code: TEMPLATE_NOT_FOUND
                details:
                  missing_template_ids: [bedroom-poster-99]
                hint: Verify template IDs using GET /api/v1/templates.
                request_id: 3f6c1a52-8c1e-4b7a-9d3e-2a1f0c9b7e41
        "408":
          description: Downloading the artwork from `artwork_url` took too long (`IMAGE_FETCH_TIMEOUT`).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "413":
          description: An artwork file is over 20 MB (`ARTWORK_FILE_TOO_LARGE`).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: The template's own image could not be loaded (`INVALID_TEMPLATE_BACKGROUND`).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Rendering failed (`MOCKUP_GENERATION_FAILED`) or an unexpected error.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "503":
          description: The API balance could not be read or charged (`WALLET_UNAVAILABLE`). Nothing was deducted; retry.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

components:

  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        Your Mockupanda API key as a Bearer token. Keys start with `mk_` and are created
        at https://www.mockupanda.com/dashboard/api-keys

  headers:
    X-Request-Id:
      description: ID of this request. It is the ID the request shows under in Dashboard > Logs.
      schema:
        type: string

  schemas:

    Template:
      type: object
      properties:
        id:
          type: string
          description: Template ID. Pass it as `template_id` when generating.
          example: bedroom-poster-01
        name:
          type: string
          example: Bedroom Poster
        category:
          type: string
          example: Wall Art
        thumbnail_url:
          type: string
          format: uri
          nullable: true
          description: Preview image of the template.
        frame_count:
          type: integer
          description: How many artworks the template holds. Above 1, send one image per frame.
          example: 1
        blending_mode:
          type: string
          description: How the artwork is blended into the scene, for example `normal` or `multiply`.
          example: normal
        size:
          type: string
          nullable: true
          description: Print size the template shows, when known.
        aspect_ratio:
          type: number
          description: Width divided by height of the artwork the template expects.
          example: 0.667
        aspect_ratio_name:
          type: string
          description: The same ratio as a name, as the Mockupanda editor shows it (`2:3`, `A4`, `Square`).
          example: "2:3"
        orientation:
          type: string
          enum: [portrait, landscape, square]
        render_mode:
          type: string
          description: How the template places the artwork. Informational.
          example: corners
        surface_type:
          type: string
          nullable: true
          description: Surface the artwork is printed on, when it matters (for example `fabric`).
        is_product_template:
          type: boolean
          description: True for products the artwork wraps onto (apparel, mugs, tote bags), false for flat prints.
        supports_product_color:
          type: boolean
          description: True when the template accepts `product_color` (today t-shirts, hoodies and totes).
        is_user_template:
          type: boolean
          description: Same as `source` being `custom`. Kept for existing integrations.
        source:
          type: string
          enum: [library, custom]
          description: |
            `library` for our ready-made scenes, always rendered exactly as we ship them.
            `custom` for templates in your account, which you can edit without the ID
            changing.

    RatioFacet:
      type: object
      description: A print ratio on offer in the current results, before any ratio filter.
      properties:
        name:
          type: string
          example: "2:3"
        orientation:
          type: string
          enum: [portrait, landscape, square]
        label:
          type: string
          example: 2:3 portrait
        aspect_ratio:
          type: number
          example: 0.667
        count:
          type: integer
          example: 11

    TemplateListResponse:
      type: object
      properties:
        templates:
          type: array
          items:
            $ref: "#/components/schemas/Template"
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            total_pages:
              type: integer
        categories:
          type: array
          items:
            type: string
          description: Every category across the library and your templates, unfiltered.
        ratios:
          type: array
          items:
            $ref: "#/components/schemas/RatioFacet"
          description: Print ratios in the results before the ratio filter, most common first, for building a ratio menu.
        ratio_filter:
          type: object
          nullable: true
          description: The ratio filter that was applied, or null.
          properties:
            requested:
              type: array
              items:
                type: string
            tolerance_percent:
              type: number
            applied_to:
              type: string
              enum: [print]
        artwork:
          type: object
          nullable: true
          description: The artwork that was measured for matching, or null.
          properties:
            width:
              type: number
            height:
              type: number
            format:
              type: string
              nullable: true
            ratio:
              type: number
            name:
              type: string
            orientation:
              type: string
              enum: [portrait, landscape, square]
            label:
              type: string
        relevance_ranked:
          type: boolean
          description: True when `templates` is ordered by search relevance (`q` was given). Do not re-sort it then.

    TemplateSet:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Set ID. Pass it as `set_id` when generating.
          example: 2bed1943-2880-4d40-b3d6-3296aa71e11e
        name:
          type: string
          example: Warm bedrooms
        template_ids:
          type: array
          items:
            type: string
          description: Template IDs in saved order, which is also the order of the generated results.
          example: [bedroom-poster-01, wall-diptych-01, living-room-03]
        template_count:
          type: integer
          example: 3
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    GenerateMockupJsonBody:
      type: object
      properties:
        template_id:
          type: string
          description: One template to render. Required unless `template_ids` or `set_id` is given.
          example: bedroom-poster-01
        template_ids:
          type: array
          items:
            type: string
          maxItems: 12
          description: Several templates to render from the same artwork, up to 12. Needs `response_format=json`.
        set_id:
          type: string
          format: uuid
          description: A saved set to render, in its saved order. Counts toward the 12 template limit. Needs `response_format=json` when the set holds more than one template.
        artwork_url:
          type: string
          format: uri
          description: Public http(s) URL of the artwork (PNG, JPG or WebP). Required unless `artwork_urls` is given.
          example: https://example.com/my-artwork.png
        artwork_urls:
          type: object
          description: One artwork URL per frame, keyed by frame number (`"0"`, `"1"`, ...), for templates with `frame_count` above 1.
          additionalProperties:
            type: string
            format: uri
        format:
          type: string
          enum: [jpeg, png]
          default: jpeg
          description: Output image format.
        quality:
          type: integer
          minimum: 1
          maximum: 100
          default: 85
          description: JPEG quality. Ignored for PNG.
        width:
          type: integer
          minimum: 100
          maximum: 4000
          default: 2000
          description: Output width in pixels. The height follows the template's shape.
        response_format:
          type: string
          enum: [binary, json]
          default: binary
          description: "`binary` returns the image as the response body. `json` returns it as base64, and is required for batches."
        product_color:
          type: string
          description: |
            Recolors the product on templates where `supports_product_color` is true (today
            t-shirts, hoodies and totes), keeping the fabric's folds and shading. A 6-digit
            hex like `#1f2a44`, or `original` for the photo's own color. Other templates
            ignore it. Omit it to use the color the template was saved with.
          example: "#1f2a44"

    GenerateMockupFormData:
      type: object
      properties:
        template_id:
          type: string
          description: One template to render. Required unless `template_ids` or `set_id` is given.
        template_ids:
          type: string
          description: Several template IDs, comma separated, or repeat the field. Up to 12.
        set_id:
          type: string
          description: A saved set to render.
        artwork:
          type: string
          format: binary
          description: Artwork file (PNG, JPG or WebP, up to 20 MB) for single-frame templates.
        artwork_0:
          type: string
          format: binary
          description: Artwork for frame 0 of a multi-frame template. Frames go up to `artwork_5`.
        artwork_1:
          type: string
          format: binary
          description: Artwork for frame 1.
        artwork_2:
          type: string
          format: binary
          description: Artwork for frame 2.
        artwork_3:
          type: string
          format: binary
          description: Artwork for frame 3.
        artwork_4:
          type: string
          format: binary
          description: Artwork for frame 4.
        artwork_5:
          type: string
          format: binary
          description: Artwork for frame 5.
        format:
          type: string
          enum: [jpeg, png]
          default: jpeg
        quality:
          type: integer
          minimum: 1
          maximum: 100
          default: 85
        width:
          type: integer
          minimum: 100
          maximum: 4000
          default: 2000
        response_format:
          type: string
          enum: [binary, json]
          default: binary
        product_color:
          type: string
          description: Product color for templates where `supports_product_color` is true, a 6-digit hex or `original`.

    MockupResult:
      type: object
      properties:
        template_id:
          type: string
        image:
          type: string
          format: byte
          description: The rendered image, base64 encoded.
        format:
          type: string
          enum: [jpeg, png]
        content_type:
          type: string
          example: image/jpeg
        size_bytes:
          type: integer

    GenerateMockupJsonResponse:
      type: object
      description: One template with `response_format=json`.
      properties:
        success:
          type: boolean
        image:
          type: string
          format: byte
          description: The rendered image, base64 encoded.
        format:
          type: string
          enum: [jpeg, png]
        content_type:
          type: string
        size_bytes:
          type: integer
        template_id:
          type: string
        duration_ms:
          type: integer
          description: Rendering time in milliseconds.
        request_id:
          type: string

    GenerateMockupBatchJsonResponse:
      type: object
      description: Several templates, or a set, with `response_format=json`.
      properties:
        success:
          type: boolean
        results:
          type: array
          items:
            $ref: "#/components/schemas/MockupResult"
        count:
          type: integer
          description: Number of mockups rendered (and charged).
        total_size_bytes:
          type: integer
        duration_ms:
          type: integer
        set_id:
          type: string
          description: Present when rendering a set.
        set_name:
          type: string
          description: Present when rendering a set.
        skipped_template_ids:
          type: array
          items:
            type: string
          description: Present when IDs stored in the set no longer exist. They were skipped and not charged.
        request_id:
          type: string

    ApiError:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in plain words.
        code:
          type: string
          description: Machine-readable error code. All codes are listed at https://www.mockupanda.com/docs/api-reference/errors
          example: TEMPLATE_NOT_FOUND
        details:
          type: object
          description: Extra context, when there is any.
        hint:
          type: string
          description: How to fix it.
        request_id:
          type: string
          description: Present on errors from `POST /mockups/generate`.

  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
          examples:
            missing:
              value:
                error: "Missing API key. Use Authorization: Bearer mk_xxx"
                code: MISSING_API_KEY
            invalid:
              value:
                error: Invalid or revoked API key
                code: INVALID_API_KEY

    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
