Медиафайлы
Обзор медиафайлов
Загрузка фото и видео для объявлений через API
Медиафайлы — обязательная часть объявлений. Для публикации нужно минимум 3 фотографии. API поддерживает два способа загрузки и автоматически оптимизирует все файлы.
Вам не нужно оптимизировать фото перед загрузкой — загружайте оригиналы.
Способы загрузки
| Способ | Когда использовать | Описание |
|---|---|---|
| URL в объявлении | Всегда, когда возможно | Самый простой — передайте URL прямо при создании объявления |
| Импорт по URL | Загрузка заранее | Загрузите фото отдельно, потом привяжите к объявлению |
| Signed URL | Загрузка с локального диска | Для файлов без публичного URL |
Рекомендация: Передавайте URL фотографий прямо при создании объявления — система загрузит их автоматически. Это самый простой способ.
Поддерживаемые форматы
Изображения
JPEG, PNG, WebP, HEIC и другие популярные форматы.
Видео
MP4, AVI, MOV — до 3 минут.
Ограничения
| Параметр | Значение |
|---|---|
| Минимум фото для публикации | 3 |
| Максимум фото на объявление | 20 |
| Файлов в одном запросе | до 100 |
| Срок действия signed URL | 30 минут |
Типичный сценарий
Рекомендуемый подход — в одном запросе:
PUT /listings
→ передаём files: [{ url: "https://..." }] и announcementStatus: "active"
→ система автоматически загрузит и оптимизирует фото
Альтернативный подход — раздельная загрузка:
1. Загрузить фото → POST /media/bulk
→ с операцией upload-from-url
2. Привязать к объявлению → PUT /listings
→ передаём files: [{ id: 123 }] или [{ externalFileId: "..." }]
Структура медиафайла
После загрузки и оптимизации файл содержит:
{
"id": 123,
"externalId": "photo-001",
"size": 245000,
"contentType": "image/jpeg",
"optimization": "success",
"blurhash": "L7HuX^zY1z-6ADx?0z2@1Io#{yV_",
"originalUrl": "https://storage.../original.jpg",
"variants": [
{ "url": "https://storage.../128.webp", "variantSize": "128", "size": 4074 },
{ "url": "https://storage.../512.webp", "variantSize": "512", "size": 32850 },
{ "url": "https://storage.../1024.webp", "variantSize": "1024", "size": 98500 }
]
}
| Поле | Описание |
|---|---|
id | Внутренний ID файла |
externalId | Ваш ID из CRM |
optimization | Статус оптимизации |
blurhash | Строка для генерации плейсхолдера |
originalUrl | Ссылка на оригинал |
variants | Оптимизированные версии разных размеров |
API Endpoints
| Метод | Путь | Описание |
|---|---|---|
POST | /media/upload-from-url | Импорт по URL |
POST | /media/bulk | Bulk операции (upload-from-url, confirm-upload, и др.) |
POST | /media/request-upload-url | Signed URL |
GET | /media/:id | Получить файл |
GET | /media/external/:externalId | Получить по external ID |
DELETE | /media/:id | Удалить файл |
DELETE | /media/external/:externalId | Удалить по external ID |
POST | /media/:id/link | Привязать external ID |
DELETE | /media/:id/link | Отвязать external ID |
Следующие шаги
- Загрузить фотографии — пошаговые инструкции
- Управление файлами — получение, удаление, linking