Produksi

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 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-dataPemeriksaan koneksi dan autentikasi.
POST/api/uploadUnggah dan analisis berkas audio.
GET/api/analyze/<file_id>Analisis ulang berdasarkan ID berkas (jika berkas asli masih ada).
POST/api/masteringUnggah mix dan mulai satu proses mastering (empat master).
GET/api/mastering/<token>Status dan hasil proses mastering.
GET/api/mastering/<token>/<variant>.wavUnduh satu master sebagai WAV 24-bit.
GET/api/content/analysis-feedFeed riset dengan informasi sensitif disamarkan untuk agen konten, hanya untuk admin.
POST/api/content/draftsEndpoint penyimpanan dan pembaruan draf untuk agen konten, hanya untuk admin.
GET/api/ai-stats?days=30Statistik penggunaan analisis AI.

Permintaan unggah

POST/api/upload

Kolom Jenis Wajib Catatan
filemultipart fileYaDiizinkan: mp3, wav, flac, m4a, aac, ogg. Maksimum 95MB.
modulesstring/listTidakSemua modul digunakan secara default jika tidak dicantumkan.
detail_levelstringTidakfull (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_balancePenilaian frekuensi dan keseimbangan pada 7 pita.
dynamic_rangeRentang dinamis, faktor puncak, PLR.
stereo_fieldMetrik lebar, fase, dan korelasi.
clarityMetrik kejernihan dan definisi spektral.
harmonic_contentNada dasar dan kompleksitas harmonik.
transientsData attack, kepadatan transien, dan punch frekuensi rendah.
3d_spatialKonsistensi tinggi, kedalaman, dan lebar.
surround_compatibilityKompatibilitas mono + skor fase.
headphone_optimizationSkor pengoptimalan pemutaran melalui headphone.
speaker_optimizationSkor pengoptimalan pemutaran melalui speaker.
genreKlasifikasi genre dan tingkat keyakinan.
voiceKehadiran vokal dan karakteristik suara.
instrumentsDeteksi instrumen dan informasi aransemen.
moodProfil suasana dengan energi dan valensi.
keywordsKata kunci dan tag semantik.
loudnessUkur LUFS, true peak, clipping, dan target streaming agar master cukup keras tanpa distorsi, puncak akibat codec, atau kejutan pada platform.
noiseUkur noise floor, dengung listrik, desis, dan artefak. Bersihkan rekaman sebelum mastering membuat gangguan tersebut lebih terdengar.
format_qualityPeriksa encoding lossy, batas spektral, dan bit depth. Hindari mastering dari sumber MP3, AAC, atau audio yang ditingkatkan resolusinya tetapi sudah terdegradasi.
referenceReferensi
visualizationsURL untuk aset visual analisis yang dihasilkan.
ai_insightsRingkasan 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

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3"

2) Unggah + modul terpilih

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,dynamic_range,genre,mood,keywords"

3) Unggah + modul terpilih + payload ringkasan

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,stereo_field,clarity,ai_insights" \ -F "detail_level=summary"

4) Endpoint uji

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"

5) JavaScript sisi klien

const formData = new FormData(); formData.append('file', fileInput.files[0]); formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights'); formData.append('detail_level', 'summary'); const res = await fetch('https://mixanalytic.com/api/upload', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: formData }); const data = await res.json(); console.log(data.analysis, data.returned_modules);

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
filemultipart fileYaDiizinkan: mp3, wav, flac, aiff, m4a, aac, ogg. Maksimum 95 MB dan 12 menit. Isi berkas harus sesuai dengan ekstensinya.
tonenumberTidakTilt nada di sekitar 1 kHz, dalam dB. Negatif lebih hangat, positif lebih terang. -2 hingga 2 dengan langkah 0.5. Default 0.
widthnumberTidakLevel 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.
punchnumberTidakKompresi glue sebagai kelipatan dari kebutuhan yang terukur di mix. 0 menonaktifkan glue. 0 hingga 1.5 dengan langkah 0.25. Default 1.
loudnessnumberTidakMenggeser 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.
monostringTidakMembuat bass mono di bawah 120 Hz. auto hanya menerapkannya jika mix terukur membutuhkannya. Salah satu dari auto, on, off. Default auto.
deharshstringTidakMenurunkan 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.
sourcestringTidakMenentukan 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.
stylestringTidakMenentukan 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_idintegerTidakID lagu yang sudah Anda analisis. Laporan tersimpannya dipakai ulang alih-alih mengukur unggahan. Unggah mix yang sama.
Idempotency-KeyheaderTidak1–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:

{ "token": "3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "status": "pending", "status_url": "/api/mastering/3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "billed": "tokens", "charged": 85, "balance": 415, "expires_in_hours": 720 }

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
400invalid_fileBerkas tidak ada, format tidak didukung, atau isi tidak sesuai dengan ekstensi.
400invalid_settingsAda pengaturan yang bukan angka atau bukan salah satu pilihannya.
400invalid_idempotency_keyHeader Idempotency-Key bukan 1–64 huruf, angka, _, atau -.
402insufficient_creditsToken tidak cukup. Isi respons menyertakan cost dan balance.
403ForbiddenKunci 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.
403supporter_onlyUntuk saat ini mastering hanya tersedia untuk akun Supporter. Tidak ada biaya yang ditagih.
413File too largeBerkas 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.
429busyAkun 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.
429Rate Limit ExceededBatas per menit, per jam, atau per hari untuk kunci Anda telah tercapai. Pesannya menyebutkan yang mana.
503failedProses tidak dapat dimulai. Semua biaya yang ditagih untuk proses ini dikembalikan.

Contoh mastering

1) Mulai proses

curl -X POST "https://mixanalytic.com/api/mastering" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_MIX" \ -F "file=@/path/to/mix.wav" \ -F "style=electronic" \ -F "loudness=0.5"

2) Periksa status hingga selesai

curl "https://mixanalytic.com/api/mastering/TOKEN" \ -H "X-API-Key: YOUR_API_KEY"

3) Unduh master

curl -o "mix - balanced.wav" "https://mixanalytic.com/api/mastering/TOKEN/balanced.wav" \ -H "X-API-Key: YOUR_API_KEY"

Kode kesalahan

Status Makna Penyebab umum
400Permintaan tidak validModul/detail_level tidak valid, kolom file tidak ada, berkas kosong.
401Tidak berwenangKunci API tidak ada, tidak valid, atau kedaluwarsa.
403DilarangAkses API tidak diizinkan untuk tingkat akun ini.
404Tidak ditemukan/api/analyze/<file_id> berkas tidak lagi tersedia (dihapus demi privasi).
413Payload terlalu besarBerkas lebih besar dari 95MB.
429Batas permintaan terlampauiTerlalu banyak permintaan per menit, jam, atau hari.
500Kesalahan serverKegagalan 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.