Generate preview image for lettering

The newLetteringPreview API method generates a fast, lightweight, transparent preview image (non-TrueView™) of a single new lettering decoration or a single new Team Name (with one name, one location). Also returns estimated design information — such as dimensions and stitch count — similar to api/designInfo.

This is not a TrueView™ image — it’s a simpler, faster preview.

---

POST parameters

Parameter	Type	Required	Description
appId	String	✅	App ID from your Wilcom Developer Portal account.
appKey	String	✅	App Key from your Wilcom Developer Portal account.
requestXml	String	✅	An XML string specifying the lettering recipe.

---

XML structure

<xml>

  <recipe ... /> <!-- Lettering recipe definition -->

    <lettering 

      text="Coach" 

      font="Block" 

      height="10" 

    />

    <output 

      trueview_file="lettering_preview.png" 

    />

  </recipe>

</xml>

---

Response

On success, the API returns an XML string containing the generated preview image and the estimated design information:

<xml>

  <files>

    <file filename="lettering_preview.png" filecontents="..." />  <!-- Simple preview image -->

  </files>

  <design_info>...</design_info>                                   <!-- Estimated metadata -->

</xml>

---

XML components

Component	Details
<recipe>	The design is based on the full <recipe> definition. This is the root container for describing a complete embroidery design or preview.
<lettering>	Specifies single new lettering decoration or single new Team Name (with one name, one location).
<output>	Specifies the output preview filename.
<files>	This element is used to pass one or more files to or from API endpoints. It contains the input vector file and the resulting design and TrueView™ file(s).
<file>	Simple preview image.
<design_info>	Provides estimated design properties — e.g. size, stitch count — for the generated embroidery file.

---

Remarks

1. The newLetteringPreview method positions a single Lettering or Team Name Lettering decoration according to the transform defined in the recipe.
   
2. It then generates a small, transparent preview image (non-TrueView™) that visually represents the stitched area in a simplified form.
   
3. The resulting image is included in the <files> element and named according to the trueview_file parameter of the output component in the recipe.
   
4. The preview image is lower in visual fidelity compared to the TrueView™ image produced by api/newDesignTrueview, but the process is significantly faster.
   
5. The <design_info> element provides an estimated preview of the design’s dimensions and stitch count. These estimates may differ slightly from the actual values produced by api/designInfo or api/newDesign using the same input.
   
6. This method is ideal when fast previews are needed and image quality is not critical. For a full TrueView™ rendering, use api/newDesignTrueview.

---

Related topics

1. There are specific limitations on input bitmap files for auto-digitizing. Refer to Auto-digitize artwork limitations for guidelines and best practices.
2. Supported bitmap formats are listed in Supported formats section of this document.

• Related Articles

• Creating production-ready embroidery lettering

  When selling decorated garments online, it’s not enough to simply let customers type in text and place it on a shirt. Unlike printing, embroidery requires fabric-specific settings to produce good stitch quality. The same lettering will need different ...

• Protecting against unsuitable image uploads

  Auto-digitizing (automatic digitizing) converts artwork into embroidery files. The Embroidery Web API uses AI to reduce colors, define objects, and choose stitch types and directions, similar to what a human digitizer would do. ⚠️ Not all images are ...

• EWA API capabilities

  Wilcom’s Embroidery Web API (EWA) provides a RESTful interface for integrating advanced embroidery capabilities into web and cloud-based applications. The API exposes functionality for rendering, modifying, and generating embroidery designs using ...

• How do I connect an CD/DVD ISO Image to a virtual machine

  For: CorelDraw 2023 VM: Parallels Device: Mac OS: iOS - M3 chip running Ventura 14.21 Please follow the steps provided in the link below on how to install the ISO image of CDGS 2023 to a VM [via PARALLELS]. How do I connect an CD/DVD ISO Image to a ...

• Preview designs

  The Preview Design feature allows you to view a visual representation of an embroidery design directly within Wilcom Library. Previewing a design helps you quickly inspect the design layout, colors, and overall appearance without downloading or ...