Справочник API · v1JSON + multipart

Встройте вышивку в ваш продукт.

Практичный REST API для приватной оцифровки изображений и настоящей конвертации машинных файлов. На этой странице — полный quickstart, справочник эндпоинтов и руководство по ошибкам.

Получить API-ключ OpenAPI 3.1

Базовый URL

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

Аутентификация

Bearer-ключ

Лимит

60/min

Задания

Асинхронно

Ключи ограничены по областям, имеют срок действия, могут быть отозваны немедленно и показываются только один раз. Храните их на сервере — никогда не размещайте в коде браузера или мобильного клиента.

Обзор Быстрый старт Аутентификация Создать задачу Жизненный цикл задачи Студия квилтинга Справочник конечных точек Ошибки и лимиты

Быстрый старт

Ваша первая задача за три шага.

Создайте ключ

Выберите только те возможности, которые нужны вашему сервису, и храните секрет в серверном менеджере секретов.

Отправьте исходник

POST multipart-данные формы с workflow, выходным форматом и одним приватным исходным файлом.

Опрашивайте задачу

Используйте возвращённый workflow и job ID, пока статус не станет completed или failed.

Создать задачу конвертации · 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-клиентам следует использовать MCP с OAuth и PKCE вместо получения ключа разработчика API.

POST /jobs

Выберите workflow, соответствующий источнику.

workflow=conversion

Существующий машинный файл

Загрузите PES, DST, JEF или другой читаемый формат вышивки и выберите другой записываемый выходной формат.

Требуется: workflow, format, file
Максимальный файл: 50 MB

workflow=digitising

Изображение JPG, PNG, SVG или WebP

Сгенерируйте превью стежков из изображения. Требуются готовая ширина и максимальное количество цветов нитей.

Дополнительные поля: width_mm, colour_count
Допустимые диапазоны: 10–300 мм · 1–24 цвета
Максимальный файл: 20 MB

Одиночные файлы и пакеты

Используйте file для одного источника или files[] для до 10 источников. Ограниченная бесплатная обработка может принимать один файл за запрос. Каждый пакет использует один общий workflow и выходной формат.

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; workflow выбирает маршрут статуса.

queuedОжидание worker

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"

Метрики

Количество стежков, размеры и специфические измерения движка.

Предупреждения

Заметки по совместимости или производству, которые должен показывать ваш UI.

Приватные файлы

Подписанные URL действуют 1440 минут и всё равно проверяют владение и состояние разблокировки.

Разблокировка может списать право

Сначала проверьте job.unlock или GET /usage. Вызов конечной точки разблокировки может потребовать разрешения подписки или имеющихся кредитов обработки. Внутренние аккаунты могут разблокировать без оплаты. Это не открывает оформление заказа или покупку кредитов.

Студия квилтинга

Нарисуйте линейный дизайн, выберите шаблон или загрузите узор. Изображения служат локальными ориентирами, а не автоматической оцифровкой. Дополнительная обрезка краёв поддерживает только линейные дизайны.

Каждый новый подготовленный результат использует одну квоту оцифровки или 5 кредитов для любого процесса. Все пяльцы и ряды включены. Изменения размещения бесплатны. Подготовка другого результата требует новой разблокировки; повторное скачивание разблокированного результата бесплатно.

Quilting · REST API

GET   /quilting/capabilities
GET   /quilting/projects
POST  /quilting/projects
GET   /quilting/projects/{project}
PATCH /quilting/projects/{project}
GET   /quilting/projects/{project}/results
POST  /quilting/projects/{project}/results
GET   /quilting/results/{result}
GET   /quilting/results/{result}/preview
POST  /quilting/results/{result}/unlock
GET   /quilting/results/{result}/download
POST  /quilting/results/{result}/retry

Authorization: Bearer $EFC_API_KEY
GET → jobs:read
POST / PATCH → jobs:write

queued → processing → ready / failed

POST /quilting/projects · application/json

{
  "template": "wave",
  "settings": {
    "mode": "embroidery",
    "format": "pes",
    "quilt_width_mm": 500,
    "quilt_height_mm": 500,
    "motif_width_mm": 80,
    "motif_height_mm": 80
  }
}

Описание OpenAPI 3.1

Справочник конечных точек

Полная поверхность 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 последними заданиями.

Ответы при повторных попытках

Retry принимает только 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 и используйте экспоненциальный backoff с джиттером. Не опрашивайте непрерывно завершённые или ошибочные задания.

Создаёте для ИИ-агента?

Используйте OAuth + MCP, а не API-ключ.

Руководство агента включает настройку подключения, URL обнаружения, OAuth PKCE, все схемы инструментов и готовые примеры JSON-RPC.

Открыть документацию MCP

Нужна помощь? Связаться с поддержкой разработчиков

Скачать описание OpenAPI