Mixanalytic API belgeleri
https://mixanalytic.com için resmî API referansı. Ses yüklemek ve seçilebilir modüller ile kompakt ya da tam yanıt modları kullanarak yapay zekâ destekli miks analizi almak için bu API'yi kullanın.
Temel URL: https://mixanalytic.com/api
Kimlik doğrulama
Her istekte API anahtarınızı X-API-Key başlığında gönderin.
- 401 eksik veya geçersiz anahtar
- 403 API erişimi olmayan ücretsiz plan anahtarı
- 429 istek sınırı aşıldı
Kapsamlar: write, Mixanalytic'da yükleme ve analiz içindir. content, hassas verileri gizlenmiş içerik araştırması verilerini okur. content_write, herkese açık olmayan içerik taslaklarını kaydeder. İçerik kapsamları yalnızca yöneticiler içindir.
Uç noktalar
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /api/test-data | Bağlantı ve kimlik doğrulama kontrolü. |
| POST | /api/upload | Ses dosyası yükle ve analiz et. |
| GET | /api/analyze/<file_id> | Dosya kimliği ile yeniden analiz et (orijinal dosya hâlâ mevcutsa). |
| POST | /api/mastering | Bir miks yükleyin ve bir mastering işlemi başlatın (dört master). |
| GET | /api/mastering/<token> | Bir mastering işleminin durumu ve sonuçları. |
| GET | /api/mastering/<token>/<variant>.wav | Tek bir masterı 24-bit WAV olarak indirin. |
| GET | /api/content/analysis-feed | İçerik ajanları için yalnızca yöneticilere açık, hassas verileri gizlenmiş araştırma akışı. |
| POST | /api/content/drafts | İçerik ajanları için yalnızca yöneticilere açık taslak kaydetme ve güncelleme uç noktası. |
| GET | /api/ai-stats?days=30 | Yapay zekâ analizi kullanım istatistikleri. |
Yükleme isteği
POST/api/upload
| Alan | Tür | Gerekli | Notlar |
|---|---|---|---|
| file | multipart file | Evet | İzin verilenler: mp3, wav, flac, m4a, aac, ogg. En fazla 95MB. |
| modules | string/list | Hayır | Belirtilmezse varsayılan olarak tüm modüller kullanılır. |
| detail_level | string | Hayır | full (varsayılan) veya summary. |
Geçersiz detail_level, 400 döndürür. Boyut sınırını aşan dosyalar 413 döndürür.
Modül seçimi
Hangi analiz modüllerinin döndürüleceğini (ve hesaplanacağını) modules ile kontrol edin.
Desteklenen biçimler:
- Virgülle ayrılmış metin: modules=frequency_balance,clarity,mood
- JSON dizi metni: modules=["frequency_balance","clarity","mood"]
- Tekrarlanan anahtar (sorgu/form): modules=frequency_balance&modules=clarity
- Tüm modüller: modules=all veya modules=*
| Modül | Açıklama |
|---|---|
| frequency_balance | 7 bantlı frekans ve denge puanlaması. |
| dynamic_range | Dinamik aralık, tepe faktörü, PLR. |
| stereo_field | Genişlik, faz ve korelasyon ölçümleri. |
| clarity | Spektral netlik ve belirginlik ölçümleri. |
| harmonic_content | Tonalite ve harmonik karmaşıklık. |
| transients | Atak, transiyent yoğunluğu ve bas vuruş gücü verileri. |
| 3d_spatial | Yükseklik, derinlik ve genişlik tutarlılığı. |
| surround_compatibility | Mono uyumluluğu ve faz puanı. |
| headphone_optimization | Kulaklıkla çalma optimizasyon puanı. |
| speaker_optimization | Hoparlörle çalma optimizasyon puanı. |
| genre | Tür sınıflandırması ve güven düzeyi. |
| voice | Vokal varlığı ve ses özellikleri. |
| instruments | Enstrüman algılama ve düzenleme bilgileri. |
| mood | Enerji ve valans içeren ruh hâli profili. |
| keywords | Anlamsal anahtar kelimeler ve etiketler. |
| loudness | LUFS, gerçek tepe, kırpma ve streaming hedeflerini ölçün; master yeterince yüksek kalsın, bozulma, codec tepeleri veya platform sürprizleri olmasın. |
| noise | Gürültü tabanı, şebeke uğultusu, tıslama ve artefaktları ölçün; mastering onları yükseltip parlaklaştırarak gizlemeyi zorlaştırmadan kayıtları temizleyin. |
| format_quality | Kayıplı kodlama, spektral kesim ve bit derinliğini kontrol edin; yayımdan önce bozulmuş MP3, AAC veya yükseltilmiş kaynaklarla yanlışlıkla mastering yapmayın. |
| reference | Referans |
| visualizations | Analiz için oluşturulan görsel varlıkların URL'leri. |
| ai_insights | LLM tarafından oluşturulan özet ve öneriler. |
Yanıt boyutu kontrolü
detail_level kullanın:
- full (varsayılan): tam yanıt
- summary: web ve mobil istemciler için kompakt yanıt
Örnekler
1) Yükleme ve tam analiz
2) Yükleme ve seçilen modüller
3) Yükleme, seçilen modüller ve özet yanıt
4) Test uç noktası
5) İstemci tarafı JavaScript
Standart yanıt meta verileri
Başarılı analiz yanıtları şunları içerir:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Bitmiş bir miks yükleyin ve tek işlemde dört adet 24-bit WAV master alın: dynamic, balanced, loud, chart. API, Mastering Studio ile aynı motoru, fiyatı ve aylık kotayı kullanır.
- Mastering yalnızca Supporter hesapları için: her UTC ayında 20 işlem dahildir, sonrasında her işlem token kullanır.
- Tek bir işlem dört masterın tamamını oluşturur. Dahil işlemlerden sonra bir işlem 85 token tutar. Bir işlem başarısız olursa tokenlarınız ya da dahil işlem hakkınız iade edilir.
- Her hesap aynı anda yalnızca bir işlem yürütebilir; bu sınır Mastering Studio ile ortaktır.
- Masterlar, işlem bittikten 24 saat sonra, Supporter hesabında ise 30 gün sonra silinir; işlem Masterlarım'da saklanıyorsa silinmez. Masterları, durum yanıtındaki expires_at zamanından önce indirin.
- İşlem başlatmak için write kapsamı gerekir. Durum sorguları ve indirmeler için read kapsamı gerekir.
Mastering isteği
POST/api/mastering
Miksi multipart/form-data olarak gönderin. Yalnızca file zorunludur.
| Alan | Tür | Gerekli | Notlar |
|---|---|---|---|
| file | multipart file | Evet | İzin verilen biçimler: mp3, wav, flac, aiff, m4a, aac, ogg. En fazla 95 MB ve 12 dakika. Dosya içeriği uzantıyla eşleşmelidir. |
| tone | number | Hayır | 1 kHz civarında ton eğimi, dB cinsinden. Negatif değerler daha sıcak, pozitif değerler daha parlak bir ses verir. -2 ile 2 arası, 0.5 adımlarla. Varsayılan: 0. |
| width | number | Hayır | 120 Hz üstündeki side sinyal seviyesi, dB cinsinden. Negatif değerler daha dar, pozitif değerler daha geniş bir ses verir. Bas ortada kalır. -3 ile 2 arası, 0.5 adımlarla. Varsayılan: 0. |
| punch | number | Hayır | Glue kompresyonu, miks için ölçülen miktarın katı olarak. 0 glue'yu kapatır. 0 ile 1.5 arası, 0.25 adımlarla. Varsayılan: 1. |
| loudness | number | Hayır | Dört ses yüksekliği hedefini birlikte kaydırır, LU cinsinden. Daha yüksek ses davulları ezecekse master daha erken durur ve bunu değişiklik listesinde belirtir. -3 ile 1.5 arası, 0.5 adımlarla. Varsayılan: 0. |
| mono | string | Hayır | 120 Hz altındaki bası mono yapar. auto değeri bunu yalnızca miksin ölçümünde ihtiyaç görüldüğünde uygular. Şunlardan biri: auto, on, off. Varsayılan: auto. |
| deharsh | string | Hayır | 4–9 kHz aralığını yalnızca öne çıktığı anlarda kısar. auto değeri bunu yalnızca miksin ölçümünde ihtiyaç görüldüğünde uygular. Şunlardan biri: auto, on, off. Varsayılan: auto. |
| source | string | Hayır | Tiz hedefini belirler. ai 10 kHz üstündeki hava bandına asla dokunmaz ve tizleri daha düşük hedefler. recorded daha parlak üst frekanslar hedefler. auto değeri song_id raporundaki yapay zekâ müziği değerlendirmesini kullanır ya da yüklenen dosyayı kendisi kontrol eder. Şunlardan biri: auto, ai, recorded. Varsayılan: auto. |
| style | string | Hayır | Alt frekansların ağırlığını ve hangi masterın önerileceğini belirler. auto değeri song_id raporundaki türü kullanır. song_id olmadan hiçbir tür uygulanmaz: alt frekanslar nötr kalır ve öneri loudness aralığına göre yapılır, bu yüzden bir tür seçmek için bir stil gönderin. Şunlardan biri: auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Varsayılan: auto. |
| song_id | integer | Hayır | Analiz ettiğiniz bir şarkının kimliği. Yüklenen dosya ölçülmek yerine şarkının kayıtlı raporu yeniden kullanılır. Aynı miksi yükleyin. |
| Idempotency-Key | header | Hayır | 1–64 karakter: harfler, rakamlar, _ ve -. |
Aralık dışındaki sayılar aralığın sınırına çekilir ve adımına yuvarlanır. Sayı olmayan bir değer ya da bilinmeyen bir seçenek 400 ile birlikte invalid_settings döndürür.
Güvenle yeniden denemek için bir Idempotency-Key başlığı gönderin ve her miks için yeni bir anahtar kullanın. Hesabınız işlem hâlâ mevcutken bir anahtarı tekrarlarsa yeniden ücret alınmaz ve yeni işlem başlatılmaz: orijinal gövdeyle birlikte "replayed": true içeren 200 yanıtını alırsınız. Tekrar, ilk istek hâlâ başlatılırken gelirse 429 busy alırsınız. 503 failed sonrasında yeni bir anahtarla yeniden deneyin.
Başlatma yanıtı
Yeni bir işlem 202 döndürür:
Supporter kotasından yapılan bir işlemin yanıtında "billed": "included" ve "charged": 0 bulunur. Supporter hesapları ayrıca used, cap, reset_date içeren bir included nesnesi de alır.
Mastering durumu ve indirmeler
GET/api/mastering/<token>
Durum done ya da error olana kadar, anahtarınızın istek sınırı içinde kalarak 3–5 saniyede bir sorgulayın.
- pending: masterlar hazırlanıyor.
- settling: işlem başarısız oldu; tokenlarınız ya da dahil işlem hakkınız iade ediliyor. Sorgulamaya devam edin.
- done: dört master hazır.
- error: işlem başarısız oldu ve işlem için tahsil edilenler iade edildi. error alanı nedenini belirtir: too_long, too_short, too_quiet, failed.
Tamamlanmış bir yanıtta şunlar bulunur: recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. masters içindeki her öğede şunlar bulunur: key, url, target_lufs, ceiling, metrics, changes, peaks.
Tamamlanmış ve hatalı yanıtlar ayrıca access alanını içerir: işlemden sonraki bakiyeniz ve dahil işlem haklarınız.
Bilinmeyen ya da süresi dolmuş işlem tokenları ve başka hesaplara ait işlem tokenları 404 ile birlikte {"status": "expired"} döndürür.
İndirme
GET/api/mastering/<token>/<variant>.wav
Masterı, yüklediğiniz dosyanın adını taşıyan 24-bit WAV eki olarak döndürür; örneğin My Mix - balanced.wav. variant şunlardan biridir: dynamic, balanced, loud, chart.
Bilinmeyen bir sürüm, başka bir hesaba ait işlem tokenı ya da süresi dolmuş veya henüz tamamlanmamış bir işlem 404 döndürür.
Her mastering yanıtında Cache-Control: private, no-store başlığı bulunur.
Mastering hataları
Hatalar {"error": "invalid_file", "message": "…"} biçiminde döndürülür.
| Durum | Hata | Anlam |
|---|---|---|
| 400 | invalid_file | Dosya eksik, biçim desteklenmiyor ya da içerik uzantıyla eşleşmiyor. |
| 400 | invalid_settings | Bir ayar sayı değil ya da geçerli seçeneklerinden biri değil. |
| 400 | invalid_idempotency_key | Idempotency-Key başlığı yalnızca harf, rakam, _ veya - içeren 1–64 karakterden oluşmuyor. |
| 402 | insufficient_credits | Yeterli token yok. Yanıt gövdesinde cost ve balance bulunur. |
| 403 | Forbidden | Ücretsiz bir hesabın anahtarı ya da bu uç noktanın gerektirdiği kapsama sahip olmayan bir anahtar. Yenileme ödemesi başarısız olan bir Supporter, ödeme gerçekleşene kadar Ücretsiz plandadır; bu sürede mastering yalnızca Mastering Studio'da çalışır. Ücret alınmaz. |
| 403 | supporter_only | Mastering şimdilik yalnızca Supporter hesaplarına açık. Ücret alınmaz. |
| 413 | File too large | Dosya 95 MB'tan büyük olduğu için istek uç noktaya ulaşmadan reddedilir, bazen JSON gövdesi olmadan. Sınırı yalnızca biraz aşan bir dosya bunun yerine invalid_file alır. |
| 429 | busy | Bu hesap için API'den ya da stüdyodan başlatılmış bir işlem zaten sürüyor ya da başlatılıyor. Yanıt gövdesinde o işlemin token değeri bulunur; işlem hâlâ başlatılırken bu değer null olur. |
| 429 | Rate Limit Exceeded | Anahtarınızın dakika, saat ya da gün başına sınırına ulaşıldı. Mesaj hangisi olduğunu belirtir. |
| 503 | failed | İşlem başlatılamadı. Bunun için tahsil edilenler iade edilir. |
Mastering örneği
1) Bir işlem başlatın
2) Tamamlanana kadar sorgulayın
3) Bir master indirin
Hata kodları
| Durum | Anlam | Tipik neden |
|---|---|---|
| 400 | Geçersiz istek | Geçersiz modül/detail_level, eksik dosya alanı veya boş dosya. |
| 401 | Yetkisiz | Eksik, geçersiz veya süresi dolmuş API anahtarı. |
| 403 | Yasak | Hesap düzeyi API erişimine izin vermiyor. |
| 404 | Bulunamadı | /api/analyze/<file_id> dosya artık kullanılamıyor (gizlilik nedeniyle silinmiş). |
| 413 | İstek içeriği çok büyük | Dosya 95MB'den büyük. |
| 429 | İstek sınırı aşıldı | Dakika, saat veya gün başına çok fazla istek. |
| 500 | Sunucu hatası | Analiz veya çalışma zamanı hatası. |
Ön yüz notları
- Web ve mobil istemcilerde detail_level=summary tercih edin.
- Gecikmeyi ve yanıt boyutunu azaltmak için yalnızca ilk gösterimde gereken modülleri isteyin.
- 429 ve 500 yanıtlarını yeniden deneme ve giderek artan bekleme süreleri ile işleyin.
- Uzun süre geçerli üretim anahtarlarını herkese açık paketlerde paylaşmayın.