ZSK Web API

ZSK Web API

CreatePES

POST

Experimental: the PES output is new. Test the created files on your Brother machines and software before you use them in production.

CreatePES creates stitch data in the Brother PES format (extension .pes) from text, from an existing design, or from both. Send it as an HTTP POST with a JSON body to StitchJob (see Overview) with "RequestType": "CreatePES", "ServerVersion": 3 and a valid WebApiLicense (see ZSK Web API License). ServerVersion 1 and 2 are rejected. Key names are case-sensitive, and integer fields need JSON integers ("DistanceMM": 2, not 2.5).

Input

  • Text only: send Monograms and Needle, omit EmbroideryBase64.
  • Existing design only: send EmbroideryType and EmbroideryBase64, omit Monograms (or send an empty list). No Needle list is needed.
  • Design + text: send EmbroideryType, EmbroideryBase64, Monograms and Needle (with a TC or TBF design, "UseEmbroideryColors": 1 can replace Needle, see Colors). TextAlignment with a Mode places the text relative to the design (see TextAlignment to Design).

Text rules: without a design, every monogram needs a non-blank text; up to 9 monograms, one line each, 200 characters in total; FontSizeMM 5 to 50; FontFamily as listed by GetFontList (case-sensitive); UsedNeedle starts at 1. See Monograms.

EmbroideryType is required with every design and must be one of these values (case-sensitive):

EmbroideryTypeFileProcessing
TC.z00Used directly. From ServerVersion 3, an optional SeqAssignmentJson assigns its sequences to new needles and colors.
TBF.tbfUsed directly.
DST.dstConverted to TC with the needle assignment in SeqAssignmentJson (required).
DSZ.dszConverted to DST, then handled like DST input; the sequence indexes in SeqAssignmentJson refer to the converted DST.

PES is an output format only; a PES file cannot be sent as a design. SeqAssignmentJson works as for CreateTC, see NeedleAssignment.

Colors

  • Needle sets the colors by position (first entry = needle 1); each monogram uses the entry in its UsedNeedle, so with text Needle needs at least that many entries. Red, Green, Blue: integers 0 to 255; other fields: strings.
  • A PES file stores no RGB colors. For every color block it stores one of the 64 Brother threads of the PEC palette: the thread nearest to the needle color. Two needles with similar colors can therefore get the same Brother thread. NeedleColor in the response shows the threads that were written.
  • With a TC or TBF design, "UseEmbroideryColors": 1 builds Needle from the design, replacing a sent list; UsedNeedle then selects an entry by position. See UseEmbroideryColors.

Response

On success: HTTP 200 with a JobResponseType with Success true and:

  • RequestData: the created PES file (PES version 1 with PEC block), Base64-encoded.
  • Info: no values for PES output; all fields are 0 or null.
  • NeedleColor: one entry per needle in NeedleSequence with the Brother thread written for it: Red, Green, Blue of the thread, ColorName (Brother thread name), ColorNumber (PEC palette index 1 to 64) and Manufacturer Brother. If the color blocks of the file cannot be matched to the needle sequence, NeedleColor holds the colors of the request or the design instead, as for CreateDST; these entries do not have Manufacturer Brother.
  • NeedleSequence: with a design, the design sequence (a stop starts a new sequence on the same needle), then the monogram needles numbered UsedNeedle + the highest design needle. Text only: the UsedNeedle of each monogram.
  • Time: processing times. PreviewData stays empty, also with WithPreview; use CreatePNG for a preview.

Info, NeedleColor, NeedleSequence and Time are JSON strings: parse each non-empty string a second time. Example for a design + text (formatted and shortened):

{
	"Info": "{ \"widthMm\": 0.0, \"heightMm\": 0.0, ..., \"numberOfStitches\": 0, ... }",
	"NeedleColor": "[ { \"NeedleNumber\": 1, \"Red\": 237, \"Green\": 23, \"Blue\": 31, \"ColorName\": \"Red\", \"ColorNumber\": \"5\", \"Manufacturer\": \"Brother\", ... }, ... ]",
	"NeedleSequence": "[ 1, 2, 3 ]",
	"PreviewData": "",
	"RequestData": "base64 encoded PES data",
	"Success": true,
	"Time": "{ ... }"
}

