画像ベクター化APIで一括処理：中断後に再開できるキューの作り方
永続化したキューで画像を一括ベクター化します。変換IDを保存し、失敗を記録して、完了済みの画像を再送せず処理を再開できます。
目次
APIで画像を一括ベクター化するには、元ファイルを1件ずつキューに入れ、次に進む前に処理状況を保存します。PerfectVector API v1では、バッチを管理するのは自分のワーカーです。1リクエストにつき画像1枚を受け付け、既定では1アカウントで同時に1件の本番変換を実行できます。PerfectVector APIの制限
画像ごとにキューのレコードを作る
各元画像の変更されないコピーと、別の出力フォルダーを用意します。以下ではワーカー1つ、ローカルのSQLiteデータベース、単一フレームのPNG、JPEG、WebPを入れたフォルダーを使います。キューに加える前にAPIのファイル制限を確認します。出力パスを固有にして、logo.png という同名のファイルが互いに上書きしないようにします。
最初のアップロードを試す前に、次の項目をまとめて保存します。
| 項目 | 保存する内容 |
|---|---|
| 元画像 | 固定のパスまたはオブジェクトのバージョンと、元データのダイジェスト。 |
| リクエストキー | 同じ操作の再送を識別する冪等性キー。最初にPOSTを試した時刻も記録します。 |
| 変換ID | APIの vec_… ID。受け取ったらすぐ保存します。 |
| 出力 | 固有のローカル保存先と、最後に確認したキューの状態。 |
| 失敗の詳細 | 取得できる場合はAPIの問題コード、リクエストID、変換エラー。 |
POSTの送信前にキューレコードをコミットします。APIがアップロードを受け付けた後、IDを受け取る前に接続が切れても、再利用できるキーが手元に残ります。PerfectVectorは同じアカウントとモードで、最初のリクエストから24時間そのキーを認識します。再送時の画像データとオプションは同じにします。PerfectVectorの冪等性
1件ずつ送信し、状態を確認して保存する
/v1/vectorizations にマルチパートPOSTを送り、image フィールドに画像、Idempotency-Key ヘッダーにその行のキーを指定します。短時間で送信を終えるには Prefer: respond-async を使います。成功応答のIDを保存してからポーリングします。202 は処理待ちを示します。201 は成功と失敗のどちらの変換も表すため、JSONの状態を確認します。PerfectVectorの待機と非同期処理
次の表はワーカーが行う処理の順序です。saved などは自分で付けるキューの状態名です。APIは processing や succeeded などを返します。
| ディスクに保存したキューの状態 | ワーカーが次に行うこと |
|---|---|
| 新規でキーを保存済み | 元データをアップロードし、返された変換IDを記録します。 |
| 送信結果が不明でIDがない | 再送可能な期間内に、保存したキーで同じアップロードを繰り返します。期間を過ぎていたら、新規課金の可能性があるため、変換を開始する前に確認対象にします。 |
| 変換IDを保存済み | 既存のIDをポーリングします。状態確認の間隔を約2秒空け、レート制限による待機時間に従います。 |
| 変換成功、ファイルがない | 結果をダウンロードして image/svg+xml を確認し、一時ファイルに書き出して所定のパスへ名前を変更します。その後に保存済みと記録します。 |
| 保存済み | POSTを省略します。ファイルがなくなっていたら、リンクが有効なうちに既存の結果を取得します。 |
| 拒否または失敗 | HTTPの問題、または変換の最終エラーを記録します。入力に問題があれば修正し、別の操作として試します。 |
POSTに 429 や 503 が返ったら、Retry-After に従い、24時間以内に元のキーと同じ画像・オプションで再試行します。too_many_in_flight の場合は、すでに進行中の本番変換が完了するまで待ちます。変換IDがあれば、再送する前にその状態を確認します。timeout や provider_unavailable で最終状態が failed と確定した場合は、再試行に新しいキーが必要です。サービスを利用できない場合は復旧を待ちます。クライアント側のタイムアウトでは元の変換の結果が不明なので、そのIDを使うか、期間内に元のキーで再送します。PerfectVector APIのエラー
再起動したワーカーは、新しい変換を始めずに状態確認や結果のダウンロードを繰り返せます。成功したSVGを1件ずつダウンロードして保存してから、キューの次の項目へ進みます。APIの結果は変換完了から24時間で期限が切れます。PerfectVectorの結果とダウンロード
次の疑似コードをもとに、自分のデータベースとHTTPクライアントに合わせて実装します。後の試験では、各リクエストをログに記録し、2件目の変換IDをコミットした直後にテスト用の一時停止を行う想定です。
for each queue row in a stable order:
if the row is rejected or its saved SVG is still on disk:
continue
if the row has no conversion ID:
verify source bytes match the stored digest
if an earlier POST is uncertain and the replay window expired:
flag the row for review and continue
POST with the stored key and original bytes and options
if the response is a permanent input rejection:
commit the error and continue
if the POST times out or the service requests a retry:
keep the same key, record the retry time and stop this run
commit the returned conversion ID
pause here when testing recovery after a commit
GET status by conversion ID, waiting between pending responses
if conversion failed:
commit its error and continue
download the existing result and check the SVG media type
write to a temporary file and rename it to the output path
commit the saved stateファイル3枚で再起動を試す
小さなPNGロゴ2枚と、壊れたPNG1枚を用意します。拒否の後もキューが進むか確認するため、壊れたファイルを意図的に入れます。テストキーでは正常な2枚がサンプルSVGを返すはずです。壊れたファイルは検証に失敗し、出力フォルダーに保存されません。テストモードでは正常な2枚に同じサンプルSVGが返ります。PerfectVectorのテストモード
- 最初のファイルを
savedにします。正常な2枚目は、変換IDを記録した後、出力を保存する前にワーカーを止めます。 - ワーカーを再起動します。1枚目を省略し、2枚目は既存の変換IDでダウンロードすることを確認します。
- 壊れたファイルが問題コードとともに失敗報告に入り、SVGが出力されていないことを確認します。
- ワーカーをもう一度実行します。保存済みの2枚が残り、成功したアップロードがどちらも再送されないことを確認します。
テストキーを使ってAPIに対して再起動試験を行いました。サンプルSVGを2つ保存し、壊れた入力を1件拒否として記録し、2件目の成功ファイルを既存IDで再開できました。最後の実行ではリクエストが送られませんでした。テスト変換はすぐ完了するので、未完了の分岐を試すにはローカルのテストデータを使います。
よくある質問
1回のAPI呼び出しで全ファイルを送れますか？
PerfectVector API v1が1回のPOSTで受け付ける画像は1枚です。バッチは個別のリクエストとして順に送ります。本番ではアカウントの同時実行制限を守り、現在の変換が終わってから次を送ります。PerfectVector APIの制限
SVGの期限が切れていたらどうしますか？
すでにダウンロードしていれば、保存済みのSVGを使います。なければ変換状態を確認し、新しい操作を開始するか決めます。新しい本番変換が成功すると、もう1クレジット使うことがあります。PerfectVectorの結果とダウンロード
参考資料
- PerfectVector — 制限 — ファイル検証とアカウントの既定同時実行数。
- PerfectVector — 冪等性 — キーの適用範囲、再送期間、入力の一致条件。
- PerfectVector — 待機と非同期処理 — 非同期の送信と状態確認。
- PerfectVector — 結果 — ダウンロード、失敗、有効期限。
- PerfectVector — テストモード — テストキーで確認できるアップロードの条件と出力。
- PerfectVector — エラー — Retry-Afterの待機時間、最終エラー、新しいキーが必要な条件。
PerfectVector APIのページでテストキーを取得し、自分のファイル3枚で試します。成功した各行のSVGがディスクにあり、再起動時に完了済みの行が再送されないことを確認してください。
