API для продавцов маркетплейсов: фото, PDF, OCR, QR, этикетки

Начало работы

Получите ключ: укажите email ниже, ключ придёт письмом.
Передавайте его в каждом запросе в заголовке Authorization: Bearer sm_….
Файлы отправляйте как multipart/form-data, параметры — в строке запроса. Методы ссылок, этикеток и расчётов принимают JSON.

export BASE=https://sellermagic.ru/api/v1
export KEY=sm_ваш_ключ

curl -H "Authorization: Bearer $KEY" -F file=@photo.jpg -o result.png "$BASE/remove-bg"

То же на Python:

import requests

r = requests.post("https://sellermagic.ru/api/v1/remove-bg",
                  headers={"Authorization": "Bearer sm_ваш_ключ"},
                  params={"bg": "ffffff", "format": "jpg"},
                  files={"file": open("photo.jpg", "rb")}, timeout=120)
r.raise_for_status()
open("result.jpg", "wb").write(r.content)

Ключ и авторизация

Ключ выглядит как sm_ и 32 символа. Передавайте его в заголовке Authorization: Bearer <ключ> или X-Api-Key: <ключ>.

Храните ключ на сервере и не вставляйте его в код страниц и мобильных приложений: из браузера его легко достать.
Если ключ попал к посторонним, отзовите его запросом DELETE /keys/current и получите новый.
На один email можно выпустить до трёх ключей, например для разных систем.

Лимиты

У ключа суточный лимит 300 единиц и не больше 30 запросов в минуту. Сутки считаются по UTC. Каждый метод стоит определённое число единиц, оно указано в описании метода. Ошибочные запросы не списываются.

В каждом ответе с ключом есть заголовки:

`X-RateLimit-Limit`	Суточный лимит ключа в единицах
`X-RateLimit-Remaining`	Сколько единиц осталось на сегодня
`X-RateLimit-Reset`	Когда лимит обновится, Unix-время
`X-Units-Cost`	Сколько стоит этот запрос
`X-Request-Id`	Идентификатор запроса: укажите его, если пишете нам о проблеме

Текущий расход — в методе GET /usage. Нужен больший лимит — напишите нам.

Ошибки

При ошибке API возвращает HTTP-код 4xx или 5xx и JSON: в error — понятное человеку описание, в code — код для программы.

{"error": "Суточный лимит ключа исчерпан. Он обновится в 00:00 UTC.", "code": "quota_exceeded"}

HTTP	code	Что делать
400	`invalid_request`	Исправить параметры или файл: подробности в `error`
401	`invalid_api_key`, `api_key_required`	Проверить ключ и заголовок Authorization
403	`forbidden`	Нет доступа к этой ссылке
404	`not_found`	Объект не найден
413	`payload_too_large`	Уменьшить файл: до 25 МБ
429	`rate_limited`, `quota_exceeded`	Повторить после `Retry-After` секунд
502, 503, 504	`processing_failed`, `busy`, `timeout`	Повторить запрос через несколько секунд

POST/remove-bg 5 единиц

Удалить фон

Убирает фон с фото товара. Результат в исходном разрешении: прозрачный фон или заливка цветом.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Изображение: JPG, PNG, WebP, HEIC и др., до 25 МБ, до 60 Мп.
`bg`	query	string	Фон: transparent или цвет в HEX без #, например ffffff. По умолчанию: `transparent`
`format`	query	string	Формат результата. Для прозрачного фона — png или webp. `png` · `jpg` · `webp` По умолчанию: `png`

Ответ: Изображение в выбранном формате.

curl -H "Authorization: Bearer $KEY" -F file=@photo.jpg -o result.jpg \
  "$BASE/remove-bg?bg=ffffff&format=jpg"

POST/resize 1 единица

Фото под размер маркетплейса

