Dokumentasi API Mixanalytic
Referensi API resmi untuk https://mixanalytic.com. Gunakan API ini untuk mengunggah audio dan menerima analisis mix berbasis AI dengan pilihan modul dan mode respons ringkas atau lengkap.
URL dasar: https://mixanalytic.com/api
Autentikasi
Kirim kunci API Anda dalam header X-API-Key pada setiap permintaan.
- 401 kunci tidak ada atau tidak valid
- 403 kunci paket gratis tanpa akses API
- 429 batas permintaan terlampaui
Cakupan: write digunakan untuk unggah dan analisis Mixanalytic. content membaca data riset konten dengan informasi sensitif disamarkan. content_write menyimpan draf konten nonpublik. Cakupan konten hanya untuk admin.
Endpoint
| Metode | Jalur | Tujuan |
|---|---|---|
| GET | /api/test-data | Pemeriksaan koneksi dan autentikasi. |
| POST | /api/upload | Unggah dan analisis berkas audio. |
| GET | /api/analyze/<file_id> | Analisis ulang berdasarkan ID berkas (jika berkas asli masih ada). |
| POST | /api/mastering | Unggah mix dan mulai satu proses mastering (empat master). |
| GET | /api/mastering/<token> | Status dan hasil proses mastering. |
| GET | /api/mastering/<token>/<variant>.wav | Unduh satu master sebagai WAV 24-bit. |
| GET | /api/content/analysis-feed | Feed riset dengan informasi sensitif disamarkan untuk agen konten, hanya untuk admin. |
| POST | /api/content/drafts | Endpoint penyimpanan dan pembaruan draf untuk agen konten, hanya untuk admin. |
| GET | /api/ai-stats?days=30 | Statistik penggunaan analisis AI. |
Permintaan unggah
POST/api/upload
| Kolom | Jenis | Wajib | Catatan |
|---|---|---|---|
| file | multipart file | Ya | Diizinkan: mp3, wav, flac, m4a, aac, ogg. Maksimum 95MB. |
| modules | string/list | Tidak | Semua modul digunakan secara default jika tidak dicantumkan. |
| detail_level | string | Tidak | full (default) atau summary. |
detail_level yang tidak valid menghasilkan 400. Berkas yang terlalu besar menghasilkan 413.
Pemilihan modul
Tentukan modul analisis yang dikembalikan dan dihitung dengan modules.
Format yang didukung:
- String yang dipisahkan koma: modules=frequency_balance,clarity,mood
- String array JSON: modules=["frequency_balance","clarity","mood"]
- Kunci berulang (kueri/formulir): modules=frequency_balance&modules=clarity
- Semua modul: modules=all atau modules=*
| Modul | Deskripsi |
|---|---|
| frequency_balance | Penilaian frekuensi dan keseimbangan pada 7 pita. |
| dynamic_range | Rentang dinamis, faktor puncak, PLR. |
| stereo_field | Metrik lebar, fase, dan korelasi. |
| clarity | Metrik kejernihan dan definisi spektral. |
| harmonic_content | Nada dasar dan kompleksitas harmonik. |
| transients | Data attack, kepadatan transien, dan punch frekuensi rendah. |
| 3d_spatial | Konsistensi tinggi, kedalaman, dan lebar. |
| surround_compatibility | Kompatibilitas mono + skor fase. |
| headphone_optimization | Skor pengoptimalan pemutaran melalui headphone. |
| speaker_optimization | Skor pengoptimalan pemutaran melalui speaker. |
| genre | Klasifikasi genre dan tingkat keyakinan. |
| voice | Kehadiran vokal dan karakteristik suara. |
| instruments | Deteksi instrumen dan informasi aransemen. |
| mood | Profil suasana dengan energi dan valensi. |
| keywords | Kata kunci dan tag semantik. |
| loudness | Ukur LUFS, true peak, clipping, dan target streaming agar master cukup keras tanpa distorsi, puncak akibat codec, atau kejutan pada platform. |
| noise | Ukur noise floor, dengung listrik, desis, dan artefak. Bersihkan rekaman sebelum mastering membuat gangguan tersebut lebih terdengar. |
| format_quality | Periksa encoding lossy, batas spektral, dan bit depth. Hindari mastering dari sumber MP3, AAC, atau audio yang ditingkatkan resolusinya tetapi sudah terdegradasi. |
| reference | Referensi |
| visualizations | URL untuk aset visual analisis yang dihasilkan. |
| ai_insights | Ringkasan dan rekomendasi yang dihasilkan LLM. |
Pengaturan ukuran respons
Gunakan detail_level:
- full (default): payload lengkap
- summary: payload ringkas untuk klien frontend atau seluler
Contoh
1) Unggah + analisis lengkap
2) Unggah + modul terpilih
3) Unggah + modul terpilih + payload ringkasan
4) Endpoint uji
5) JavaScript sisi klien
Metadata respons standar
Respons analisis yang berhasil mencakup:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Unggah mix jadi dan dapatkan empat master WAV 24-bit dari satu proses: dynamic, balanced, loud, chart. API ini memakai mesin, harga, dan kuota bulanan yang sama dengan Mastering Studio.
- Mastering khusus untuk Supporter: 20 proses per bulan UTC sudah termasuk, setelah itu setiap proses memakai token.
- Satu proses membuat keempat master. Setelah jatah proses habis, satu proses memakai 85 token. Jika proses gagal, token atau proses yang termasuk akan dikembalikan.
- Setiap akun hanya dapat menjalankan satu proses pada satu waktu, termasuk proses dari Mastering Studio.
- Master dihapus 24 jam setelah proses selesai, atau 30 hari pada akun Supporter, kecuali proses tersebut disimpan di Master saya. Unduh sebelum expires_at dalam respons status.
- Memulai proses memerlukan cakupan write. Status dan unduhan memerlukan read.
Permintaan mastering
POST/api/mastering
Kirim mix sebagai multipart/form-data. Hanya file yang wajib.
| Kolom | Jenis | Wajib | Catatan |
|---|---|---|---|
| file | multipart file | Ya | Diizinkan: mp3, wav, flac, aiff, m4a, aac, ogg. Maksimum 95 MB dan 12 menit. Isi berkas harus sesuai dengan ekstensinya. |
| tone | number | Tidak | Tilt nada di sekitar 1 kHz, dalam dB. Negatif lebih hangat, positif lebih terang. -2 hingga 2 dengan langkah 0.5. Default 0. |
| width | number | Tidak | Level side di atas 120 Hz, dalam dB. Negatif lebih sempit, positif lebih lebar. Bass tetap di tengah. -3 hingga 2 dengan langkah 0.5. Default 0. |
| punch | number | Tidak | Kompresi glue sebagai kelipatan dari kebutuhan yang terukur di mix. 0 menonaktifkan glue. 0 hingga 1.5 dengan langkah 0.25. Default 1. |
| loudness | number | Tidak | Menggeser keempat target loudness sekaligus, dalam LU. Jika lebih keras akan membuat drum tergencet, master berhenti lebih awal dan mencantumkannya dalam daftar perubahannya. -3 hingga 1.5 dengan langkah 0.5. Default 0. |
| mono | string | Tidak | Membuat bass mono di bawah 120 Hz. auto hanya menerapkannya jika mix terukur membutuhkannya. Salah satu dari auto, on, off. Default auto. |
| deharsh | string | Tidak | Menurunkan 4–9 kHz hanya pada momen saat frekuensi itu menonjol. auto hanya menerapkannya jika mix terukur membutuhkannya. Salah satu dari auto, on, off. Default auto. |
| source | string | Tidak | Menentukan target treble. ai tidak pernah mengubah air band di atas 10 kHz dan menargetkan frekuensi tinggi yang lebih rendah. recorded menargetkan frekuensi tinggi yang lebih terang. auto memakai penilaian musik AI dari laporan song_id, atau memeriksa unggahan itu sendiri. Salah satu dari auto, ai, recorded. Default auto. |
| style | string | Tidak | Menentukan bobot low end dan master yang direkomendasikan. auto memakai genre dari laporan song_id. Tanpa song_id, tidak ada genre yang diterapkan: low end tetap netral dan rekomendasi mengikuti rentang loudness, jadi kirim gaya untuk memilih genre. Salah satu dari auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Default auto. |
| song_id | integer | Tidak | ID lagu yang sudah Anda analisis. Laporan tersimpannya dipakai ulang alih-alih mengukur unggahan. Unggah mix yang sama. |
| Idempotency-Key | header | Tidak | 1–64 karakter: huruf, angka, _, dan -. |
Angka di luar rentang dipotong ke batasnya dan dibulatkan ke langkahnya. Nilai yang bukan angka, atau pilihan yang tidak dikenal, menghasilkan 400 dengan invalid_settings.
Kirim header Idempotency-Key untuk mencoba ulang dengan aman, dengan kunci baru untuk setiap mix. Jika akun Anda mengulang kunci selama prosesnya masih ada, tidak ada yang ditagih atau dimulai lagi: Anda mendapat 200 dengan isi respons asli ditambah "replayed": true. Jika pengulangan tiba saat permintaan pertama masih dimulai, Anda mendapat 429 busy. Setelah 503 failed, coba lagi dengan kunci baru.
Respons mulai
Proses baru menghasilkan 202:
Proses dari kuota Supporter memiliki "billed": "included" dan "charged": 0. Supporter juga mendapat objek included dengan used, cap, reset_date.
Status dan unduhan mastering
GET/api/mastering/<token>
Periksa status setiap 3–5 detik, dalam batas permintaan kunci Anda, hingga statusnya done atau error.
- pending: master sedang dibuat.
- settling: proses gagal dan token atau proses yang termasuk sedang dikembalikan. Terus periksa status.
- done: keempat master sudah siap.
- error: proses gagal dan biaya yang ditagih sudah dikembalikan. Kolom error menjelaskan alasannya: too_long, too_short, too_quiet, failed.
Respons selesai berisi recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Setiap item dalam masters memiliki key, url, target_lufs, ceiling, metrics, changes, peaks.
Respons selesai dan gagal juga menyertakan access: saldo Anda dan proses yang termasuk setelah proses ini.
Token proses yang tidak dikenal atau kedaluwarsa, serta token milik akun lain, menghasilkan 404 dengan {"status": "expired"}.
Unduh
GET/api/mastering/<token>/<variant>.wav
Mengembalikan master sebagai lampiran WAV 24-bit yang dinamai sesuai unggahan Anda, misalnya My Mix - balanced.wav. variant adalah salah satu dari dynamic, balanced, loud, chart.
Varian yang tidak dikenal, token milik akun lain, atau proses yang sudah kedaluwarsa atau belum selesai menghasilkan 404.
Setiap respons mastering menyertakan Cache-Control: private, no-store.
Kesalahan mastering
Kesalahan dikembalikan sebagai {"error": "invalid_file", "message": "…"}.
| Status | Kesalahan | Makna |
|---|---|---|
| 400 | invalid_file | Berkas tidak ada, format tidak didukung, atau isi tidak sesuai dengan ekstensi. |
| 400 | invalid_settings | Ada pengaturan yang bukan angka atau bukan salah satu pilihannya. |
| 400 | invalid_idempotency_key | Header Idempotency-Key bukan 1–64 huruf, angka, _, atau -. |
| 402 | insufficient_credits | Token tidak cukup. Isi respons menyertakan cost dan balance. |
| 403 | Forbidden | Kunci milik akun gratis, atau kunci tanpa cakupan yang diperlukan endpoint ini. Supporter yang pembayaran perpanjangannya gagal berada di paket gratis sampai pembayaran berhasil, sehingga sementara itu mastering hanya dapat dipakai di Mastering Studio. Tidak ada biaya yang ditagih. |
| 403 | supporter_only | Untuk saat ini mastering hanya tersedia untuk akun Supporter. Tidak ada biaya yang ditagih. |
| 413 | File too large | Berkas lebih besar dari 95 MB, sehingga permintaan ditolak sebelum mencapai endpoint, terkadang tanpa isi JSON. Berkas yang hanya sedikit melewati batas mendapat invalid_file sebagai gantinya. |
| 429 | busy | Akun ini sudah memiliki proses yang sedang berjalan atau sedang dimulai, dari API atau studio. Isi respons menyertakan token proses tersebut, yang bernilai null selama proses itu masih dimulai. |
| 429 | Rate Limit Exceeded | Batas per menit, per jam, atau per hari untuk kunci Anda telah tercapai. Pesannya menyebutkan yang mana. |
| 503 | failed | Proses tidak dapat dimulai. Semua biaya yang ditagih untuk proses ini dikembalikan. |
Contoh mastering
1) Mulai proses
2) Periksa status hingga selesai
3) Unduh master
Kode kesalahan
| Status | Makna | Penyebab umum |
|---|---|---|
| 400 | Permintaan tidak valid | Modul/detail_level tidak valid, kolom file tidak ada, berkas kosong. |
| 401 | Tidak berwenang | Kunci API tidak ada, tidak valid, atau kedaluwarsa. |
| 403 | Dilarang | Akses API tidak diizinkan untuk tingkat akun ini. |
| 404 | Tidak ditemukan | /api/analyze/<file_id> berkas tidak lagi tersedia (dihapus demi privasi). |
| 413 | Payload terlalu besar | Berkas lebih besar dari 95MB. |
| 429 | Batas permintaan terlampaui | Terlalu banyak permintaan per menit, jam, atau hari. |
| 500 | Kesalahan server | Kegagalan analisis atau runtime. |
Catatan frontend
- Untuk klien web atau seluler, utamakan detail_level=summary.
- Minta hanya modul yang dibutuhkan untuk tampilan awal untuk mengurangi latensi dan ukuran payload.
- Tangani 429 dan 500 dengan percobaan ulang dan jeda yang makin lama.
- Jangan memaparkan kunci produksi berumur panjang dalam bundle publik.