Документация API
Интегрируйте Vectorgram в своё приложение. Один эндпоинт — отправить, один — опрашивать, один — скачать, задачи асинхронны по замыслу. Базовый URL https://api.vectorgram.ai, аутентификация — Authorization: Bearer <api_key>. Ключи выглядят так: vectorgram_sk_live_… — префикс прописан полностью намеренно, чтобы ключ, найденный в старом .env, можно было опознать, не испытывая его.
Новый аккаунт получает 25 бесплатных конвертаций через API в течение 30 дней — полное качество, без водяного знака. Дальше API требует тариф, который его включает (Pro и выше), и вызовы расходуют месячную квоту этого тарифа. Перерасхода нет: вызовы сверх квоты отвечают 402 с датой сброса. GET /v1/account показывает обе квоты и остаток по каждой.
Быстрый старт
1 — Получите API-ключ
Загрузка…
2 — Отправьте изображение
curl -X POST https://api.vectorgram.ai/v1/vectorize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 8f1b0c2e-0a1d-4f77-9c3a-2b6e5d4c1a90" \
-F "file=@image.png" \
-F "image_type=clipart" \
-F "detail=high" \
-F "gradients=smooth" \
-F "smoothing=strong" \
-F "retention=24h"В ответ приходит 202 Accepted с задачей в очереди — конвертация ещё не выполнена. Один и тот же запрос дважды с одним и тем же Idempotency-Key вернёт первую задачу, а не создаст вторую; замена файла или настроек под уже использованным ключом — это 409.
3 — Опрашивайте или примите вебхук
GET /v1/jobs/job_abc123
{
"id": "job_abc123",
"status": "queued",
"progress": 0,
"queue_position": 3,
"mode": "logo",
"retention": "24h",
"megapixels": 2.1,
"created_at": "2026-08-03T10:30:00Z"
}status проходит состояния queued → processing → completed | failed | canceled | expired. Пока задача в очереди, вы получаете настоящий queue_position, а не выдуманный обратный отсчёт; progress во время обработки интерполируется из оценки размера и не поднимается выше 95%, пока файла ещё нет. Крупные изображения могут обрабатываться минуты — опрашивайте с разумным интервалом или, лучше, зарегистрируйте вебхук.
4 — Скачайте
{
"id": "job_abc123",
"status": "completed",
"progress": 100,
"download_url": "https://api.vectorgram.ai/v1/jobs/job_abc123/download",
"completed_at": "2026-08-03T10:30:04Z",
"expires_at": "2026-08-04T10:30:04Z"
}download_url появляется, только когда результат существует, требует тот же bearer-токен и отдаёт файл вложением. С retention=none файл удаляется сразу при отдаче — скачайте его один раз.
Параметры конвертации
Все поля — multipart form data на POST /v1/vectorize. Четыре поля с пометкой вручную — это настройки трассировки: доступны на Pro, Studio, Agency и Enterprise. На Free и Lite их принимают и заменяют значениями по умолчанию, а не отклоняют, так что клиент, который всегда их отправляет, всё равно сконвертирует — просто получит автоматический результат.
Обязательное. Изображение для конвертации. Определяется по его байтам, а не по имени файла.
Какое это изображение. По умолчанию auto — тогда движок классифицирует его сам.
Необязательное, и svg — единственное значение. Движок пишет именно SVG, и ничто не конвертирует его во что-то другое: EPS, PNG, PDF, DXF и AI отклоняются с 400 unsupported_output_format, а не ставятся в очередь на провал.
Срок хранения результата. По умолчанию 24h; none удаляет его после первого скачивания. Значение ограничивается максимумом вашего тарифа, а не отклоняется — Free не удержит результат 10 дней, как его ни проси.
Ваш собственный ключ группировки: возвращается вместе с задачей и годится как фильтр. Отправляйте один запрос на изображение. Пакетная конвертация доступна с Pro (30 файлов, 50 на Studio, 100 на Agency); ниже этого группа вмещает один файл, а второй отвечает 400 batch_limit_exceeded.
Название папки на дашборде, в которой будут лежать файлы пакета. Необязательное и требует batch_id (иначе 400 invalid_folder_name); ограничения как у batch_id — 128 символов, никаких управляющих символов. Папку называет первый принятый файл; последующие файлы пакета её не переименовывают. Если поле пропущено, папка получает дату своего создания.
Сколько изображения переживает слияние областей. По умолчанию high — самая свободная ступень движка начиная с 1.3.0. Значение ползунка 1–100 принимается и приводится к одной из ступеней.
Обработка градиентов. По умолчанию smooth; stepped и auto сохраняют плоские заливки движка.
Скругление углов. По умолчанию strong — настоящие углы остаются острыми, а возвращается лишь то, что движок векторизации скруглил случайно. Значение ползунка 0–100 принимается и приводится к одной из ступеней.
Что рисует движок. По умолчанию fill — каждая форма становится заполненным контуром. centerline рисует один открытый штрих вдоль середины каждой линии (fill="none", с цветом и толщиной обводки) — именно этот путь повторяют перьевые плоттеры, лазерные гравёры, фрезеры с ЧПУ и режущие плоттеры: один проход на линию вместо двух контуров вокруг неё. Участки, слишком толстые, чтобы быть линией, остаются залитыми фигурами. detail, gradients и smoothing не применяются и игнорируются. Неизвестное значение отвечает 400.
Закрытие швов, есть на всех тарифах. По умолчанию true — каждая заливка заходит на 0,75 px под соседнюю, поэтому тонкая светлая линия между двумя цветами не проступает. false даёт точное разбиение: фигуры сходятся край в край, без перекрытия (для правки геометрии). В обоих случаях ни одна фигура не сдвигается. Игнорируется с centerline.
Эндпоинты
Сгенерированный справочник — каждое поле, каждая форма ответа — это Swagger UI, который сервис отдаёт по адресу /docs/swagger, а документ OpenAPI — по адресу /v3/api-docs.
Вебхуки
Поскольку задачи выполняются асинхронно — на крупные файлы уходят минуты, — подпишитесь на вебхуки вместо опроса. Зарегистрируйте эндпоинт через POST /v1/webhooks; секрет подписи возвращается один раз, при создании, и больше никогда.
POST https://your-app.example/hooks/vectorgram
X-Vectorgram-Event: processing.completed
X-Vectorgram-Signature: sha256=<hmac of the raw body, hex>
{
"id": "evt_9f2c…",
"event": "processing.completed",
"created_at": "2026-08-03T10:30:04Z",
"data": { "job_id": "job_abc123", "status": "completed" }
}Проверяйте подпись: вычислите HMAC-SHA256 сырого тела запроса с секретом своего эндпоинта и сравните за постоянное время — любое несовпадение считайте неаутентифицированным запросом. Доставка происходит минимум один раз: при ответе не 2xx попытка повторяется трижды с экспоненциальной задержкой, поэтому сделайте обработчик идемпотентным по id. Эндпоинты должны указывать на публичный адрес; это перепроверяется в момент доставки, а не только при регистрации.
Ошибки
Сбои — это JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Смотрите на code, а не на сообщение — сообщения переписывают.