刺绣 文件转换器
登录免费注册
API 参考 · v1JSON + multipart

将刺绣功能集成到 您的产品中。

用于私有图像描针和真实机器文件转换的实用 REST API。本页包含完整的快速入门、端点参考和错误指南。

获取 API 密钥OpenAPI 3.1

基础 URL

https://embroideryfileconverter.com/api/developer/v1

身份验证

Bearer 密钥

速率

60/min

作业

异步

密钥具有作用域、会过期、可立即撤销，且仅显示一次。请将其保存在您的服务器上，切勿在浏览器或移动客户端代码中嵌入。

概览快速入门身份验证创建作业作业生命周期端点参考错误与限制
快速入门

三步完成您的首个作业。

01

创建密钥

仅选择服务所需的权限，并将密钥存储在服务器端密钥管理器中。

02

发送源文件

使用 POST multipart 表单数据提交工作流、输出格式和一个私有源文件。

03

轮询作业

使用返回的工作流和作业 ID，直到状态变为已完成或失败。

创建转换作业 · Shell
curl -X POST https://embroideryfileconverter.com/api/developer/v1/jobs \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json" \
  -F "workflow=conversion" \
  -F "format=dst" \
  -F "[email protected]"

身份验证

带作用域的 Bearer 密钥。

在每个请求的 Authorization 标头中发送密钥。密钥仅能访问其所有者的作业，且仅限于创建时选择的权限。

formats:read
usage:read
jobs:read
jobs:write
Authorization 标头
Authorization: Bearer efc_live_...
Accept: application/json

仅限服务器端

切勿在网页、分发的桌面二进制文件或移动应用中嵌入开发者密钥。请通过后端代理请求。

需要委托用户访问权限？

AI 客户端应使用带 OAuth 和 PKCE 的 MCP，而非接收开发者 API 密钥。

POST /jobs

选择与源文件匹配的工作流。

workflow=conversion

现有机器文件

上传 PES、DST、JEF 或其他可读刺绣格式，并选择不同的可写输出格式。

所需
workflow, format, file
最大文件
50 MB
workflow=digitising

JPG、PNG、SVG 或 WebP 图像

从图像生成针迹预览。需要指定成品宽度和最大线色数量。

附加字段
width_mm, colour_count
有效范围
10–300 mm · 1–24 色
最大文件
20 MB

单个文件与批量

使用 file 用于单个源文件，或 files[] 用于最多 10 个源文件。有限的免费处理可能每请求仅接受一个文件。每个批次使用共享的工作流和输出格式。
202 Accepted
{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}

创建为异步操作

HTTP 202 表示私有作业已接受，但机器文件尚未就绪。请保存 job.id 和 job.workflow; 工作流会选择状态路由。

queued等待工作线程
processing引擎正在运行
completed检查输出和警告
failed读取 failureCode 和 failureReason

轮询与文件

读取结果，而不仅是状态。

已完成的响应包含解析后的指标、警告、事件、预览产物和输出文件。签名 URL 有效期短；URL 过期后请重新请求作业。

获取处理作业 · Shell
curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"

指标

针迹数量、尺寸和引擎特定测量值。

警告

您的界面应显示的兼容性或生产注意事项。

私有文件

签名 URL 有效期 10 分钟，且仍会强制执行所有权和解锁状态。

解锁可能消耗权益

先检查 job.unlock 或 GET /usage. 调用解锁端点可能会消耗订阅额度或现有处理点数。内部账户可免费解锁。此操作不会打开结账或购买点数。

端点参考

完整的 v1 接口。

OpenAPI JSON
GET/formats

可读源格式、可写输出格式及兼容性警告。

formats:read
GET/usage

预览额度、点数、工作流费用及重置日期。

usage:read
GET/jobs

账户最近 50 个私有处理作业。

jobs:read
POST/jobs

创建转换或图像打版预览作业。

jobs:write
GET/jobs/conversion/{id}

检查一个所属转换作业及其输出。

jobs:read
GET/jobs/digitising/{id}

检查一个所属打版作业及其输出。

jobs:read
POST/jobs/{workflow}/{id}/retry

在私有源仍存在时重新排队失败的作业。

jobs:write
POST/jobs/{workflow}/{id}/unlock

使用额度或现有点数解锁已完成的作业。

jobs:write

列表响应

GET /formats 返回 data[] 和 artworkInputs[]. GET /jobs 返回 data[] 加 freeUsage 且最多返回最近 50 个作业。

重试响应

重试仅接受 failed 源文件 尚未过期的作业。重试成功将返回 HTTP 202，并将作业重置为 queued.

错误与速率限制

清晰地失败。有意地重试。

401

密钥缺失、无效、已过期或已撤销

403

缺少权限或资源属于其他用户

404

未找到作业或私有文件

409

作业状态不允许此操作

410

源文件上传已过期

422

字段、文件、格式无效或配额不足

429

超出速率限制

422 验证错误
{
  "message": "The format field is invalid.",
  "errors": {
    "format": [
      "Choose an output format different from every detected source format."
    ]
  }
}

每分钟 60 次请求

通用限制按 API 密钥生效，另有独立的网络上限。上传、处理和解锁路由具有更严格的滥用控制。

处理 HTTP 429

遵守 Retry-After 并使用带抖动的指数退避。不要持续轮询已完成或失败的作业。

为 AI 代理构建？

请使用 OAuth + MCP，而非 API 密钥。

代理指南包含连接设置、发现 URL、OAuth PKCE、所有工具架构和可直接复制的 JSON-RPC 示例。

打开 MCP 文档

需要帮助？ 联系开发者支持

下载 OpenAPI 描述