> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# 画像ベクター化APIで一括処理：中断後に再開できるキューの作り方

> 永続化したキューで画像を一括ベクター化します。変換IDを保存し、失敗を記録して、完了済みの画像を再送せず処理を再開できます。

Source: https://perfectvector.com/ja/blog/batch-vectorize-images-api

Language: ja
Author: Jay
Published: 2026-11-10T08:00:00+09:00

APIで画像を一括ベクター化するには、元ファイルを1件ずつキューに入れ、次に進む前に処理状況を保存します。PerfectVector API v1では、バッチを管理するのは自分のワーカーです。1リクエストにつき画像1枚を受け付け、既定では1アカウントで同時に1件の本番変換を実行できます。[PerfectVector APIの制限](https://perfectvector.com/docs/api/limits)

## 画像ごとにキューのレコードを作る

各元画像の変更されないコピーと、別の出力フォルダーを用意します。以下ではワーカー1つ、ローカルのSQLiteデータベース、単一フレームのPNG、JPEG、WebPを入れたフォルダーを使います。キューに加える前に[APIのファイル制限](https://perfectvector.com/docs/api/limits)を確認します。出力パスを固有にして、`logo.png` という同名のファイルが互いに上書きしないようにします。

最初のアップロードを試す前に、次の項目をまとめて保存します。

| 項目      | 保存する内容                                 |
| ------- | -------------------------------------- |
| 元画像     | 固定のパスまたはオブジェクトのバージョンと、元データのダイジェスト。     |
| リクエストキー | 同じ操作の再送を識別する冪等性キー。最初にPOSTを試した時刻も記録します。 |
| 変換ID    | APIの `vec_…` ID。受け取ったらすぐ保存します。         |
| 出力      | 固有のローカル保存先と、最後に確認したキューの状態。             |
| 失敗の詳細   | 取得できる場合はAPIの問題コード、リクエストID、変換エラー。       |

POSTの送信前にキューレコードをコミットします。APIがアップロードを受け付けた後、IDを受け取る前に接続が切れても、再利用できるキーが手元に残ります。PerfectVectorは同じアカウントとモードで、最初のリクエストから24時間そのキーを認識します。再送時の画像データとオプションは同じにします。[PerfectVectorの冪等性](https://perfectvector.com/docs/api/idempotency)

**処理の流れ**

![タグ付きのラスター画像の束から変換記録を経てSVGに至ります。再開を示す矢印は保存済みの変換記録を指しています。](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp)

*ダウンロードの前に変換IDを保存します。中断したら、そのIDから処理を再開します。*

## 1件ずつ送信し、状態を確認して保存する

`/v1/vectorizations` にマルチパートPOSTを送り、`image` フィールドに画像、`Idempotency-Key` ヘッダーにその行のキーを指定します。短時間で送信を終えるには `Prefer: respond-async` を使います。成功応答のIDを保存してからポーリングします。`202` は処理待ちを示します。`201` は成功と失敗のどちらの変換も表すため、JSONの状態を確認します。[PerfectVectorの待機と非同期処理](https://perfectvector.com/docs/api/waiting-and-async)

次の表はワーカーが行う処理の順序です。`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のエラー](https://perfectvector.com/docs/api/errors)

再起動したワーカーは、新しい変換を始めずに状態確認や結果のダウンロードを繰り返せます。成功したSVGを1件ずつダウンロードして保存してから、キューの次の項目へ進みます。APIの結果は変換完了から24時間で期限が切れます。[PerfectVectorの結果とダウンロード](https://perfectvector.com/docs/api/results)

次の疑似コードをもとに、自分のデータベースとHTTPクライアントに合わせて実装します。後の試験では、各リクエストをログに記録し、2件目の変換IDをコミットした直後にテスト用の一時停止を行う想定です。

```text
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のテストモード](https://perfectvector.com/docs/api/test-mode)

1. 最初のファイルを `saved` にします。正常な2枚目は、変換IDを記録した後、出力を保存する前にワーカーを止めます。
2. ワーカーを再起動します。1枚目を省略し、2枚目は既存の変換IDでダウンロードすることを確認します。
3. 壊れたファイルが問題コードとともに失敗報告に入り、SVGが出力されていないことを確認します。
4. ワーカーをもう一度実行します。保存済みの2枚が残り、成功したアップロードがどちらも再送されないことを確認します。

テストキーを使ってAPIに対して再起動試験を行いました。サンプルSVGを2つ保存し、壊れた入力を1件拒否として記録し、2件目の成功ファイルを既存IDで再開できました。最後の実行ではリクエストが送られませんでした。テスト変換はすぐ完了するので、未完了の分岐を試すにはローカルのテストデータを使います。

## よくある質問

### 1回のAPI呼び出しで全ファイルを送れますか？

PerfectVector API v1が1回のPOSTで受け付ける画像は1枚です。バッチは個別のリクエストとして順に送ります。本番ではアカウントの同時実行制限を守り、現在の変換が終わってから次を送ります。[PerfectVector APIの制限](https://perfectvector.com/docs/api/limits)

### SVGの期限が切れていたらどうしますか？

すでにダウンロードしていれば、保存済みのSVGを使います。なければ変換状態を確認し、新しい操作を開始するか決めます。新しい本番変換が成功すると、もう1クレジット使うことがあります。[PerfectVectorの結果とダウンロード](https://perfectvector.com/docs/api/results)

## 参考資料

1. [PerfectVector — 制限](https://perfectvector.com/docs/api/limits) — ファイル検証とアカウントの既定同時実行数。
2. [PerfectVector — 冪等性](https://perfectvector.com/docs/api/idempotency) — キーの適用範囲、再送期間、入力の一致条件。
3. [PerfectVector — 待機と非同期処理](https://perfectvector.com/docs/api/waiting-and-async) — 非同期の送信と状態確認。
4. [PerfectVector — 結果](https://perfectvector.com/docs/api/results) — ダウンロード、失敗、有効期限。
5. [PerfectVector — テストモード](https://perfectvector.com/docs/api/test-mode) — テストキーで確認できるアップロードの条件と出力。
6. [PerfectVector — エラー](https://perfectvector.com/docs/api/errors) — Retry-Afterの待機時間、最終エラー、新しいキーが必要な条件。

***

[PerfectVector APIのページでテストキーを取得](https://perfectvector.com/ja/api)し、自分のファイル3枚で試します。成功した各行のSVGがディスクにあり、再起動時に完了済みの行が再送されないことを確認してください。

## Explore

- [Read the HTML article](https://perfectvector.com/ja/blog/batch-vectorize-images-api)
- [PNG2SVGの一括変換：ダウンロードしたZIPを確認](https://perfectvector.com/ja/blog/png2svg-batch-convert.md)
- [Claude CodeとMCPで画像フォルダーを一括SVG化：保存先の設計と検査](https://perfectvector.com/ja/blog/batch-vectorize-images-claude-code-mcp.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)