Create Embroidery Task

Overview

Asynchronously generate an embroidery DST file and preview image from one input image. Use the returned task ID with Query Task to retrieve status and results.

Protocol	Endpoint	Method	Authentication	Request format	Response format
HTTPS	/open-api/v1/embroidery/create-task	POST	Bearer	multipart/form-data	application/json

Headers

Parameter	Value	Description
Authorization	Bearer	Token returned by Get Token
Content-Type	multipart/form-data	With FormData or curl --form, let the client generate the header with its boundary

Request Body (HTTP Form)

Parameter	Type	Required	Description
image	file	Exactly one of image and image_url	One nonempty png, jpeg, jpg, or webp image; maximum 20 MB (20 × 1024 × 1024 bytes)
image_url	string	Exactly one of image and image_url	One accessible HTTP(S) image URL; same image format and size limits as image
width	number	Yes	Finished item width in mm; 30–200 inclusive; decimals supported, for example 100.25
color_count	int	Yes	Maximum number of colors; integer from 1 to 16 inclusive
density	int	Yes	Stitch density: 1=low, 2=medium, 3=high; integer only

Do not provide both image and image_url or omit both. width, color_count, and density have no defaults and must be supplied. URL requests also use multipart/form-data.

Output is a DST file and preview image. Do not supply format, model, or version. callback_url is currently unsupported; poll the query endpoint.

Response

Parameter	Child field	Type	Description
code	-	int	200 means submission succeeded, not that generation is complete
data	task_id	string	Asynchronous task ID
	state	string	queueing after successful submission
msg	-	string	Response message

{"code":200,"data":{"task_id":"embroidery_example_task","state":"queueing"},"msg":"success"}

Error Codes

Code	Example message	Description
1003	width only supports 30-200 mm	Invalid parameter range, type, or missing required value
1003	color_count only supports 1-16	Color count outside the allowed range
1003	density only supports 1, 2, 3	Unsupported density
1003	width is required	Missing required field; other fields follow the same field-name and validation-message format
10031001	Upload file size exceeds limit	Image exceeds the size limit
10031005	images only allow png jpeg jpg webp	Unsupported image format
10031019	image and image_url must provide exactly one	Missing or conflicting image sources

Errors use the standard code and msg response fields. Messages may vary with language and error type. Handle errors by code rather than matching the full message.

Request Examples (Shell)

File upload:

curl --location 'https://api.hitem3d.ai/open-api/v1/embroidery/create-task' \
  --header 'Authorization: Bearer {{token}}' \
  --form 'image=@"/path/to/input.png"' \
  --form 'width=100' \
  --form 'color_count=8' \
  --form 'density=2'

Image URL:

curl --location 'https://api.hitem3d.ai/open-api/v1/embroidery/create-task' \
  --header 'Authorization: Bearer {{token}}' \
  --form 'image_url=https://example.com/input.png' \
  --form 'width=100' \
  --form 'color_count=8' \
  --form 'density=2'