Üretim

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 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-dataBağlantı ve kimlik doğrulama kontrolü.
POST/api/uploadSes 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/masteringBir 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>.wavTek 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=30Yapay zekâ analizi kullanım istatistikleri.

Yükleme isteği

POST/api/upload

Alan Tür Gerekli Notlar
filemultipart fileEvetİzin verilenler: mp3, wav, flac, m4a, aac, ogg. En fazla 95MB.
modulesstring/listHayırBelirtilmezse varsayılan olarak tüm modüller kullanılır.
detail_levelstringHayırfull (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_balance7 bantlı frekans ve denge puanlaması.
dynamic_rangeDinamik aralık, tepe faktörü, PLR.
stereo_fieldGenişlik, faz ve korelasyon ölçümleri.
claritySpektral netlik ve belirginlik ölçümleri.
harmonic_contentTonalite ve harmonik karmaşıklık.
transientsAtak, transiyent yoğunluğu ve bas vuruş gücü verileri.
3d_spatialYükseklik, derinlik ve genişlik tutarlılığı.
surround_compatibilityMono uyumluluğu ve faz puanı.
headphone_optimizationKulaklıkla çalma optimizasyon puanı.
speaker_optimizationHoparlörle çalma optimizasyon puanı.
genreTür sınıflandırması ve güven düzeyi.
voiceVokal varlığı ve ses özellikleri.
instrumentsEnstrüman algılama ve düzenleme bilgileri.
moodEnerji ve valans içeren ruh hâli profili.
keywordsAnlamsal anahtar kelimeler ve etiketler.
loudnessLUFS, 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.
noiseGü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_qualityKayı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.
referenceReferans
visualizationsAnaliz için oluşturulan görsel varlıkların URL'leri.
ai_insightsLLM 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

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

2) Yükleme ve seçilen modüller

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) Yükleme, seçilen modüller ve özet yanıt

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) Test uç noktası

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

5) İstemci tarafı JavaScript

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);

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
filemultipart fileEvetİ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.
tonenumberHayır1 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.
widthnumberHayır120 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.
punchnumberHayırGlue 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.
loudnessnumberHayırDö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.
monostringHayır120 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.
deharshstringHayır4–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.
sourcestringHayırTiz 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.
stylestringHayırAlt 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_idintegerHayırAnaliz 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-KeyheaderHayır1–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:

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

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
400invalid_fileDosya eksik, biçim desteklenmiyor ya da içerik uzantıyla eşleşmiyor.
400invalid_settingsBir ayar sayı değil ya da geçerli seçeneklerinden biri değil.
400invalid_idempotency_keyIdempotency-Key başlığı yalnızca harf, rakam, _ veya - içeren 1–64 karakterden oluşmuyor.
402insufficient_creditsYeterli token yok. Yanıt gövdesinde cost ve balance bulunur.
403ForbiddenÜ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.
403supporter_onlyMastering şimdilik yalnızca Supporter hesaplarına açık. Ücret alınmaz.
413File too largeDosya 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.
429busyBu 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.
429Rate Limit ExceededAnahtarınızın dakika, saat ya da gün başına sınırına ulaşıldı. Mesaj hangisi olduğunu belirtir.
503failedİşlem başlatılamadı. Bunun için tahsil edilenler iade edilir.

Mastering örneği

1) Bir işlem başlatın

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) Tamamlanana kadar sorgulayın

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

3) Bir master indirin

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

Hata kodları

Durum Anlam Tipik neden
400Geçersiz istekGeçersiz modül/detail_level, eksik dosya alanı veya boş dosya.
401YetkisizEksik, geçersiz veya süresi dolmuş API anahtarı.
403YasakHesap düzeyi API erişimine izin vermiyor.
404Bulunamadı/api/analyze/<file_id> dosya artık kullanılamıyor (gizlilik nedeniyle silinmiş).
413İstek içeriği çok büyükDosya 95MB'den büyük.
429İstek sınırı aşıldıDakika, saat veya gün başına çok fazla istek.
500Sunucu 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.