On error, Success is false and RequestData holds the error message.

Errors

HTTPRequestDataCause
200Error: unknown command!RequestType is not exactly CreatePES.
400CreatePES needs ServerVersion 3 or higher.ServerVersion 1 or 2.
400No licence token found. / Invalid licence token.WebApiLicense is missing, empty or rejected.
400Only one line of text per monogram ... / A maximum of 9 lines ... / The text length is longer ...More than one Text entry, more than 9 monograms, or more than 200 characters.
400Invalid needle color listText without a Needle list, or too few Needle entries for the highest UsedNeedle.
400Invalid monogram text. Found empty textNo design, and Monograms is missing or empty or a monogram text is blank.
400Invalid font size. ... / Invalid font name(s). ... / The text contains not supported character(s): ...FontSizeMM outside 5 to 50, FontFamily not listed by GetFontList, or characters the font does not support.
400embroideryData.Length == 0DST or DSZ input without a valid SeqAssignmentJson.
400ApplyNasTC: ... (for example ApplyNasTC: Sequence 1 is not assigned to a cone)TC input: SeqAssignmentJson does not fit the design, or the design has K-head (Moos/Kettel) needles. See NeedleAssignment.
500Error messageUnexpected error, for example invalid Base64 in EmbroideryBase64.
503Error messageThe stitch data could not be created; retry later.

Parameters

Parameter Type Description Required
RequestType string Must be exactly "CreatePES" (case-sensitive). Yes
ServerVersion int API version. Send 3; 1 and 2 are rejected. Yes
WebApiLicense string License key, see ZSK Web API License. Yes
EmbroideryType string "TC" (Z00), "TBF", "DST" or "DSZ" (case-sensitive): type of the design in EmbroideryBase64. Required with every design; DST and DSZ also need SeqAssignmentJson. TC can use it from ServerVersion 3. No
EmbroideryBase64 string Base64-encoded design file. Required for design only and design + text; omit it for text only. No
Monograms array Text lines: up to 9 monograms, one line each, 200 characters in total, non-blank without a design; UsedNeedle starts at 1 (see Monograms). Omit it or send an empty list for design only. No
Needle array Needle colors by position (first entry = needle 1), required with text and covering the highest UsedNeedle, unless UseEmbroideryColors is 1 with a TC or TBF design. Red, Green, Blue: int 0..255, the other fields strings; the PES file gets the Brother thread nearest to each color. No
UseEmbroideryColors int 1 = build the Needle list from a TC or TBF design, replacing a Needle list in the request; UsedNeedle then selects an entry by position. No effect for text only or DST/DSZ input. Ignored for TC input with SeqAssignmentJson (ServerVersion 3). No
SeqAssignmentJson string Needle assignment (NeedleAssignment, UsedConeDefs) as a JSON string, required for DST and DSZ input, optional for TC input from ServerVersion 3 (see NeedleAssignment). No
TextAlignment object Places the text relative to the design when Mode is set (design + text only): Mode (Top, Bottom, Left, Right, Manual; not case-sensitive), Alignment, DistanceMM (int), and xPosMM/yPosMM for Mode Manual (see TextAlignment to Design). No
LineSpacing array Extra spacing in mm between consecutive text lines, one double per gap, e.g. [5.0]; used with two or more monograms (see Linespacing). No
Rotation int Rotation of the whole output in degrees, 0..359 (see Rotation). No

Example

{
	"RequestType": "CreatePES",
	"EmbroideryType": "TC",
	"EmbroideryBase64": "base64 encoded embroidery data",
	"Monograms": [
		{
			"Text": [
				"Heart"
			],
			"FontFamily": "Arial",
			"FontSizeMM": 10.0,
			"UsedNeedle": 2,
			"TextStitchParameter": "Premium"
		}
	],
	"Needle": [
		{
			"Red": 196,
			"Green": 30,
			"Blue": 58,
			"ColorName": "radiant red"
		},
		{
			"Red": 0,
			"Green": 0,
			"Blue": 0,
			"ColorName": "Black"
		}
	],
	"Rotation": 0,
	"TextAlignment": {
		"Mode": "Bottom",
		"Alignment": 1,
		"DistanceMM": 2
	},
	"ServerVersion": 3,
	"WebApiLicense": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
}