# 刺绣文件转换器开发者 API

规范页面: https://embroideryfileconverter.com/zh/developers

使用私有 REST API 构建刺绣工作流，支持图像数字化、文件转换、作业状态、验证输出和签名下载。

## 选择正确的集成方式

- 将本页的 REST API 用于后端、SaaS 产品、电商工作流、自动化或服务端应用。
- 当助手需要通过 OAuth 代表用户操作时，请使用 [AI 代理与 MCP 文档](https://embroideryfileconverter.com/zh/ai-agents)。

请勿将开发者 API 密钥放入浏览器 JavaScript、移动应用或分发的桌面二进制文件中。

## 基础 URL 与身份验证

- 基础 URL: `https://embroideryfileconverter.com/api/developer/v1`
- 身份验证: `Authorization: Bearer efc_live_...`
- 作业内容类型: `multipart/form-data`
- 通用默认速率限制：每个密钥每分钟 60 次请求，另有单独的网络上限
- 已签名文件 URL 有效期：10 分钟
- [OpenAPI 3.1 描述](https://embroideryfileconverter.com/developers/openapi.json)
- [创建或撤销 API 密钥](https://embroideryfileconverter.com/developers/keys)

API 密钥仅显示一次，仅以 SHA-256 哈希形式存储，会过期且可立即撤销。可用能力包括 `formats:read`、`usage:read`、`jobs:read` 和 `jobs:write`。

## 快速入门：创建转换作业

```bash
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 "file=@design.pes"
```

由于处理是异步的，API 返回 HTTP 202：

```json
{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}
```

同时持久化 `job.id` 和 `job.workflow`。轮询特定工作流的作业端点，直到状态变为 `completed` 或 `failed`。

## 作业创建字段

### 格式转换

对现有刺绣机文件使用 `workflow=conversion`。

- 必填：`workflow`、`format`，以及 `file` 或 `files[]`
- 最大来源大小：每个文件 50 MB
- 输出 `format` 必须可写且不同于检测到的来源格式。

### 打版

对 JPG、JPEG、PNG、SVG 或 WebP 图像使用 `workflow=digitising`。

- 必填：`workflow`、`format`，以及 `file` 或 `files[]`、`width_mm` 和 `colour_count`
- `width_mm`：10 到 300 之间的数字
- `colour_count`: 整数，范围 1 至 24
- 最大来源大小：每个文件 20 MB

`files[]` 最多接受 10 个来源文件同时处理。免费额度受限的账号每次请求可能仅限一个来源文件。批次内所有文件使用相同的工作流程和输出格式。

## 轮询任务

```bash
curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"
```

可能的状态有 `queued`、`processing`、`completed` 和 `failed`。详细任务响应包含指标、警告、失败信息、事件、预览文件、输出、解锁状态以及临时签名文件 URL。签名 URL 过期后请重新请求任务。

## 完整接口参考

- `GET /formats` 需要 `formats:read` 权限，返回 `data[]` 和 `artworkInputs[]`。
- `GET /usage` 需要 `usage:read` 权限，返回 `freeUsage`，包含额度、点数、工作流程费用及重置日期。
- `GET /jobs` 需要 `jobs:read` 权限，返回最多 50 条近期自有任务的 `data[]` 和 `freeUsage`。
- `POST /jobs` 需要 `jobs:write` 权限，创建一条或多条私有异步预览任务。
- `GET /jobs/conversion/{id}` 需要 `jobs:read` 权限，返回一条自有转换任务。
- `GET /jobs/digitising/{id}` 需要 `jobs:read` 权限，返回一条自有数字化任务。
- `POST /jobs/conversion/{id}/retry` 和 `POST /jobs/digitising/{id}/retry` 需要 `jobs:write` 权限。仅限来源文件未过期的失败任务可重试。
- `POST /jobs/conversion/{id}/unlock` 和 `POST /jobs/digitising/{id}/unlock` 需要 `jobs:write` 权限。任务必须已完成。
- 带签名的 `GET /uploads/{id}/download` 和 `GET /uploads/{id}/preview` URL 需要 `jobs:read` 权限；请使用任务响应中返回的完整 URL，不要自行拼接。

## 解锁行为

解锁前请检查 `job.unlock` 或 `GET /usage`。解锁请求可消耗账户中可用的订阅权益或处理点数。内部账户可免费解锁。此操作不会打开结账或购买点数。额度或点数不足将返回验证错误。

## 错误与重试行为

- `401`：开发者密钥缺失、格式错误、已过期或已吊销
- `403`：密钥缺少对应权限或资源属于其他账号
- `404`：任务或私有文件未找到
- `409`：当前任务状态不允许重试或解锁
- `410`：私有来源文件上传已过期
- `422`：字段无效、来源文件或输出格式不支持，或额度不足
- `429`：超出速率限制；请遵守 `Retry-After` 并使用带抖动的指数退避

任务创建同样受上传和处理限制保护，解锁接口有更严格的计费操作限制。请避免高频轮询，任务进入终态后停止轮询。

## 安全模型

客户文件始终私有。每条任务查询仅限 API 密钥所有者访问，签名 URL 会过期，可下载的机器文件在权益校验通过前保持锁定，密钥权限在执行请求操作前进行校验。

## 相关页面

- [AI 代理与 MCP](https://embroideryfileconverter.com/zh/ai-agents)
- [支持的绣花格式](https://embroideryfileconverter.com/zh/formats)
- [隐私与文件保留](https://embroideryfileconverter.com/zh/privacy)