ZSK Web API

CreateDSZ

POST

CreateDSZ creates stitch data in the DSZ format (extension .dsz) 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": "CreateDSZ", "ServerVersion": 3 and a valid WebApiLicense (see ZSK Web API License). 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):

EmbroideryType	File	Processing
`TC`	.z00	Used directly.
`TBF`	.tbf	Used directly.
`DST`	.dst	Used directly, without conversion to TC.
`DSZ`	.dsz	Used as is, without conversion, with or without text.

Text, if present, is added to the design. CreateDSZ needs no needle assignment (SeqAssignmentJson), not even for DST or DSZ input.

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.
Only Red, Green, Blue and ColorName are passed on to the stitch generation; only CreateTC writes the other fields into its output.
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 DSZ file, Base64-encoded.
Info: widthMm, heightMm, maxX, maxY, minX, minY and numberOfStitches of the created DSZ file; maxX/maxY/minX/minY are distances in mm from the start point (widthMm = maxX + minX, heightMm = maxY + minY). The other fields (also numberOfCuts, TC output only) are 0 or null.
NeedleColor: with a design, empty. Text only: one entry per monogram (its UsedNeedle and that Needle entry).
NeedleSequence: with a design, empty. 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\": ..., \"heightMm\": ..., ..., \"numberOfStitches\": ..., ... }",
	"NeedleColor": "",
	"NeedleSequence": "",
	"PreviewData": "",
	"RequestData": "base64 encoded DSZ data",
	"Success": true,
	"Time": "{ ... }"
}

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

Errors

HTTP	RequestData	Cause
200	Error: unknown command!	`RequestType` is not exactly `CreateDSZ`.
400	No licence token found. / Invalid licence token.	`WebApiLicense` is missing, empty or rejected.
400	Only 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.
400	Invalid needle color list	Text without a `Needle` list, or too few `Needle` entries for the highest `UsedNeedle`.
400	Invalid monogram text. Found empty text	No design, and `Monograms` is missing or empty or a monogram text is blank.
400	Invalid 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.
500	Error message	Unexpected error, for example invalid Base64 in `EmbroideryBase64`.
503	Error message	The stitch data could not be created; retry later.

Parameters

Parameter	Type	Description	Required
`RequestType`	string	Must be exactly "CreateDSZ" (case-sensitive).	Yes
`ServerVersion`	int	API version. Send 3.	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 need no needle assignment.	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; only Red, Green, Blue and ColorName affect the DSZ file.	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.	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": "CreateDSZ",
	"EmbroideryType": "DST",
	"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"
}