Tài liệu API · v1JSON + multipart

Tích hợp thêu vào sản phẩm của bạn.

REST API thực tế để số hóa hình ảnh riêng tư và chuyển đổi file máy thêu thực tế. Trang này là hướng dẫn khởi đầu nhanh, tham chiếu điểm cuối và hướng dẫn lỗi đầy đủ.

Lấy khóa API OpenAPI 3.1

URL cơ sở

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

Xác thực

Khóa Bearer

Tỷ lệ

60/min

Công việc

Bất đồng bộ

Khóa được giới hạn phạm vi, hết hạn, có thể thu hồi ngay lập tức và chỉ hiển thị một lần. Giữ chúng trên máy chủ của bạn—không bao giờ đưa vào mã trình duyệt hoặc ứng dụng di động.

Tổng quan Khởi đầu nhanh Xác thực Tạo công việc Vòng đời công việc Tham chiếu điểm cuối Lỗi & giới hạn

Khởi đầu nhanh

Công việc đầu tiên của bạn trong ba bước.

Tạo khóa

Chỉ chọn các khả năng mà dịch vụ của bạn cần và lưu bí mật trong trình quản lý bí mật phía máy chủ.

Gửi nguồn

POST dữ liệu biểu mẫu multipart với quy trình làm việc, định dạng đầu ra và một file nguồn riêng tư.

Thăm dò công việc

Sử dụng quy trình làm việc và ID công việc đã trả về cho đến khi trạng thái hoàn tất hoặc thất bại.

Tạo công việc chuyển đổi · 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]"

Xác thực

Khóa Bearer có phạm vi.

Gửi khóa trong tiêu đề Authorization cho mỗi yêu cầu. Một khóa chỉ có thể truy cập các công việc của chủ sở hữu và chỉ các khả năng đã chọn khi tạo.

formats:read

usage:read

jobs:read

jobs:write

Tiêu đề Authorization

Authorization: Bearer efc_live_...
Accept: application/json

Chỉ phía máy chủ

Không nhúng khóa nhà phát triển vào trang web, tệp nhị phân máy tính để bàn phân phối hoặc ứng dụng di động. Proxy yêu cầu qua backend của bạn.

Cần quyền truy cập người dùng được ủy quyền?

Máy khách AI nên sử dụng MCP với OAuth và PKCE thay vì nhận khóa API nhà phát triển.

POST /jobs

Chọn quy trình làm việc phù hợp với nguồn.

workflow=conversion

File máy thêu hiện có

Tải lên PES, DST, JEF hoặc định dạng thêu có thể đọc khác và chọn đầu ra có thể ghi khác.

Cần có: workflow, format, file
Kích thước file tối đa: 50 MB

workflow=digitising

Tác phẩm JPG, PNG, SVG hoặc WebP

Tạo bản xem trước mũi khâu từ tác phẩm. Yêu cầu chiều rộng hoàn thiện và số lượng màu chỉ tối đa.

Trường bổ sung: width_mm, colour_count
Phạm vi hợp lệ: 10–300 mm · 1–24 màu
Kích thước file tối đa: 20 MB

File đơn lẻ và hàng loạt

Sử dụng file cho một nguồn hoặc files[] cho tối đa 10 nguồn. Xử lý miễn phí giới hạn có thể chấp nhận một file mỗi yêu cầu. Mỗi lô sử dụng một quy trình làm việc và định dạng đầu ra chung.

202 Đã chấp nhận

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

Tạo là bất đồng bộ

HTTP 202 nghĩa là công việc riêng tư đã được chấp nhận, không phải file máy thêu đã sẵn sàng. Lưu cả hai job.id và job.workflow; quy trình làm việc chọn tuyến trạng thái.

queuedĐang chờ worker

processingEngine đang chạy

completedKiểm tra đầu ra và cảnh báo

failedĐọc failureCode và failureReason

Thăm dò và file

Đọc kết quả, không chỉ trạng thái.