Вписывает фото в заданный размер: с полями (contain) или с обрезкой по центру (cover). Например 900×1200 для Wildberries.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Изображение до 25 МБ.
`width`	query	integer	Ширина, px (16–8000). По умолчанию: `900`
`height`	query	integer	Высота, px (16–8000). По умолчанию: `1200`
`mode`	query	string	contain — товар целиком с полями, cover — заполнить кадр с обрезкой. `contain` · `cover` По умолчанию: `contain`
`bg`	query	string	Цвет полей в HEX без # или transparent. По умолчанию: `ffffff`
`margin`	query	number	Отступ от края в режиме contain, доля стороны (0–0.3). По умолчанию: `0.04`
`format`	query	string	Формат результата. `jpg` · `png` · `webp` · `avif` · `heic` · `jxl` · `gif` · `bmp` · `tiff` · `ico` · `pdf` По умолчанию: `jpg`
`quality`	query	integer	Качество для jpg, webp, avif, heic, jxl (30–100). По умолчанию: `92`

Ответ: Изображение заданного размера.

curl -H "Authorization: Bearer $KEY" -F file=@photo.jpg -o card.jpg \
  "$BASE/resize?width=900&height=1200&mode=contain"

POST/compress 1 единица

Сжать фото

Уменьшает вес изображения. Если сжатый файл получился бы больше исходного того же формата, возвращается исходный.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Изображение до 25 МБ.
`format`	query	string	keep — формат исходника. `keep` · `jpg` · `webp` · `avif` · `png` По умолчанию: `keep`
`quality`	query	integer	Качество (30–100). По умолчанию: `80`
`max`	query	integer	Максимальная длинная сторона, px; 0 — не менять. По умолчанию: `2000`

Ответ: Сжатое изображение.

curl -H "Authorization: Bearer $KEY" -F file=@photo.jpg -o small.webp \
  "$BASE/compress?format=webp&quality=80&max=2000"

POST/convert 1 единица

Конвертировать формат

