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 ...

• Generate estimates

  Generate embroidery stitch estimates from artwork or embroidery designs. Estimator analyzes your artwork and calculates an estimated stitch count in seconds. If your organization's pricing has been configured, it also calculates production and ...

• 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 ...