APIリファレンス · v1JSON + multipart

刺繍機能を組み込む自社製品に。

非公開の画像デジタイジングと実機ファイル変換に対応した実用的なREST APIです。このページはクイックスタート、エンドポイント一覧、エラーガイドをすべて網羅しています。

APIキーを取得 OpenAPI 3.1

ベースURL

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

認証

Bearerキー

レート制限

60/min

ジョブ

非同期

キーは権限範囲が限定され、有効期限があり、即時失効可能です。1回だけ表示されます。サーバー側で厳重に保管し、ブラウザやモバイルクライアントのコードに埋め込まないでください。

概要クイックスタート認証ジョブの作成ジョブライフサイクルエンドポイント一覧エラーと制限

クイックスタート

3ステップで最初のジョブを作成できます。

キーを作成

サービスに必要な権限だけを選択し、シークレットはサーバー側のシークレットマネージャーに保存してください。

ソースを送信

workflow、出力形式、1つの非公開ソースファイルをmultipartフォームデータでPOSTしてください。

ジョブをポーリング

返された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

サーバーサイドのみ

開発者キーをWebページ、配布用デスクトップバイナリ、モバイルアプリに埋め込まないでください。必ずバックエンド経由でリクエストをプロキシしてください。

ユーザー委任アクセスが必要ですか？

AIクライアントは開発者APIキーではなく、OAuthとPKCEを備えたMCPをご利用ください。

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 で1つのソース、または files[] で最大10件のソースを処理できます。無料処理の制限では1リクエストにつき1ファイルのみ受け付ける場合があります。バッチはすべて同一の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は非公開ジョブが受理されたことを示し、機械ファイルが完成したわけではありません。次の2つを保持してください job.id および job.workflow; workflowがステータス取得用のルートを決定します。

queuedワーカー待機中

processingエンジン実行中

completed出力と警告を確認

failedfailureCodeとfailureReasonを確認

ポーリングとファイル

ステータスだけでなく結果も確認してください。

完了時のレスポンスには、解析済みメトリクス、警告、イベント、プレビュー成果物、出力ファイルが含まれます。署名付きURLの有効期間は短いため、期限切れ時は再度ジョブを取得してください。

処理ジョブを取得 · Shell

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

メトリクス

ステッチ数、寸法、エンジン固有の測定値。

警告

UIに表示すべき互換性や生産に関する注意事項。

非公開ファイル

署名付き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}

所有する 1 件の変換ジョブとその出力を検査。

jobs:read

GET/jobs/digitising/{id}

所有する 1 件のデジタイジングジョブとその出力を検査。

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エージェント向けに構築しますか？

APIキーではなくOAuth + MCPをご利用ください。

エージェントガイドには、接続設定、discovery URL、OAuth PKCE、すべてのツールスキーマ、コピー可能なJSON-RPCサンプルが含まれています。

MCPドキュメントを開く

ヘルプが必要ですか？開発者サポートに問い合わせる

OpenAPI記述をダウンロード

刺繍機能を組み込む 自社製品に。

3ステップで最初のジョブを作成できます。

キーを作成

ソースを送信

ジョブをポーリング

権限範囲が限定されたBearerキー。

ソースに合ったワークフローを選択してください。

既存の機械ファイル

JPG、PNG、SVG、WebPのアートワーク

作成は非同期です

ステータスだけでなく結果も確認してください。

メトリクス

警告

非公開ファイル

v1の全エンドポイント。

一覧レスポンス

再試行レスポンス

明確に失敗させ、意図的に再試行してください。

APIキーではなくOAuth + MCPをご利用ください。

刺繍機能を組み込む自社製品に。