Медиа

Медиатека сайта — картинки, которые стоят на его страницах. Загрузка через API v2 кладёт файл в каталог загрузок сайта, создаёт все размеры, пишет WebP-копию рядом с каждым JPEG и PNG, сохраняет alt и язык. Повторная загрузка того же файла не создаёт дубль. У каждого файла есть короткий адрес: /media/ и путь файла в медиатеке, например /media/2026/09/ccae29ae_1778004215.png.

Загрузить

По адресу:

curl -s -X POST "$API/site/$SITE/media" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url": "https://onpress.pro/media/2026/05/ccae29ae_1778004215.png", "alt": "Схема сборки страницы", "title": "schema", "lang": "ru"}' \
  | jq '{id, path, webp, width, height, deduped, sizes: (.sizes | keys)}'

{
  "id": 6449,
  "path": "/media/2026/09/ccae29ae_1778004215.png",
  "webp": "/media/2026/09/ccae29ae_1778004215.webp",
  "width": 1400,
  "height": 1207,
  "deduped": false,
  "sizes": ["medium", "medium_large", "onpress_md", "onpress_sm", "thumbnail"]
}

Файлом в base64 (здесь — тот же файл, скачанный заранее: curl -s -o schema.png https://onpress.pro/media/2026/05/ccae29ae_1778004215.png):

curl -s -X POST "$API/site/$SITE/media" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -n --arg data "$(base64 < schema.png)" '{data: $data, filename: "schema.png", alt: "Схема"}')" \
  | jq '{id, path, deduped}'

Поле	Смысл
`url`	откуда скачать: только `http`/`https`, без логина в адресе, не локальные и не внутренние адреса
`data`	файл в base64 или `data:`-URI; вместе с `url` нельзя
`filename`	обязателен с `data`; расширение исправляется по настоящему типу содержимого
`alt`	альтернативный текст
`title`	заголовок вложения; по умолчанию — имя файла
`lang`	язык вложения (если медиа на сайте переводятся); по умолчанию — основной

Форматы: JPEG, PNG, WebP, GIF, SVG — определяются по содержимому, а не по расширению и не по заголовкам источника.
Предел: 15 МБ на файл. Тело запроса ограничено 10 МБ, а base64 раздувает файл на треть, поэтому файлы больше примерно 7 МБ отправляйте через url.
SVG проверяется на безопасность: <script>, обработчики on*=, ссылки javascript:, <!ENTITY, <foreignObject>, встроенные фреймы — отказ 422 unsafe_svg с причиной. У SVG нет размеров и WebP.
Размеры: все зарегистрированные (thumbnail, medium, medium_large, large, onpress_sm, onpress_md, onpress_xl — какие подходят по ширине), у каждого свой path и webp. Картинка шире 1920 px сохраняется уменьшенной с суффиксом -scaled, оригинал лежит рядом.
Одна загрузка — один запрос; пакетной формы нет, учитывайте лимит 120 запросов в минуту.

Повторная загрузка

Загрузка идемпотентна. Каждое вложение помнит, откуда пришло (адрес источника), и что в нём (SHA-256 содержимого). Повтор того же url находит вложение без скачивания; те же байты под другим адресом или в data находятся по хешу, и новый адрес добавляется вложению. Ответ — существующее вложение с "deduped": true и deduped_by (source_url или sha256). Найденное вложение не меняется: alt, title и lang применяются только при создании. Скрипт, который заливает картинки статьи, после сбоя можно просто запустить заново. Одновременные загрузки одного источника сериализуются — получится одно вложение.

{ "id": 6449, "path": "/media/2026/09/ccae29ae_1778004215.png", "deduped": true, "deduped_by": "sha256" }

Вставить в страницу

Берите path. Это короткий адрес файла, от корня сайта:

![Схема сборки страницы](/media/2026/09/ccae29ae_1778004215.png "Как страница собирается по шаблону")