Переводит изображение в другой формат. На входе JPG, PNG, WebP, HEIC, AVIF, JPEG XL, GIF, BMP, TIFF, ICO, PSD и др. Анимация не сохраняется: берётся первый кадр.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Изображение до 25 МБ.
`format` *	query	string	Формат результата. `jpg` · `png` · `webp` · `avif` · `heic` · `jxl` · `gif` · `bmp` · `tiff` · `ico` · `pdf` По умолчанию: `jpg`
`quality`	query	integer	Качество для jpg, webp, avif, heic, jxl (30–100). По умолчанию: `90`
`max`	query	integer	Максимальная длинная сторона, px; 0 — не менять. По умолчанию: `0`
`bg`	query	string	Чем заменить прозрачность в jpg, bmp, pdf (HEX без #). По умолчанию: `ffffff`

Ответ: Файл в выбранном формате (для pdf — application/pdf).

curl -H "Authorization: Bearer $KEY" -F file=@IMG_0001.HEIC -o photo.jpg \
  "$BASE/convert?format=jpg&quality=90"

POST/watermark 1 единица

Водяной знак

Накладывает текст или логотип: в угол, по центру или мозаикой по всему фото.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Фото до 25 МБ.
`logo`	form-data	file	Логотип (лучше PNG с прозрачностью). Если не передан, используется text.
`text`	query	string	Текст знака, до 80 символов.
`position`	query	string	br — справа внизу, bl, tr, tl, c — центр, tile — мозаика. `br` · `bl` · `tr` · `tl` · `c` · `tile` По умолчанию: `br`
`size`	query	integer	Ширина знака, % ширины фото (5–80). По умолчанию: `30`
`opacity`	query	integer	Непрозрачность, % (5–100). По умолчанию: `50`
`color`	query	string	Цвет текста, HEX без #. По умолчанию: `ffffff`
`shadow`	query	boolean	Тень под знаком. По умолчанию: `true`
`format`	query	string	keep — формат исходника. `keep` · `jpg` · `png` · `webp` · `avif` · `heic` · `jxl` · `gif` · `bmp` · `tiff` · `ico` · `pdf` По умолчанию: `keep`

Ответ: Фото с водяным знаком.

curl -H "Authorization: Bearer $KEY" -F file=@photo.jpg -o marked.jpg \
  "$BASE/watermark?text=%C2%A9%20My%20Shop&position=tile&opacity=35"

POST/ocr 3 единицы

Распознать текст

Распознаёт печатный текст на фото, скане или в PDF до 30 страниц. Повёрнутые фото выравниваются автоматически.

Параметр	Где	Тип	Описание
`file` *	form-data	file	Изображение или PDF до 25 МБ.
`lang`	query	string	Язык текста. `rus+eng` · `rus` · `eng` По умолчанию: `rus+eng`
`out`	query	string	text — JSON с текстом, pdf — PDF с текстовым слоем. `text` · `pdf` По умолчанию: `text`

Ответ: Для out=text — JSON, для out=pdf — application/pdf.

curl -H "Authorization: Bearer $KEY" -F file=@invoice.jpg "$BASE/ocr?lang=rus%2Beng&out=text"

{"text": "ТОВАРНАЯ НАКЛАДНАЯ № 1457 от 19.10.2026\n...", "chars": 214}

POST/pdf/compress 1 единица

Сжать PDF

Уменьшает размер PDF. Если сжатый файл не меньше исходного, возвращается исходный.

Параметр	Где	Тип	Описание
`file` *	form-data	file	PDF до 25 МБ.
`level`	query	string	ebook — среднее, strong — сильное, print — слабое. `ebook` · `strong` · `print` По умолчанию: `ebook`

Ответ: Сжатый PDF.

curl -H "Authorization: Bearer $KEY" -F file=@catalog.pdf -o small.pdf "$BASE/pdf/compress?level=ebook"

POST/pdf/merge 1 единица

Объединить PDF

Соединяет 2–50 PDF и изображений в один PDF в порядке передачи. Изображения становятся страницами A4.

Параметр	Где	Тип	Описание
`files` *	form-data	file[]	Файлы PDF и изображения, в сумме до 25 МБ. Поле повторяется.

Ответ: Объединённый PDF.

curl -H "Authorization: Bearer $KEY" -F files=@a.pdf -F files=@b.pdf -F files=@scan.jpg -o all.pdf "$BASE/pdf/merge"

POST/pdf/split 1 единица

Разделить PDF

Делит PDF на страницы или диапазоны (ZIP-архив) либо извлекает страницы в один PDF.

Параметр	Где	Тип	Описание
`file` *	form-data	file	PDF до 25 МБ.
`mode`	query	string	each — каждая страница, ranges — диапазоны в отдельные файлы, extract — выбранные страницы в один PDF. `each` · `ranges` · `extract` По умолчанию: `each`
`ranges`	query	string	Для ranges и extract: например 1-3,5,8-10.

Ответ: ZIP-архив (each, ranges) или PDF (extract).

curl -H "Authorization: Bearer $KEY" -F file=@doc.pdf -o pages.pdf "$BASE/pdf/split?mode=extract&ranges=1-2,5"

POST/pdf/from-images 1 единица

Фото в PDF

Собирает до 100 изображений в один PDF формата A4, по одному на страницу, с автоповоротом.

Параметр	Где	Тип	Описание
`files` *	form-data	file[]	Изображения, в сумме до 25 МБ. Поле повторяется.

Ответ: PDF.

curl -H "Authorization: Bearer $KEY" -F files=@page1.jpg -F files=@page2.jpg -o doc.pdf "$BASE/pdf/from-images"

GET/barcode не списывает единиц

Штрихкод

Рисует штрихкод EAN-13 или Code 128. При type=auto EAN-13 выбирается для 12–13 цифр с верной контрольной цифрой.

Параметр	Где	Тип	Описание
`data` *	query	string	Значение кода. Для EAN-13 можно 12 цифр — контрольная посчитается сама.
`type`	query	string	Тип кода. `auto` · `ean13` · `code128` По умолчанию: `auto`
`fmt`	query	string	Формат картинки. `svg` · `png` По умолчанию: `svg`

Ответ: SVG или PNG.

curl -H "Authorization: Bearer $KEY" -o code.svg "$BASE/barcode?data=4601234567893&fmt=svg"

POST/labels 1 единица

Этикетки PDF

Готовит PDF с этикетками для термопринтера, по одной на страницу: название, артикул, штрихкод. До 2000 этикеток. Вместо JSON можно передать multipart с файлом Excel/CSV (поле file) и полями size, type.

Параметр	Где	Тип	Описание
`size`	JSON	string	Размер этикетки, мм. `58x40` · `58x30` · `40x30` · `75x120` По умолчанию: `58x40`
`type`	JSON	string	Тип штрихкода. `auto` · `ean13` · `code128` По умолчанию: `auto`
`items` *	JSON	array	Этикетки: [{"code": "4601234567893", "name": "…", "sku": "…", "copies": 2}].

Ответ: PDF для печати в масштабе 100%.

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -o labels.pdf \
  -d '{"size":"58x40","items":[{"code":"4601234567893","name":"Футболка белая M","sku":"TS-WH-M","copies":3}]}' \
  "$BASE/labels"

POST/links 1 единица

Создать короткую ссылку или QR

Создаёт короткую ссылку (kind=link) или динамический QR-код (kind=qr). Ссылки, созданные с ключом, привязаны к нему: их видно в списке, а статистику и адрес можно менять этим же ключом.

Параметр	Где	Тип	Описание
`url` *	JSON	string	Куда ведёт ссылка: http или https, до 2048 символов.
`kind`	JSON	string	Тип. `link` · `qr` По умолчанию: `link`

Ответ: Созданная ссылка.

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.wildberries.ru/catalog/123/detail.aspx","kind":"qr"}' "$BASE/links"

{"code": "NmvAHe", "kind": "qr", "url": "https://www.wildberries.ru/catalog/123/detail.aspx",
 "short_url": "https://sellermagic.ru/s/NmvAHe", "token": "…", "manage_url": "https://sellermagic.ru/stat/NmvAHe#t=…"}

GET/links не списывает единиц · нужен ключ

Список ссылок ключа

Ссылки и QR-коды, созданные этим ключом, от новых к старым. Для следующей страницы передайте next_before_id как before_id.

Параметр	Где	Тип	Описание
`limit`	query	integer	Сколько вернуть (1–200). По умолчанию: `50`
`before_id`	query	integer	Курсор постраничного вывода.

Ответ: Список.

curl -H "Authorization: Bearer $KEY" "$BASE/links?limit=50"

{"items": [{"id": 42, "code": "NmvAHe", "kind": "qr", "url": "…", "short_url": "…", "clicks": 128, "disabled": false, "created_at": "2026-10-19T17:45:00Z"}], "next_before_id": ""}

GET/links/{code} не списывает единиц

Статистика ссылки

Переходы за всё время и по дням за 30 дней, устройства, системы, браузеры, источники. Доступ — ключом API, которым ссылка создана, или ключом управления в заголовке X-Token.

Параметр	Где	Тип	Описание
`code` *	путь	string	Код ссылки.
`X-Token`	заголовок	string	Ключ управления ссылкой (token из ответа при создании), если ссылка создана без ключа API.

Ответ: Статистика.

curl -H "Authorization: Bearer $KEY" "$BASE/links/NmvAHe"

{"code": "NmvAHe", "url": "…", "kind": "qr", "clicks": 128, "by_day": [{"key": "2026-10-19", "n": 14}],
 "devices": [{"key": "Телефон", "n": 101}], "os": [...], "browsers": [...], "refs": [...]}

PUT/links/{code} не списывает единиц

Сменить адрес ссылки

Меняет, куда ведёт ссылка или QR-код. Напечатанный QR перепечатывать не нужно.

Параметр	Где	Тип	Описание
`code` *	путь	string	Код ссылки.
`url` *	JSON	string	Новый адрес.

Ответ: Новый адрес.

curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.ozon.ru/product/123"}' "$BASE/links/NmvAHe"

{"url": "https://www.ozon.ru/product/123"}

GET/qr/{code}.{ext} не списывает единиц

Картинка QR-кода

QR-код короткой ссылки в SVG или PNG.

Параметр	Где	Тип	Описание
`code` *	путь	string	Код ссылки.
`ext` *	путь	string	Формат. `svg` · `png`
`size`	query	integer	Размер PNG, px (128–4096). По умолчанию: `1024`
`fg`	query	string	Цвет кода, HEX без #. По умолчанию: `111111`
`bg`	query	string	Цвет фона, HEX без #. По умолчанию: `ffffff`

Ответ: SVG или PNG.

curl -H "Authorization: Bearer $KEY" -o qr.png "$BASE/qr/NmvAHe.png?size=2048"

POST/unit-economics не списывает единиц

Юнит-экономика

Прибыль, маржа, ROI, безубыточная цена и цена для нужной маржи на одну продажу. Логистика учитывает невыкупы.

Параметр	Где	Тип	Описание
`price` *	JSON	number	Цена для покупателя, ₽.
`cost`	JSON	number	Себестоимость, ₽.
`commission_pct`	JSON	number	Комиссия маркетплейса, %.
`logistics`	JSON	number	Логистика до покупателя, ₽.
`buyout_pct`	JSON	number	Процент выкупа, %. По умолчанию: `100`
`return_logistics`	JSON	number	Обратная логистика за невыкуп, ₽.
`storage`	JSON	number	Хранение на единицу, ₽.
`acquiring_pct`	JSON	number	Эквайринг и прочие %, от цены.
`ads_pct`	JSON	number	Реклама (ДРР), % от цены.
`other`	JSON	number	Прочие расходы на единицу, ₽.
`tax`	JSON	string	Налог: УСН 6% от цены, УСН 15% от прибыли, свой % от цены, без налога. `usn6` · `usn15` · `custom` · `none` По умолчанию: `usn6`
`tax_pct`	JSON	number	Ставка для tax=custom, % от цены.
`units_per_month`	JSON	number	Продаж в месяц — для monthly_profit.
`target_margin_pct`	JSON	number	Нужная маржа, % — для target_price.

Ответ: Расчёт.

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"price":1490,"cost":450,"commission_pct":24.5,"logistics":85,"buyout_pct":80,"return_logistics":50,"storage":12,"ads_pct":8,"tax":"usn6","units_per_month":300,"target_margin_pct":25}' \
  "$BASE/unit-economics"

