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

# Пакетная векторизация через API с возобновлением

> Поставьте изображения в надёжную очередь. Сохраняйте ID конвертаций, обрабатывайте ошибки и продолжайте работу без повторной отправки готовых файлов.

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

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

Чтобы векторизовать изображения через API пакетно, поставьте каждый исходный файл в очередь и сохраните ход его обработки перед переходом к следующему. В PerfectVector API v1 очередью управляет ваш обработчик. API принимает одно изображение на запрос и по умолчанию допускает одну активную рабочую конвертацию на аккаунт. [Ограничения PerfectVector API](https://perfectvector.com/docs/api/limits)

## Создайте запись для каждого изображения

Сохраните неизменяемую копию каждого исходника и выделите отдельную папку для результатов. Ниже предполагаются один обработчик, локальная база SQLite и папка с однофреймовыми PNG, JPEG или WebP. Сверьтесь с [ограничениями файлов API](https://perfectvector.com/docs/api/limits), прежде чем добавлять файлы. Назначьте каждому результату уникальный путь, чтобы два исходника с именем `logo.png` не перезаписали друг друга.

Сохраните следующие поля вместе до первой попытки загрузки.

| Поле               | Что хранить                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Исходник           | Стабильный путь или версию объекта и хеш исходных байтов.                                                   |
| Ключ запроса       | Ключ идемпотентности, по которому API распознаёт повторы этой операции. Запишите время первой попытки POST. |
| ID конвертации     | Идентификатор API вида `vec_…`. Сохраните его сразу после получения.                                        |
| Результат          | Уникальный локальный путь и последнее подтверждённое состояние записи.                                      |
| Сведения об ошибке | Код проблемы 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.*

## Отправляйте, проверяйте и сохраняйте по одной задаче

Отправьте multipart-запрос POST на `/v1/vectorizations`, поместив изображение в поле `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. Между проверками подождать около двух секунд и соблюдать задержки при ограничении частоты запросов.                                               |
| Конвертация успешна, файла нет             | Скачать результат, проверить `image/svg+xml`, записать во временный файл и переименовать его в целевой. Затем пометить запись как сохранённую.                              |
| Сохранено                                  | Пропустить POST. Если результат пропал, попробовать скачать его по существующей ссылке, пока она действует.                                                                 |
| Запрос отклонён или конвертация не удалась | Записать проблему HTTP или окончательную ошибку конвертации. Исправить исходник перед новой операцией.                                                                      |

Если POST вернул `429` или `503`, соблюдайте `Retry-After` и повторите запрос с тем же изображением, параметрами и ключом в течение 24 часов. При `too_many_in_flight` также дождитесь окончания активной конвертации. Если ID уже есть, проверьте его перед новой отправкой. После подтверждённого окончательного статуса `failed` с ошибкой `timeout` или `provider_unavailable` для новой попытки нужен новый ключ. При недоступности провайдера дождитесь восстановления. При тайм-ауте на стороне клиента состояние конвертации неизвестно. Проверьте ID или повторите запрос с исходным ключом в пределах окна. [Ошибки PerfectVector API](https://perfectvector.com/docs/api/errors)

После перезапуска обработчик может снова проверить статус или скачать результат без новой конвертации. Скачивайте и сохраняйте каждый готовый SVG перед переходом к следующему файлу. Результат API доступен 24 часа после окончания конвертации. [Результаты и скачивание в PerfectVector](https://perfectvector.com/docs/api/results)

Этот псевдокод можно адаптировать к своей базе и HTTP-клиенту. В проверке ниже обработчик записывает все запросы в журнал и позволяет тесту остановить его сразу после сохранения второго 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
```

## Проверьте перезапуск на трёх файлах

Возьмите два небольших логотипа PNG и один повреждённый PNG. Оставьте повреждённый файл в тесте, чтобы проверить, продолжает ли очередь работу после отклонения. С тестовым ключом оба корректных файла должны вернуть тестовые SVG. Повреждённый файл должен не пройти проверку и не появиться в папке результатов. В тестовом режиме оба корректных файла возвращают один и тот же пример SVG. [Тестовый режим PerfectVector](https://perfectvector.com/docs/api/test-mode)

1. Дождитесь, пока первый файл получит статус `saved`. Остановите обработчик после записи ID второго корректного файла и до сохранения результата.
2. Перезапустите обработчик. Убедитесь, что он пропускает первый файл и скачивает второй по уже сохранённому ID.
3. Проверьте, что повреждённый файл есть в отчёте с кодом проблемы и что для него не записан SVG.
4. Запустите обработчик ещё раз. Убедитесь, что оба SVG остались на месте и ни одна успешная загрузка не повторилась.

Мы проверили перезапуск с тестовым ключом API. Обработчик сохранил два тестовых SVG, записал один повреждённый файл как отклонённый и продолжил обработку второго корректного файла по сохранённому ID. Последний запуск не отправил ни одного запроса. Тестовые конвертации заканчиваются сразу, поэтому для проверки ветки ожидания подготовьте тестовый ответ.

## Частые вопросы

### Можно ли отправить все файлы одним вызовом API?

PerfectVector API v1 принимает одно изображение в каждом POST. Отправляйте партию отдельными запросами. В рабочем режиме учитывайте лимит активных конвертаций на аккаунт и дождитесь завершения текущей перед отправкой следующей. [Ограничения PerfectVector API](https://perfectvector.com/docs/api/limits)

### Что делать, если срок скачивания SVG уже истёк?

Используйте сохранённый SVG, если успели скачать его. В противном случае проверьте статус конвертации и решите, запускать ли новую. Успешная рабочая конвертация может списать ещё один кредит. [Результаты и скачивание в 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/ru/api) и проверьте перезапуск на трёх своих файлах. Убедитесь, что для каждой успешной записи на диске есть SVG, а готовые файлы не отправляются снова после перезапуска.

## Explore

- [Read the HTML article](https://perfectvector.com/ru/blog/batch-vectorize-images-api)
- [Пакетная конвертация PNG2SVG: проверьте скачанный ZIP](https://perfectvector.com/ru/blog/png2svg-batch-convert.md)
- [Пакетная конвертация папки в SVG через Claude Code](https://perfectvector.com/ru/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)