Text Layers

What Text Layer Rendering Means

A text layer is live, editable type inside a PSD, the kind a designer uses for a headline, a name, or a price. SudoMock reads those layers on upload and lets you swap the wording, font, size, and color at render time, so one template becomes an endless run of personalized images. Most PSD mockup tools flatten or ignore text; SudoMock renders it and stays faithful to the style the designer built.

Text output is checked side by side against Photoshop reference exports for documented supported cases. Validate each production PSD against the compatibility matrix before shipping.

What You Get on Upload

Every POST /api/v1/psd/upload response lists the text layers it found under text_layers. Each one carries its current text, font, size, color, whether that font is available in your catalog, and whether it can be edited in this version.

1{
2  "success": true,
3  "data": {
4    "uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
5    "name": "Greeting Card Front",
6    "smart_objects": [ /* ... */ ],
7    "text_layers": [
8      {
9        "uuid": "b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60",
10        "name": "Headline",
11        "text_content": "YOUR BRAND",
12        "font_postscript_name": "Poppins-Bold",
13        "font_size": 96,
14        "color": "#1A1A1A",
15        "font_available": true,
16        "is_editable": true,
17        "segment_count": 1,
18        "has_stroke_effect": true,
19        "stroke_count": 2,
20        "has_color_overlay": false,
21        "enclosing_group_layers": [
22          "9d7e4b18-3a65-4c21-8f90-2b6d7e1a5c43"
23        ]
24      }
25    ],
26    "group_layers": [
27      {
28        "uuid": "9d7e4b18-3a65-4c21-8f90-2b6d7e1a5c43",
29        "name": "Headline Outline",
30        "has_stroke_effect": true,
31        "stroke_count": 1
32      }
33    ],
34    "collections": []
35  },
36  "message": ""
37}

The top-level group_layers list contains each editable outline group's uuid, name, has_stroke_effect, and stroke_count. Presence in this list is the editability signal.

Personalizing at Render Time

Add up to 50 entries to text_layers, with only the layers you want to change. Each entry needs the layer uuid and exactly one of text or segments. A text value is 1 to 500 characters; font, font_size, and color are optional for single-style layers and fall back to the layer's original values. The font value is either a catalog font uuid or its PostScript name from GET /api/v1/fonts.

1{
2  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
3  "smart_objects": [
4    {
5      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
6      "asset": { "url": "https://your-cdn.com/design.png", "fit": "cover" }
7    }
8  ],
9  "text_layers": [
10    {
11      "uuid": "b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60",
12      "text": "SUMMER SALE",
13      "font": "Poppins-Bold",
14      "font_size": 96,
15      "color": "#C0392B",
16      "stroke_color": ["#C0392B", "#FFFFFF"],
17      "fit": "shrink",
18      "vertical_align": "center"
19    }
20  ]
21}

Fitting Replacement Text

A replacement can be longer than the text it stands in for. The optional fit field on a single-style text layer decides what happens when the new text is wider than the layer's area:

• overflow (default): the text keeps its size and may extend past the layer's area.
• clip: the text keeps its size and is cut to what fits.
• shrink: the text is scaled down so it stays inside the layer's area.

Paragraph (box) layers wrap on their own, and mixed-style layers keep their own layout, so fit does not apply to them.

Smaller text leaves room in the layer's area. The optional vertical_align field decides where it sits there, and takes effect only when shrink actually reduces the text on a single-style point-text layer:

• top (default): the text stays where the designer placed it.
• center: the text sits in the vertical middle of the area.
• bottom: the text sits on the area's bottom edge.

Recoloring Text and Outlines

color changes the color you actually see. Designers often give a text layer its final color through a color effect rather than the fill; SudoMock applies your color to whichever one defines the visible color, so the result always matches what you asked for. The upload response tells you up front: has_color_overlay is true when the layer's visible color comes from a color effect.

Layers with an outline effect can be recolored too. Set stroke_color to a hex string to recolor the front outline owned by that text layer while keeping its width and placement. For stacked outlines, send a front-to-back list to recolor each outline independently. Use null in any position to keep that outline as designed. The upload response reports stroke_count; a value of 2 or more means the layer has a stack. Entries beyond that count are ignored. A layer with has_stroke_effect true in the upload response has at least one outline of its own and supports this override.

An outline owned by an enclosing group is separate. Use the group UUID from enclosing_group_layers and send it through group_layers. You can send up to 50 group overrides; each one changes the group outline around everything inside that group.

