Whisper Archive
Whisper Archive
MUSIC ARCHIVE
Скачать приложенияПриложения
Для разработчиков

Whisper Archive API

Base URL

API-ключи

Ключ действует от вашего имени. Храните его как пароль: не публикуйте в репозиториях и не вставляйте в код сайтов.

Загрузка…

Быстрый старт

  1. Создайте ключ выше. Для загрузки и изменения альбомов нужен доступ «Чтение и запись».
  2. Передавайте его в заголовке Authorization: Bearer wa_….
  3. Создайте альбом, добавьте треки и сделайте его публичным:

Аутентификация

API принимает ключ в одном из двух заголовков:

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: wa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Публичные данные (открытые альбомы, профили, стриминг) доступны и без ключа. Ключ нужен, чтобы видеть свои приватные альбомы и что-либо изменять.

Доступ Что разрешено
read Только GET-запросы: свои альбомы (включая приватные), треки, стриминг, ссылки для шеринга.
write Всё из read, плюс создание, изменение и удаление альбомов и треков.

Вход из приложения

Если вы делаете приложение для других людей, ключ создавать вручную не нужно: пользователь входит по коду из письма, как на сайте, и приложение получает токен на чтение и запись на 30 дней.

  1. POST /api/auth/request-code с email — на почту придёт 6-значный код. Для регистрации нового аккаунта передайте ещё nickname.
  2. POST /api/auth/token с email и code — в ответе будет token. Сохраните его в защищённом хранилище устройства.
  3. Когда токен истечёт (ответ 401), снова запросите код. При выходе из аккаунта вызовите DELETE /api/auth/token.

Через ключ нельзя управлять другими ключами и админ-панелью — это доступно только из браузера после входа по почте. Если ключ утёк, отзовите его в разделе выше: он перестанет работать сразу.

Лимиты

120 / мин
запросов на один ключ
3 / 10 мин
создание альбомов
20 / 10 мин
дозагрузка треков
5 GB
хранилище на аккаунт
Обложка 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 — без лайка. По нему трек встаёт среди лайков площадки.

Как синхронизировать

  1. GET /api/library/{service}?since={revision} — забрать изменения (на новом устройстве — без since: вся библиотека). Удалённое — удалить у себя, новое — скачать файл (GET …/{key}/file) и сохранить с тем же key.
  2. POST /api/library/{service}/changes — отправить свои изменения пачкой (до 100 записей и 100 удалений). Не переданное поле не меняется.
  3. 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 и интерактивной документации.

Регистрация
Подтвердите email, чтобы создать аккаунт.