Публичный API Magic Chords

Версионированный REST API для распознавания аккордов, транскрипции текстов и экспорта нот. Все эндпоинты находятся под /api/v1/, принимают и возвращают JSON (кроме загрузок и созданных файлов) и открыты анонимным разработчикам в рамках разумных квот.

Каждый эндпоинт задокументирован интерактивно во встроенном справочнике ниже — он генерируется непосредственно из реализации и всегда актуален.

Как это работает

Анализ и транскрипция выполняются асинхронно: вы отправляете задание, получаете job_id, опрашиваете статус, а затем забираете полный результат после завершения обработки.

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

Отправить анализ аккордов по URL песни:

curl -X POST https://magic-chords.dev/api/v1/analyze/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

Ответ содержит идентификатор вашего задания:

{"job_id": "bBm3Zx8kQ7...", "status": "processing"}

Опрашивайте, пока статус не станет complete:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7...

Получить аккорды, темп, тональность и структуру:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../result

Или сразу скачать файл экспорта (pdf, midi, musicxml, txt, csv, json):

curl -o chords.pdf \
  "https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../export?format=pdf"

Чтобы проанализировать локальный аудиофайл вместо URL:

curl -X POST https://magic-chords.dev/api/v1/analyze \
  -F "file=@song.mp3"

Эндпоинты

Метод и путь	Назначение
`POST /api/v1/analyze`	Отправить загруженное аудио на анализ аккордов (multipart-форма)
`POST /api/v1/analyze/url`	Отправить медиа-URL на анализ аккордов
`POST /api/v1/transcribe`	Отправить загруженное аудио на транскрипцию текста
`POST /api/v1/transcribe/url`	Отправить медиа-URL на транскрипцию текста
`GET /api/v1/jobs/{job_id}`	Компактный статус для опроса
`GET /api/v1/jobs/{job_id}/result`	Полный результат (аккорды, слова, темп, тональность…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Экспортировать завершённый анализ в pdf/midi/musicxml/txt/csv/json
`GET /api/v1/limits`	Текущая политика квот (не тарифицируется)

Ограничения

Анонимные клиенты ограничены по IP-адресу. Текущие значения по умолчанию (также доступны через /api/v1/limits):

Категория	Лимит
Отправка заданий (heavy)	20 в час на клиента
Чтение статуса/результата/экспорта (light)	60 в минуту на клиента
Одновременные задания	2 на клиента

Каждый учитываемый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При достижении лимита вы получите 429 с заголовком Retry-After — пожалуйста, соблюдайте его.

Ошибки

Статус	Значение
`400`	Неверный запрос (плохой URL, неизвестный формат)
`404`	Неизвестный job_id
`409`	Задание существует, но не завершено или не экспортируется
`413`	Загрузка превышает максимальный размер
`415`	Файл не распознан как аудио
`429`	Превышен лимит запросов или параллельности
`503`	Временно недоступно (квота-бэкенд не работает)

Примечания

Относитесь к job_id как к токену доступа: любой, у кого он есть, может прочитать результат задания.
URL должны указывать на общедоступные хосты; внутренние адреса отклоняются.
Для экспорта требуется завершённый анализ аккордов; задания только с транскрипцией пока не экспортируются.
Cookie-аутентификация YouTube недоступна через публичный API.
IP-адреса клиентов могут записываться для защиты от злоупотреблений.
Кросс-доменный доступ из браузеров по умолчанию отключён; операторы могут разрешить источники через PUBLIC_API_CORS_ORIGINS.

Интерактивный справочник API

Полный справочник загружается ниже — просматривайте все эндпоинты и пробуйте запросы прямо на этой странице.

Загрузка интерактивного справочника…