# Embroidery File Converter Developer API

正規ページ: https://embroideryfileconverter.com/ja/developers

画像デジタイジング、ファイル変換、ジョブステータス、検証済み出力、署名付きダウンロードのためのプライベートREST APIで刺繍ワークフローを構築します。

## 適切な統合を選択

- バックエンド、SaaS製品、eコマースワークフロー、自動化、またはサーバーサイドアプリケーションにはこのページのREST APIを使用してください。
- アシスタントがOAuthを通じてユーザーの代わりに動作する場合は[AIエージェントとMCPドキュメント](https://embroideryfileconverter.com/ja/ai-agents)を使用してください。

開発者APIキーをブラウザJavaScript、モバイルアプリケーション、または配布されるデスクトップバイナリに配置しないでください。

## ベースURLと認証

- ベースURL: `https://embroideryfileconverter.com/api/developer/v1`
- 認証: `Authorization: Bearer efc_live_...`
- ジョブコンテンツタイプ: `multipart/form-data`
- 一般的なデフォルトレート制限: 1キーあたり1分間に 60 リクエスト、別途ネットワーク上限あり
- 署名付きファイルURLの有効期間: 10 分
- [OpenAPI 3.1記述](https://embroideryfileconverter.com/developers/openapi.json)
- [APIキーを作成または失効](https://embroideryfileconverter.com/developers/keys)

APIキーは1回のみ表示され、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[]`
- 最大ソースサイズ: 1ファイルあたり 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 の整数
- 最大ソースサイズ: 1ファイルあたり 20 MB

`files[]` は1回のバッチで最大10件の元データを扱えます。処理制限のある無料アカウントでは1リクエストあたり1件に制限される場合があります。バッチ内の全ファイルは同一ワークフローと出力形式で処理されます。

## ジョブの状態取得

```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` 権限を必要とし、1件以上の非公開非同期プレビュージョブを作成します。
- `GET /jobs/conversion/{id}` は `jobs:read` 権限を必要とし、所有する変換ジョブ1件を返します。
- `GET /jobs/digitising/{id}` は `jobs:read` 権限を必要とし、所有する刺繍化ジョブ1件を返します。
- `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を使用し、URLを自分で構築しないでください。

## アンロック動作

`job.unlock` または `GET /usage` をアンロック前に確認してください。アンロック要求により、利用可能なサブスクリプション権利またはアカウント上の処理クレジットが消費される場合があります。内部アカウントは無償でアンロックできる場合があります。チェックアウトを開いたりクレジットを購入したりするものではありません。枠またはクレジットが不足している場合は検証エラーになります。

## エラーと再試行動作

- `401`: 開発者キーが存在しない、形式不正、有効期限切れ、または取り消し済み
- `403`: キーに必要な権限がない、またはリソースが別アカウントに属する
- `404`: ジョブまたは非公開ファイルが見つかりません
- `409`: 現在のジョブ状態では再試行またはアンロックが許可されません
- `410`: 非公開元データのアップロード有効期限が切れました
- `422`: フィールド・元ファイル・出力形式が不正、または利用枠不足
- `429`: レート制限を超えました。`Retry-After` を尊重し、指数バックオフにジッターを加えて再試行してください

ジョブ作成はアップロード・処理制限の対象です。アンロック経路にはより厳しい課金アクション制限があります。過剰なポーリングを避け、終了状態に達したら取得を停止してください。

## セキュリティモデル

顧客ファイルは非公開です。すべてのジョブ照会はAPIキー所有者に制限され、署名付きURLは有効期限が切れ、ダウンロード可能なミシンファイルは権利確認が通るまでロックされたままです。要求された操作を実行する前にキーの権限が強制されます。

## 関連ページ

- [AIエージェントとMCP](https://embroideryfileconverter.com/ja/ai-agents)
- [対応刺繍形式](https://embroideryfileconverter.com/ja/formats)
- [プライバシーとファイル保持](https://embroideryfileconverter.com/ja/privacy)