Phản hồi hoàn tất bao gồm số liệu đã phân tích, cảnh báo, sự kiện, hiện vật xem trước và file đầu ra. URL đã ký tồn tại ngắn; yêu cầu lại công việc khi URL hết hạn.

Lấy công việc xử lý · Shell

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

Số liệu

Số mũi khâu, kích thước và đo lường cụ thể engine.

Cảnh báo

Ghi chú tương thích hoặc sản xuất mà UI của bạn nên hiển thị.

File riêng tư

URL đã ký tồn tại 10 phút và vẫn thực thi quyền sở hữu và trạng thái mở khóa.

Mở khóa có thể tiêu tốn quyền lợi

Kiểm tra trước job.unlock hoặc GET /usage. Gọi điểm cuối mở khóa có thể tiêu hao hạn mức đăng ký hoặc tín dụng xử lý hiện có. Tài khoản nội bộ có thể mở khóa miễn phí. Thao tác này không mở trang thanh toán hoặc mua tín dụng.

Tham chiếu điểm cuối

Bề mặt v1 hoàn chỉnh.

OpenAPI JSON

GET/formats

Nguồn có thể đọc, đầu ra có thể ghi và cảnh báo tương thích.

formats:read

GET/usage

Hạn mức xem trước, tín dụng, chi phí quy trình và ngày đặt lại.

usage:read

GET/jobs

50 công việc xử lý riêng tư gần nhất của tài khoản.

jobs:read

POST/jobs

Tạo công việc xem trước chuyển đổi hoặc số hóa từ ảnh.

jobs:write

GET/jobs/conversion/{id}

Kiểm tra một công việc chuyển đổi của tài khoản và đầu ra của nó.

jobs:read

GET/jobs/digitising/{id}

Kiểm tra một công việc số hóa của tài khoản và đầu ra của nó.

jobs:read

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

Đưa lại hàng đợi công việc thất bại khi nguồn riêng tư vẫn còn tồn tại.

jobs:write

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

Mở khoá công việc đã hoàn tất bằng hạn mức hoặc tín dụng hiện có.

jobs:write

Liệt kê phản hồi

GET /formats trả về data[] và artworkInputs[]. GET /jobs trả về data[] cộng freeUsage và giới hạn ở 50 công việc gần đây nhất.

Phản hồi thử lại

Thử lại chỉ chấp nhận failed công việc có nguồn chưa hết hạn. Thử lại thành công trả về HTTP 202 với công việc được đặt lại thành queued.

Lỗi và giới hạn tỷ lệ

Thất bại rõ ràng. Thử lại có chủ đích.

401

Khóa thiếu, không hợp lệ, hết hạn hoặc bị thu hồi

403

Khả năng thiếu hoặc tài nguyên thuộc về người dùng khác

404

Không tìm thấy công việc hoặc file riêng tư

409

Trạng thái công việc không cho phép hành động này

410

Tải lên nguồn đã hết hạn

422

Trường, file, định dạng không hợp lệ hoặc hạn mức không đủ

429

Vượt quá giới hạn tỷ lệ

Lỗi xác thực 422

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

60 yêu cầu mỗi phút

Giới hạn chung áp dụng cho mỗi khóa API, với trần mạng riêng. Các tuyến tải lên, xử lý và mở khóa có kiểm soát lạm dụng chặt chẽ hơn.

Xử lý HTTP 429

Tôn trọng Retry-After và sử dụng exponential backoff với jitter. Không liên tục thăm dò các công việc đã hoàn tất hoặc thất bại.

Xây dựng cho tác nhân AI?

Sử dụng OAuth + MCP, không phải khóa API.

Hướng dẫn tác nhân bao gồm thiết lập kết nối, URL khám phá, OAuth PKCE, mọi schema công cụ và ví dụ JSON-RPC sẵn sao chép.

Mở tài liệu MCP

Cần trợ giúp? Liên hệ hỗ trợ nhà phát triển

Tải mô tả OpenAPI