Generate preview image for lettering

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.
Info
This is not a TrueView™ image — it’s a simpler, faster preview.

POST parameters

ParameterTypeRequiredDescription
appIdString✅App ID from your Wilcom Developer Portal account.
appKeyString✅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

ComponentDetails
<recipe>The design is based on the full <recipe> definition. This is the root container for describing a complete embroidery design or preview.
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.

  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.