创建刺绣任务接口

接口概述

根据单张图片异步生成刺绣 DST 文件和效果图，返回任务 ID。通过查询任务接口获取状态和结果。

网络协议	请求地址	请求方法	鉴权方式	请求格式	响应格式
HTTPS	/open-api/v1/embroidery/create-task	POST	Bearer	multipart/form-data	application/json

请求头（Headers）

参数名称	值	描述
Authorization	Bearer	使用获取 token 接口返回的 token
Content-Type	multipart/form-data	使用 FormData 或 curl --form 时，由客户端自动生成包含 boundary 的请求头

请求体（HTTP Form 表单提交）

参数名称	类型	必填	参数描述
image	file	与 image_url 二选一	输入图片，支持 png、jpeg、jpg、webp；不超过 20 MB（20 × 1024 × 1024 字节）；仅 1 张，不能为空文件
image_url	string	与 image 二选一	可访问的输入图片 HTTP(S) URL；图片格式和大小限制同 image；仅 1 个 URL
width	number	是	成品宽度，单位 mm，范围 30～200（含边界），支持小数，例如 100.25
color_count	int	是	最大颜色数量，范围 1～16（含边界），仅支持整数
density	int	是	针迹密度：1=低、2=中、3=高，仅支持整数

image 和 image_url 不能同时提供，也不能都不提供。width、color_count、density 均无默认值，必须显式传入。URL 方式也使用 multipart/form-data 表单。

输出固定为 DST 文件和效果图，无需传 format、model 或 version。当前接口不支持 callback_url，请轮询查询任务接口。

响应体（Response）

参数名称	子字段	类型	描述
code	-	int	200 表示提交成功；不代表生成完成
data	task_id	string	异步任务 ID，用于查询任务
	state	string	创建成功后为 queueing
msg	-	string	响应信息

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

错误码（Error Code）

错误码	错误信息示例	描述
1003	width only supports 30-200 mm	参数范围、类型或必填校验失败
1003	color_count only supports 1-16	颜色数量越界
1003	density only supports 1, 2, 3	密度越界
1003	width is required	缺少必填参数；其他字段同样返回字段名和校验说明
10031001	Upload file size exceeds limit	图片超过大小限制
10031005	images only allow png jpeg jpg webp	图片格式不支持
10031019	image and image_url must provide exactly one	图片文件和 URL 未满足二选一规则

错误响应沿用通用 code、msg 结构；msg 可能随语言和错误类型变化。客户端应根据 code 判断错误，不要依赖完整提示文本。

请求示例（Shell）

上传文件：

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'

使用图片 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'