{"profit": 335.6, "margin_pct": 22.52, "roi_pct": 74.58, "payout": 994.2, "monthly_profit": 100680,
 "breakeven_price": 944.31, "target_price": 1591.1, "logistics_per_sale": 118.75,
 "breakdown": {"cost": 450, "commission": 365.05, "logistics": 118.75, "storage": 12, "ads": 119.2, "tax": 89.4, "profit": 335.6}}

GET/usage не списывает единиц · нужен ключ

Расход и лимиты ключа

Лимиты ключа, расход за сегодня и история по дням и методам за 30 дней.

Ответ: Расход.

curl -H "Authorization: Bearer $KEY" "$BASE/usage"

{"key_prefix": "sm_AbCdEf", "plan": {"name": "free", "daily_units": 300, "requests_per_minute": 30},
 "today": {"units_used": 42, "units_remaining": 258, "resets_at": "2026-10-20T00:00:00Z"},
 "costs": {"remove-bg": 5, "ocr": 3, "convert": 1}, "history": [{"day": "2026-10-19", "endpoint": "remove-bg", "requests": 8, "units": 40}]}

DELETE/keys/current не списывает единиц · нужен ключ

Отозвать ключ

Отзывает ключ, которым выполнен запрос. Восстановить его нельзя — получите новый на этой странице.

Ответ: Подтверждение.

curl -X DELETE -H "Authorization: Bearer $KEY" "$BASE/keys/current"

{"ok": "Ключ отозван."}

API

Начало работы

Получить ключ

Ключ и авторизация

Лимиты

Ошибки

Фото

Удалить фон

Фото под размер маркетплейса

Сжать фото

Конвертировать формат

Водяной знак

Документы и PDF

Распознать текст

Сжать PDF

Объединить PDF

Разделить PDF

Фото в PDF

Штрихкоды и этикетки

Штрихкод

Этикетки PDF

Ссылки и QR-коды

Создать короткую ссылку или QR

Список ссылок ключа

Статистика ссылки

Сменить адрес ссылки

Картинка QR-кода

Расчёты

Юнит-экономика

Ключ и расход

Расход и лимиты ключа

Отозвать ключ