Короткий адрес работает на любом домене сайта и переживает смену домена. По нему сервер сразу отдает файл, без редиректа. url — тот же адрес с доменом. Выгрузка GET /pages/{ref}/markdown печатает короткий адрес. Картинка из медиатеки при сборке страницы выводится как <picture> с размерами и WebP.

Пустой alt можно оставить. На сайте такая картинка получает alt с названием страницы. В markdown и в выгрузке он остается пустым. Заданный alt выводится как есть.

Где еще нужен id вложения: иконка сайта (site_icon в настройках), логотип организации и картинка соцсетей по умолчанию в SEO, превью страницы (image в свойствах страницы или thumbnail в PATCH /pages/{ref}; оно же og:image, выводится блоком onpress/featured-image).

Найти

# список медиатеки
curl -s -H "Authorization: Bearer $OP_TOKEN" \
  "$API/site/$SITE/media?page=1&per_page=50&type=image&orderby=date&order=desc" \
  | jq '{total, pages, mime_groups, items: [.items[] | {id, path, filename, alt, thumb}]}'

# по адресу источника
curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/media?source_url=https://onpress.pro/media/2026/05/ccae29ae_1778004215.png" | jq '{id, path}'

# по хешу содержимого
curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/media?sha256=$(shasum -a 256 schema.png | cut -d' ' -f1)" | jq '{id, path}'

# одно вложение со всеми размерами
curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/media/6449" | jq '{id, path, sizes, source_urls, sha256}'

Параметр списка	По умолчанию	Смысл
`page`	`1`	страница выдачи
`per_page`	`50`	до 100
`search`	—	подстрока имени файла, заголовка, подписи или описания, до 200 символов
`type`	—	группа (`image`, `video`, `audio`, `document`, `other`) или точный тип (`image/png`)
`orderby`	`date`	`date`, `name` (заголовок), `id`
`order`	`desc`	`desc`, `asc`

Строки списка облегчены: без sizes, source_urls и sha256 — за ними GET /media/{id}. thumb — превью размера medium (с пропорциями оригинала), mime_groups — счёт по группам по всей медиатеке. Страница выдачи за концом — 200 с пустым items и нулями в total и pages: берите итоги со страницы внутри диапазона.

GET /media/{id} описывает любое вложение сайта, в том числе загруженное не через API — у таких source_urls пустой, а sha256 равен null. Не нашлось — 404 media_not_found.

Удалить

DELETE /media/{id} удаляет вложение вместе с файлом, всеми размерами и WebP-копиями. Например, удалите картинку 6449:

curl -s -X DELETE "$API/site/$SITE/media/6449" \
  -H "Authorization: Bearer $OP_TOKEN"

{ "success": true, "site_id": "x9HTLHECq", "id": 6449, "deleted": true }

Такого вложения нет — 404 media_not_found. Пачкой файлы удаляет раздел «Медиа» консоли.

Коды ошибок

Код	HTTP	Когда
`source_required`	400	нет ни `url`, ни `data`
`source_ambiguous`	400	и `url`, и `data`
`filename_required`	400	`data` без `filename`
`bad_url`	400	не http(s), логин в адресе, локальный или внутренний адрес
`bad_data`	400	`data` не base64
`bad_field`	400	`alt`, `title` или `lang` не строка
`unknown_language`	400	нет такого языка; список в `languages`
`bad_source_url`, `bad_sha256`, `bad_id`	400	кривой параметр поиска
`bad_page`, `bad_per_page`, `bad_search`, `bad_type`, `bad_orderby`, `bad_order`	400	кривой параметр списка
`media_not_found`	404	ничего не найдено
`file_too_large`	413	больше 15 МБ
`unsupported_type`	415	не JPEG, PNG, WebP, GIF или SVG
`empty_file`	400 или 422	ноль байт
`unsafe_svg`	422	SVG не прошёл проверку
`source_not_found`	422	источник ответил 404
`download_failed`	422	источник не скачался
`sideload_failed`	422	сайт отказал в приёме файла
`media_failed`, `media_unavailable`	502, 503	исполнитель на сайте ответил неожиданно или не ответил