---
title: "Render a PSD mockup"
method: POST
path: "/api/v1/renders"
tags: ["PSD mockups"]
---

# Render a PSD mockup

`POST /api/v1/renders`

## Request

- Base URL: `https://api.sudomock.com`
- URL: `https://api.sudomock.com/api/v1/renders`
- Auth: API key in header `x-api-key`

Renders a mockup by compositing layers with user-provided images.

## Request body

- RenderRequest: What to render: which mockup, what goes into it, and how to export it.
  - `mockup_uuid` string, required: UUID of the mockup to render. Must be a valid UUID, for example c315f78f-d2c7-4541-b240-a9372842de94. Obtained from the POST /api/v1/psd/upload or GET /api/v1/psd-mockups response.
  - `smart_objects` SmartObjectInput[]: List of smart objects with their assets. Required unless text_layers, group_layers or hidden_layers is provided.
    - `uuid` string, required: UUID of the smart object to render
    - `asset` AssetInput: The image to place into a smart object, and how it should sit there. Image source priority: base64 > url (including data: URLs) - base64: Raw base64 string (no data: prefix). Suits small images already in memory. - url: HTTP/HTTPS URL or data:image/...;base64,... URL. Suits large files.
      - `url` string, nullable: URL to the user's image (HTTP/HTTPS or data: URL). Either url or base64 must be provided. The server fetches the image, so the request stays small: the right choice for large files.
      - `base64` string, nullable: Raw base64-encoded image bytes (no data: prefix). Either url or base64 must be provided. Saves the server-side fetch for small images already in memory. Base64 adds about a third to the file size and the whole request must finish uploading within 60 seconds, so send large files by url.
      - `content_type` string, nullable: MIME type when using base64 field. Supported: image/png, image/jpeg, image/webp, image/gif. Defaults to image/png if omitted.
      - `fit` 'fill' | 'fit' | 'crop': How the artwork meets the smart object area. 'fit' scales it until it fits inside, keeping proportions, which can leave empty space. 'fill' stretches it to the bounds and does not keep its proportions. 'crop' covers the area and cuts the overflow, keeping proportions. 'contain' and 'cover' are the older names for 'fit' and 'crop' and are still accepted. Defaults to 'fit': a caller who says nothing is not asking to have their artwork distorted, and a silently stretched design is a defect the caller cannot see.
      - `size` AssetSize: How large the artwork is drawn inside the smart object. Fractional pixels are accepted.
        - `width` number, nullable: Custom width in pixels
        - `height` number, nullable: Custom height in pixels
      - `position` AssetPosition: Where the artwork sits inside the smart object. Fractional pixels are accepted.
        - `top` number, nullable: Top offset in pixels
        - `left` number, nullable: Left offset in pixels
      - `rotate` number: Rotation angle in degrees (clockwise positive). Applied to the artwork before it is fitted, so the turned artwork, corners included, is what fit places inside the still axis-aligned size box at position.
      - `flip_horizontal` boolean: Flip artwork horizontally (left-right mirror)
      - `flip_vertical` boolean: Flip artwork vertically (top-bottom mirror)
      - `remove_background` boolean: Remove the image background before placing the artwork; the subject is isolated onto a clean transparent cutout. Adds 25 credits per artwork to the render cost.
    - `color` ColorOverlay: A colour laid over the smart object, with a blending mode.
      - `hex` string, nullable: Hex color code (e.g., '#FF5733'). Send this or 'label'.
      - `label` string, nullable: One of the colours saved on this mockup, by the name you gave it. Send this instead of 'hex' to keep calling a colour what your own catalogue calls it. Names match exactly, and are set with PATCH /api/v1/psd-mockups/{uuid}.
      - `blending_mode` string: Blend mode for color overlay. Common values: 'normal', 'multiply' (fabric/textile mockups), 'screen', 'overlay', 'soft_light'. All 27 Photoshop blend modes supported.
    - `adjustment_layers` AdjustmentLayers: Image adjustment parameters applied to the user's artwork before blending into the mockup. Applied after fit transformation, does not affect PSD-level adjustments.
      - `brightness` integer: Brightness adjustment (-150 to 150). 0=no change.
      - `contrast` integer: Contrast adjustment (-100 to 100). 0=no change.
      - `opacity` integer: Artwork opacity (0=fully transparent, 100=fully opaque). Default 100.
      - `saturation` integer: Saturation adjustment (-100 to 100). 0=no change, -100=grayscale.
      - `vibrance` integer: Vibrance adjustment (-100 to 100). Similar to saturation but preserves skin tones.
      - `blur` number: Gaussian blur amount (0=sharp, 100=max blur). Useful for background effects.
  - `text_layers` TextLayerInput[], nullable: Up to 50 text-layer overrides. Each entry targets a text-layer UUID and provides exactly one of text for a single-style layer or segments for a mixed-style layer. Omitted layers and styling fields keep their authored values.
    - `uuid` string, required: UUID of the text layer to update (from the upload/detail response text_layers list)
    - `text` string, nullable: Replacement text (1-500 characters) for single-style layers (segment_count = 1)
    - `segments` TextSegmentInput[], nullable: Styled-segment overrides for multi-style layers (segment_count > 1). Override any subset by index; omitted segments keep their original text.
      - `index` integer, required: Segment to replace (0-based, from the layer's segments list)
      - `text` string, required: Replacement text for this segment (1-200 characters). The segment keeps its own font, size, and color.
    - `font` string, nullable: Font to render with: a font uuid from GET /fonts, or a PostScript name. Single-style layers only. Omit to keep the layer's original font.
    - `font_size` number, nullable: Font size in pixels at the mockup's native resolution. Single-style layers only. Omit to keep the original size.
    - `color` string, nullable: Text color as hex, e.g. #1A1A1A. Single-style layers only. Applies to the color you see: when the layer's visible color comes from a color effect, that effect takes the new color. Omit to keep the original color.
    - `stroke_color` union: Color for this text layer's own outlines. Send a hex value like "#FFFFFF" to recolor the front outline, or a list in stroke_count order (front to back). Use null to keep an outline's original color; extra entries are ignored. Layers with no outlines ignore this value with a warning. Single-style layers only. Omit to keep all original outline colors.
      - string
      - string[]
    - `fit` 'shrink' | 'clip' | 'overflow': How longer replacement text is handled for single-style point text: 'overflow' (default) preserves the designed size and may extend beyond the original area; 'shrink' scales the text down to fit; 'clip' preserves the size and cuts it at the last character that fits. Paragraph text continues to wrap within its box.
    - `vertical_align` 'top' | 'bottom' | 'center': Where text that 'fit': 'shrink' scaled down sits vertically within the original text area: 'top' (default) keeps the designed position, 'center' centers it in the area, 'bottom' aligns it to the area's bottom edge. Only applies when shrinking actually occurs; single-style point text only.
  - `group_layers` GroupLayerInput[], nullable: Group outline overrides. Each entry addresses a listed group by its own UUID; the change affects everything inside that group.
    - `uuid` string, required: UUID of the group layer to update (from the upload/detail response group_layers list)
    - `stroke_color` union, required: Color for the group's outlines. Send a hex value like "#FFFFFF" to recolor the front outline, or a list in stroke_count order (front to back). Use null to keep an outline's original color; extra entries are ignored. The change affects everything inside this group.
      - string
      - string[]
  - `hidden_layers` string[], nullable: Up to 50 layers to leave out of this render, each by the UUID that GET /api/v1/psd-mockups/{uuid}/layers lists for it, including the layers inside a smart object's contents. Hiding a group hides every layer inside it, and a layer clipped to a hidden layer is hidden with it, as in Photoshop. A layer hidden inside a smart object's contents is hidden in every copy of that smart object. A layer cannot be hidden and edited in the same request, and a smart object that receives an image cannot have layers inside it hidden. Omit to draw every layer the template shows.
  - `export_options` ExportOptions: Format, size and quality of the rendered file.
    - `image_format` 'png' | 'jpg' | 'webp': Output format: 'webp' (30-70% smaller, recommended), 'png' (lossless), 'jpg' (smallest, no transparency)
    - `image_size` union: Output width in pixels (100-10000), or "original" to render a PSD template at its own size and resolution: the template's own width and, unless dpi is set, the resolution the PSD was saved with. Height auto-calculated from the source aspect ratio. Renders on an account in trial are capped at 1024: a larger width is rejected with error_code OUTPUT_RESOLUTION_LIMIT (HTTP 402) and is never silently downscaled. Add a payment method to render at full width.
      - integer
      - 'original'
    - `quality` integer: Compression quality for JPG/WebP (1-100). Ignored for PNG (always lossless). Default: 90.
    - `dpi` integer, nullable: Resolution tag stamped into the output file metadata (JPG/WebP via Exif XResolution, PNG via pHYs), e.g. 300 for print. This is metadata only: it does NOT change the pixels. Pixel dimensions are controlled by image_size: set image_size = print_size_inches * dpi for a true print-ready file (e.g. 12 in * 300 = 3600 px). Range 72-2400. Default: null (opt-in). Omitting it does not leave the file untagged: the encoder writes a default ~25.4 DPI (1 px/mm) tag. With image_size "original" and no dpi, the file carries the PSD's own resolution. All three formats carry the tag, but for maximum print-tool compatibility prefer jpg or png, because WebP stores resolution in Exif and not every viewer surfaces it.
  - `export_label` string, nullable: Optional label for export file naming (max 100 chars, alphanumeric + hyphen/underscore)
  - `is_async` boolean: If true, the render is QUEUED and the call returns 202 immediately with a job_id (poll GET /api/v1/jobs/{job_id}, or receive a webhook if one is configured). If false (default), the render runs synchronously and returns the result.

## Response `200`

Successful Response

- RenderResponse: The finished render and where to fetch it.
  - `data` RenderResponseData, required: Data payload in render response
    - `print_files` PrintFile[], required: List of rendered print files
      - `export_path` string, required: Path to the rendered output file
      - `smart_object_uuid` string, required: UUID of the first Smart Object in the request; an empty string for a render without Smart Objects, including text-only and group-only renders.
      - `render_uuid` string, nullable: The render's transaction id (also the async job uuid). Returned so storefront/Studio fulfillment flows can correlate the render; null on legacy paths.
    - `render_uuid` string, nullable: The render's transaction id (also the async job uuid). Echoed at the data level for convenience; null on legacy paths.
  - `success` boolean: Success status
  - `warnings` RenderWarning[], nullable: Non-fatal advisories about this render (e.g. requested size above the mockup's native resolution). Omitted when none.
    - `code` string, required: Stable advisory code
    - `message` string, required: Human-readable, non-fatal advisory

## Other responses

- `202`: Render queued (is_async=true). Poll status_url for the result.

---

[API](https://skmtc.dev/sudomock/apis/sudomock-api.md) · [All operations](https://skmtc.dev/sudomock/apis/sudomock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sudomock/apis/sudomock-api/revisions/c1cc24006c60?raw)