• TEXT_STROKE_NOT_PRESENT: you sent stroke_color, as a hex or list, for a layer with no outline of its own. The render succeeds and the value is ignored; use group_layers for an enclosing group outline.
• TEXT_COLOR_HIDDEN_BY_EFFECT: the layer has a gradient effect covering the text, so the requested color may not be visible in the result.

Editing Mixed-Style Layers

When a single layer mixes styles, like a thin first name next to a bold surname, the upload response marks it with segment_count greater than 1 and lists each run under segments. Personalize it by sending a segments array with only the runs you want to change, each by its index. Every segment keeps its own font, size, and color, and any run you leave out keeps its original text. Send 1 to 32 segment entries per layer, with 1 to 200 characters in each entry. One render can contain at most 200 segment overrides across all text layers, and one layer's effective combined segment text can contain at most 500 characters.

1{
2  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
3  "text_layers": [
4    {
5      "uuid": "b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60",
6      "segments": [
7        { "index": 0, "text": "Jane " },
8        { "index": 1, "text": "SMITH" }
9      ]
10    }
11  ]
12}

Fonts

The built-in font catalog is the full open-licensed Google Fonts library (2,000+ families under OFL, Apache, and UFL licenses), free to use in commercial work. Pro and Scale plans can also upload their own TTF and OTF fonts.

List, search, and filter the catalog with GET /api/v1/fonts. On Pro and Scale plans, upload your own fonts with POST /api/v1/fonts (TTF and OTF, up to 5 MB each) and remove them with DELETE /api/v1/fonts/{uuid}. Pro includes 10 custom fonts; Scale is unlimited. See the Fonts API reference for request fields, pagination, and responses.

1curl -X POST https://api.sudomock.com/api/v1/fonts \
2  -H "X-API-KEY: sm_your_api_key" \
3  -F "[email protected]" \
4  -F "license_confirmed=true"

When a Font Is Missing

When no replacement font is supplied, SudoMock uses the PSD layer's original font when available. If an original or resolved catalog font file cannot be loaded at render time, the render uses a default font and returns a TEXT_FONT_FALLBACK warning. An explicitly requested font that is not in your catalog returns 422 FONT_NOT_FOUND.

A fallback for an original or resolved catalog font file that cannot be loaded does not fail the render. It attaches a warning so you can upload the exact font or pick another catalog font and render again. An explicitly requested font that is not in your catalog does not fall back; it returns 422 FONT_NOT_FOUND.

1{
2  "success": true,
3  "data": { "print_files": [ /* ... */ ] },
4  "warnings": [
5    {
6      "code": "TEXT_FONT_FALLBACK",
7      "message": "Original font not in catalog; rendered in a default font."
8    }
9  ]
10}

What Is Supported (as of July 2026)

A few layer types and styles -- vertical text and justified alignment -- are not editable in this version, so they render exactly as they look in the PSD. Each has a one-step workaround in the table above, so your layout still survives the upload.

Optical kerning nuances and ligature toggles may differ slightly from the original.

Fine-Tuning for the Most Demanding Work

Everything above renders true to the original with no setup. When a job is unusually exacting, a wordmark, a packaging line, a piece of editorial type, a few choices in Photoshop before upload give you the most precise possible result. None of these are required; they are ways to hand the render even more to work from.

• Bold that has to be perfect. SudoMock reproduces Photoshop's synthetic bold faithfully. For a large headline or a logotype, you can also pick the font's own Bold weight in Photoshop, so the render uses the type designer's drawn bold shapes rather than a synthesized one.
• Underline or strikethrough you want to control to the pixel. Both decorations carry over exactly as set. When you need a rule of a specific thickness or offset, say a custom underline under a wordmark, draw it as its own line or shape layer; it renders exactly where you place it, independent of the font's built-in metrics.
• Line spacing that is critical. Leading renders true to the original across every line. If the spacing has to land on an exact value, set an explicit leading in Photoshop rather than leaving it on Auto, so the spacing is fixed by you rather than derived from the font.
• The finest small caps. Small caps render as designed. For the most refined small-cap typography, choose a family that ships true small-cap glyphs (the smcp feature); those purpose-drawn glyphs give a more polished result than scaled capitals.

Errors and Warnings

Errors block a render so you can fix the request; warnings ride along with a successful render so you know exactly what happened. The codes are stable, so you can branch on them in your integration. Every item in the warnings array contains only code and message.

The full feature matrix, including everything beyond text, lives on the PSD Compatibility page, and the request and response fields are documented on Render Mockup.

Frequently Asked Questions