Whisper Archive API
API-ключи
Ключ действует от вашего имени. Храните его как пароль: не публикуйте в репозиториях и не вставляйте в код сайтов.
Быстрый старт
- Создайте ключ выше. Для загрузки и изменения альбомов нужен доступ «Чтение и запись».
-
Передавайте его в заголовке
Authorization: Bearer wa_…. - Создайте альбом, добавьте треки и сделайте его публичным:
Аутентификация
API принимает ключ в одном из двух заголовков:
Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: wa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Публичные данные (открытые альбомы, профили, стриминг) доступны и без ключа. Ключ нужен, чтобы видеть свои приватные альбомы и что-либо изменять.
| Доступ | Что разрешено |
|---|---|
| read | Только GET-запросы: свои альбомы (включая приватные), треки, стриминг, ссылки для шеринга. |
| write | Всё из read, плюс создание, изменение и удаление альбомов и треков. |
Вход из приложения
Если вы делаете приложение для других людей, ключ создавать вручную не нужно: пользователь входит по коду из письма, как на сайте, и приложение получает токен на чтение и запись на 30 дней.
-
POST /api/auth/request-codeсemail— на почту придёт 6-значный код. Для регистрации нового аккаунта передайте ещёnickname. -
POST /api/auth/tokenсemailиcode— в ответе будетtoken. Сохраните его в защищённом хранилище устройства. -
Когда токен истечёт (ответ
401), снова запросите код. При выходе из аккаунта вызовитеDELETE /api/auth/token.
Через ключ нельзя управлять другими ключами и админ-панелью — это доступно только из браузера после входа по почте. Если ключ утёк, отзовите его в разделе выше: он перестанет работать сразу.
Лимиты
| Обложка | JPG, PNG или WEBP, до 10 MB, не больше 6000×6000 |
| Трек | MP3, WAV, FLAC, OGG или M4A, до 100 MB и 4 часов |
| Альбом | До 50 треков и 500 MB суммарно |
| Код на почту | Не больше 5 запросов за 10 минут с одного IP; код действует 10 минут, 5 попыток ввода |
| Название | Альбом — до 75 символов, трек — до 200 |
При превышении лимита запросов сервер отвечает 429 с заголовком
Retry-After — подождите указанное число секунд.
Синхронизация библиотеки
Свои треки пользователя в приложениях Whisper — скачанные по ссылке с YouTube, SoundCloud или из видео ВКонтакте, свои файлы, обрезки, замены треков площадки — архив хранит вместе с файлом и временем лайка. Так на телефоне и на другом компьютере получается та же картина: те же треки на тех же местах в «Лайках».
service |
Площадка, чьей библиотеке принадлежит трек: yandex, vk
или archive. У каждого приложения свои «Лайки» — трек из клиента
Яндекса не появится в клиенте ВК. |
key |
Номер трека у клиента, одинаковый на всех устройствах
(a-z 0-9 - _, до 64 символов; Whisper Music — studio-…). |
kind |
import — свой трек, replace — свой файл вместо трека
площадки (replaces), cut — обрезка трека площадки. |
source |
Откуда файл: site (youtube, soundcloud,
vk-video, file…), url и id на сайте. |
revision |
Номер изменения: растёт при любой правке записи. Клиент спрашивает
«что изменилось после N» — удаления приходят записями с deleted: true. |
likedAt |
Время лайка в мс (UTC), 0 — без лайка. По нему трек встаёт среди
лайков площадки. |
Как синхронизировать
-
GET /api/library/{service}?since={revision}— забрать изменения (на новом устройстве — безsince: вся библиотека). Удалённое — удалить у себя, новое — скачать файл (GET …/{key}/file) и сохранить с тем жеkey. -
POST /api/library/{service}/changes— отправить свои изменения пачкой (до 100 записей и 100 удалений). Не переданное поле не меняется. -
PUT /api/library/{service}/{key}/file— загрузить файл трека, которого на сервере ещё нет.
Порядок в «Лайках»
Лайки площадки и свои лайкнутые треки сливаются по времени лайка, новые сверху.
При равном времени свой трек выше; трек площадки без известного времени — после всех своих.
Пример: лайки Яндекса в 15:00 и 13:00, трек с YouTube лайкнут в 14:00 — он второй, на любом
устройстве. Записи replace отдельной строкой не показываются: файл играет вместо
трека площадки, а лайк — у самого трека.
свои = лайкнутые записи по убыванию likedAt
для каждого лайка площадки t (новые сверху):
пока есть свой s и (время t неизвестно или s.likedAt >= t.likedAt): вывести s
вывести t
вывести оставшиеся свои
Конфликты: побеждает последняя запись на сервере — поэтому клиент сначала забирает изменения,
потом отправляет свои. Файлы библиотеки занимают то же место, что альбомы (5 GB на аккаунт).
Полное описание — в docs/LIBRARY-SYNC.md репозитория архива, примеры запросов —
в разделе «Эндпоинты» ниже.
Ошибки
Все ответы — JSON. Ошибка всегда приходит в одном формате:
{
"type": "not_found",
"message": "Альбом не найден."
}
Ориентируйтесь на type — он стабилен, а message
предназначен для человека. Некоторые ошибки содержат дополнительные поля:
invalid_track — fileName,
validation_error — errors,
rate_limit_exceeded — retryAfterSeconds.
| Код | Когда |
|---|---|
400 | Некорректные данные или файл не прошёл проверку (bad_request, validation_error, invalid_cover, invalid_track, storage_quota_exceeded) |
401 | Ключ не передан, отозван или истёк (unauthorized) |
403 | Чужой альбом или ключ только на чтение (forbidden, read_only_key) |
404 | Объект не найден или приватный и недоступен вам (not_found) |
409 | Конфликт: например, попытка удалить последний трек альбома (conflict) |
429 | Превышен лимит запросов (rate_limit_exceeded) |
Эндпоинты
Нажмите на эндпоинт, чтобы увидеть пример. Полная схема — в OpenAPI и интерактивной документации.