# Developer API Конвертера файлов вышивки

Каноническая страница: https://embroideryfileconverter.com/ru/developers

Создавайте рабочие процессы вышивки с помощью приватного REST API для оцифровки изображений, конвертации файлов, статуса задач, проверенных выходов и подписанных загрузок.

## Выберите подходящую интеграцию

- Используйте REST API на этой странице для бэкенда, SaaS-продукта, электронной коммерции, автоматизации или серверного приложения.
- Используйте [документацию AI-агента и MCP](https://embroideryfileconverter.com/ru/ai-agents), когда ассистент должен действовать от имени пользователя через OAuth.

Не размещайте ключ разработчика API в JavaScript браузера, мобильном приложении или распространяемом бинарном файле рабочего стола.

## Базовый URL и аутентификация

- Базовый URL: `https://embroideryfileconverter.com/api/developer/v1`
- Аутентификация: `Authorization: Bearer efc_live_...`
- Тип содержимого задания: `multipart/form-data`
- Общий лимит по умолчанию: 60 запросов в минуту на ключ, с отдельным сетевым ограничением
- Срок действия подписанной ссылки на файл: 1440 мин.
- [Описание 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`.

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

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

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

```text
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
```

[Описание OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)

## Поля создания задания

### Конвертация

Используйте `workflow=conversion` для существующего файла машинной вышивки.

- Обязательно: `workflow`, `format` и `file` или `files[]`
- Максимальный размер исходного файла: 50 МБ
- Выходной `format` должен быть доступен для записи и отличаться от обнаруженного исходного формата.

### Оцифровка

Используйте `workflow=digitising` для изображений JPG, JPEG, PNG, SVG или WebP.

- Обязательно: `workflow`, `format`, `file` или `files[]`, `width_mm` и `colour_count`
- `width_mm`: число от 10 до 300
- `colour_count`: целое число от 1 до 24
- Максимальный размер исходного файла: 20 МБ

`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` и возвращает `data[]` плюс `freeUsage` для до 50 последних принадлежащих заданий.
- `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`. Задание должно быть завершено.
- Подписанные URL `GET /uploads/{id}/download` и `GET /uploads/{id}/preview` требуют `jobs:read`; используйте полный URL из ответа о задании, а не формируйте его самостоятельно.

## Поведение разблокировки

Проверьте `job.unlock` или `GET /usage` перед разблокировкой. Запрос на разблокировку может списать доступное право подписки или кредиты обработки на счёте. Внутренние аккаунты могут разблокировать без оплаты. Не открывает оформление заказа или покупку кредитов. Недостаточная квота или кредиты возвращают ошибку валидации.

## Ошибки и поведение при повторных попытках

- `401`: отсутствует, неверный, просроченный или отозванный ключ разработчика
- `403`: отсутствует возможность ключа или ресурс принадлежит другому аккаунту
- `404`: задание или приватный файл не найден
- `409`: текущее состояние задания не позволяет повторить или разблокировать
- `410`: загрузка приватного источника просрочена
- `422`: недопустимые поля, исходный файл, выходной формат или недостаточная квота
- `429`: превышен лимит скорости; учитывайте `Retry-After` и используйте экспоненциальный откат с jitter

Создание заданий также защищено лимитами загрузки и обработки, а маршруты разблокировки имеют более строгий лимит платёжных действий. Избегайте агрессивного опроса и останавливайтесь после терминального статуса.

## Модель безопасности

Файлы клиентов остаются конфиденциальными. Каждый запрос задания ограничен владельцем API-ключа, подписанные URL истекают, загружаемые машинные файлы остаются заблокированными до прохождения проверок прав, а ключевые возможности проверяются перед выполнением запрошенной операции.

## Связанные страницы

- [ИИ-агенты и MCP](https://embroideryfileconverter.com/ru/ai-agents)
- [Поддерживаемые форматы вышивки](https://embroideryfileconverter.com/ru/formats)
- [Конфиденциальность и хранение файлов](https://embroideryfileconverter.com/ru/privacy)