Медиа

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

Загрузить

По адресу:

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

{
  "id": 6449,
  "path": "/wp-content/uploads/sites/233/2026/09/ccae29ae_1778004215.png",
  "webp": "/wp-content/uploads/sites/233/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/wp-content/uploads/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": "/wp-content/uploads/sites/233/2026/09/ccae29ae_1778004215.png", "deduped": true, "deduped_by": "sha256" }

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

Берите path, а не url:

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

path — от корня сайта, работает на любом его домене и переживает смену домена. url — абсолютный адрес того домена, на котором работал загрузчик. Картинка из медиатеки при сборке страницы выводится как <picture> с размерами и WebP.

Где ещё нужен id вложения: иконка сайта (site_icon в настройках), логотип организации и картинка соцсетей по умолчанию в SEO, изображение записи (_thumbnail_id во frontmatter, выводится вставкой 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/wp-content/uploads/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.

Удалить

В API v2 ручки удаления медиа нет. Удаляет первая версия API, и она принимает тот же токен — вместе с файлом и всеми размерами:

curl -s -X DELETE "https://ВАШ_ДОМЕН/wp-json/onpress/v1/media/bulk-delete" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"items": [6449]}'

{ "success": true, "deleted": 1, "results": [ { "success": true, "id": 6449 } ] }

Элемент — id, адрес или {"filename": "…"}. Запрос идёт на домен самого сайта. Пакетное удаление есть и в разделе «Медиа» дашборда.

Коды ошибок

Код	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	WordPress отказал в приёме файла
`media_failed`, `media_unavailable`	502, 503	исполнитель на сайте ответил неожиданно или не ответил