بيئة الإنتاج

توثيق Mixanalytic API

المرجع الرسمي لواجهة API على https://mixanalytic.com. استخدمها لرفع الصوت وتلقي تحليل مكس مدعوم بـ AI، مع اختيار الوحدات وأنماط استجابة مختصرة أو كاملة.

عنوان URL الأساسي: https://mixanalytic.com/api

المصادقة

أرسل مفتاح API في ترويسة X-API-Key مع كل طلب.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 401 مفتاح مفقود أو غير صالح
  • 403 مفتاح خطة مجانية دون صلاحية الوصول إلى API
  • 429 تجاوز حد معدل الطلبات

نطاقات الصلاحيات: يُستخدم write للرفع/التحليل في Mixanalytic. يقرأ content بيانات أبحاث المحتوى بعد حجب المعلومات الحساسة. يحفظ content_write مسودات محتوى غير عامة. نطاقات المحتوى مخصصة للمسؤولين فقط.

نقاط النهاية

الطريقة المسار الغرض
GET/api/test-dataفحص الاتصال/المصادقة.
POST/api/uploadرفع ملف صوتي وتحليله.
GET/api/analyze/<file_id>إعادة التحليل باستخدام معرّف الملف (إذا كان الملف الأصلي لا يزال موجودًا).
POST/api/masteringرفع مكس وبدء عملية ماسترينغ واحدة (أربع نسخ ماستر).
GET/api/mastering/<token>حالة عملية الماسترينغ ونتائجها.
GET/api/mastering/<token>/<variant>.wavتنزيل نسخة ماستر واحدة بصيغة WAV بدقة 24-bit.
GET/api/content/analysis-feedموجز أبحاث لوكلاء المحتوى بعد حجب المعلومات الحساسة، مخصص للمسؤولين فقط.
POST/api/content/draftsنقطة نهاية لحفظ/تحديث مسودات وكلاء المحتوى، مخصصة للمسؤولين فقط.
GET/api/ai-stats?days=30إحصاءات استخدام تحليل AI.

طلب الرفع

POST/api/upload

الحقل النوع مطلوب ملاحظات
filemultipart fileنعمالصيغ المسموحة: mp3, wav, flac, m4a, aac, ogg. الحد الأقصى 95MB.
modulesstring/listلاتُستخدم جميع الوحدات افتراضيًا إذا لم يُحدّد هذا الحقل.
detail_levelstringلاfull (افتراضي) أو summary.

إذا كانت قيمة detail_level غير صالحة تُعاد 400. الملفات الأكبر من الحد المسموح تُعيد 413.

اختيار الوحدات

تحكّم في وحدات التحليل التي تُعاد وتُحسب باستخدام modules.

الصيغ المدعومة:

  • سلسلة نصية مفصولة بفواصل: modules=frequency_balance,clarity,mood
  • سلسلة نصية لمصفوفة JSON: modules=["frequency_balance","clarity","mood"]
  • مفتاح متكرر (استعلام/نموذج): modules=frequency_balance&modules=clarity
  • جميع الوحدات: modules=all أو modules=*
الوحدة الوصف
frequency_balanceتقييم الترددات والتوازن عبر 7 نطاقات.
dynamic_rangeالنطاق الديناميكي، عامل القمة، PLR.
stereo_fieldمقاييس الاتساع/الطور/الارتباط.
clarityمقاييس الوضوح الطيفي وتحديد التفاصيل.
harmonic_contentالمفتاح الموسيقي والتعقيد التوافقي.
transientsبيانات الهجوم الصوتي وكثافة العابرات وقوة الضربة في الترددات المنخفضة.
3d_spatialاتساق الارتفاع/العمق/العرض.
surround_compatibilityتوافق الصوت الأحادي + تقييم الطور.
headphone_optimizationتقييم تحسين التشغيل عبر السماعات الرأسية.
speaker_optimizationتقييم تحسين التشغيل عبر مكبرات الصوت.
genreتصنيف النوع الموسيقي ودرجة الثقة.
voiceحضور الغناء وخصائص الصوت البشري.
instrumentsاكتشاف الآلات ومعلومات التوزيع الموسيقي.
moodملف المزاج مع الطاقة والقيمة الوجدانية.
keywordsكلمات مفتاحية ووسوم دلالية.
loudnessقِس LUFS والذروة الحقيقية والقص وأهداف البث ليبقى الماستر عاليًا بما يكفي دون تشويه أو قمم ناتجة عن الترميز أو مفاجآت على المنصات.
noiseقِس مستوى الضوضاء وطنين الشبكة والهسيس والشوائب لتنظيف التسجيلات قبل أن يجعلها الماسترينغ أعلى وأسطع وأصعب في الإخفاء.
format_qualityافحص الترميز بفقد والقطع الطيفي وعمق البت كي لا تستخدم خطأً مصادر MP3 أو AAC متدهورة أو مصادر مرفوعة الدقة في الماسترينغ قبل الإصدار.
referenceالمرجع
visualizationsعناوين URL للأصول المرئية الناتجة عن التحليل.
ai_insightsملخص وتوصيات يولّدها LLM.

التحكّم في حجم الاستجابة

استخدم detail_level:

  • full (افتراضي): حمولة كاملة
  • summary: حمولة مختصرة لعملاء الواجهة الأمامية/الهاتف

أمثلة

1) رفع + تحليل كامل

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

2) رفع + وحدات مختارة

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) رفع + وحدات مختارة + حمولة ملخصة

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) نقطة نهاية الاختبار

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

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

البيانات الوصفية القياسية للاستجابة

تتضمن استجابات التحليل الناجحة:

  • requested_modules
  • returned_modules
  • detail_level
  • available_modules

الماسترينغ

ارفع مكسًا نهائيًا واحصل على أربع نسخ ماستر بصيغة WAV بدقة 24-bit من عملية واحدة: dynamic, balanced, loud, chart. تستخدم API المحرك والسعر والحصة الشهرية نفسها المستخدمة في استوديو الماسترينغ.

  • الماسترينغ متاح لمشتركي Supporter فقط: 20 عملية مضمّنة في كل شهر بتوقيت UTC، ثم تستخدم كل عملية التوكنات.
  • تُنشئ العملية الواحدة نسخ الماستر الأربع كلها. بعد العمليات المضمّنة تكلّف العملية 85 توكن. إذا فشلت العملية، تُعاد توكناتها أو العملية المضمّنة التي استخدمتها.
  • يُنفّذ كل حساب عملية واحدة في كل مرة، ويتشارك هذا الحد مع استوديو الماسترينغ.
  • تُحذف نسخ الماستر بعد 24 ساعة من انتهاء العملية، أو بعد 30 يومًا على حساب Supporter، ما لم تُحفظ العملية في «نسخ الماستر الخاصة بي». نزّلها قبل expires_at الوارد في استجابة الحالة.
  • يتطلب بدء عملية نطاق الصلاحية write. وتتطلب الحالة والتنزيلات read.

طلب الماسترينغ

POST/api/mastering

أرسل المكس بتنسيق multipart/form-data. الحقل file وحده مطلوب.

الحقل النوع مطلوب ملاحظات
filemultipart fileنعمالصيغ المسموحة: mp3, wav, flac, aiff, m4a, aac, ogg. الحد الأقصى 95 MB و12 دقيقة. يجب أن يطابق محتوى الملف امتداده.
tonenumberلاإمالة النغمة حول 1 kHz بوحدة dB. القيمة السالبة أدفأ، والموجبة أكثر سطوعًا. من -2 إلى 2 بخطوات قدرها 0.5. القيمة الافتراضية 0.
widthnumberلامستوى الجوانب فوق 120 Hz بوحدة dB. القيمة السالبة أضيق، والموجبة أعرض. يبقى الباس في المنتصف. من -3 إلى 2 بخطوات قدرها 0.5. القيمة الافتراضية 0.
punchnumberلاالضغط اللاصق كمضاعف للمقدار الذي قيس للمكس. القيمة 0 توقف الضغط اللاصق. من 0 إلى 1.5 بخطوات قدرها 0.25. القيمة الافتراضية 1.
loudnessnumberلايحرّك أهداف الجهارة الأربعة معًا بوحدة LU. إذا كانت الجهارة الأعلى ستسحق الطبول، يتوقف الماستر قبل ذلك ويذكر هذا في قائمة تغييراته. من -3 إلى 1.5 بخطوات قدرها 0.5. القيمة الافتراضية 0.
monostringلايجعل الباس أحادي القناة تحت 120 Hz. تطبّقه القيمة auto فقط عندما يُظهر قياس المكس حاجة إليه. إحدى القيم auto, on, off. القيمة الافتراضية auto.
deharshstringلايخفض 4–9 kHz فقط في اللحظات التي تبرز فيها. تطبّقه القيمة auto فقط عندما يُظهر قياس المكس حاجة إليه. إحدى القيم auto, on, off. القيمة الافتراضية auto.
sourcestringلايحدد هدف الترددات العالية. لا تحرّك القيمة ai نطاق الهواء فوق 10 kHz أبدًا، وتستهدف مستوى أخفض للترددات العالية. تستهدف القيمة recorded ترددات عالية أكثر سطوعًا. تستخدم القيمة auto نتيجة كشف موسيقى الذكاء الاصطناعي من تقرير song_id، أو تفحص الملف المرفوع بنفسها. إحدى القيم auto, ai, recorded. القيمة الافتراضية auto.
stylestringلايحدد ثقل الترددات المنخفضة ونسخة الماستر الموصى بها. تستخدم القيمة auto النوع الموسيقي من تقرير song_id. بدون song_id لا يُطبَّق أي نوع موسيقي: تبقى الترددات المنخفضة محايدة وتعتمد التوصية على نطاق علوّ الصوت، لذا أرسل نمطًا لتختار نوعًا موسيقيًا. إحدى القيم auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. القيمة الافتراضية auto.
song_idintegerلامعرّف أغنية حلّلتها. يُعاد استخدام تقريرها المحفوظ بدلًا من قياس الملف المرفوع. ارفع المكس نفسه.
Idempotency-Keyheaderلامن 1 إلى 64 حرفًا: أحرف وأرقام و_ و-.

تُقيَّد الأرقام الخارجة عن النطاق بحدوده وتُقرَّب إلى خطوته. القيمة غير الرقمية أو الخيار غير المعروف يُعيد 400 مع invalid_settings.

أرسل ترويسة Idempotency-Key لإعادة المحاولة بأمان، واستخدم مفتاحًا جديدًا لكل مكس. إذا كرر حسابك مفتاحًا والعملية لا تزال موجودة، فلن يُخصم شيء ولن تبدأ عملية جديدة: تتلقى 200 مع متن الاستجابة الأصلي و"replayed": true. إذا وصل التكرار والطلب الأول لا يزال قيد البدء، تتلقى 429 busy. بعد 503 failed أعد المحاولة بمفتاح جديد.

استجابة البدء

تُعيد العملية الجديدة 202:

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

العملية المحتسبة من حصة Supporter تحتوي على "billed": "included" و"charged": 0. ويتلقى مشتركو Supporter أيضًا كائن included يتضمن used, cap, reset_date.

حالة الماسترينغ والتنزيلات

GET/api/mastering/<token>

استعلم كل 3–5 ثوانٍ، ضمن حد معدل الطلبات لمفتاحك، حتى تصبح الحالة done أو error.

  • pending: نسخ الماستر قيد الإنشاء.
  • settling: فشلت العملية وتجري إعادة توكناتها أو العملية المضمّنة. واصل الاستعلام.
  • done: نسخ الماستر الأربع جاهزة.
  • error: فشلت العملية وأُعيد ما خُصم مقابلها. يوضح الحقل error السبب: too_long, too_short, too_quiet, failed.

تحتوي الاستجابة المكتملة على recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. يتضمن كل عنصر في masters الحقول key, url, target_lufs, ceiling, metrics, changes, peaks.

تتضمن الاستجابات المكتملة واستجابات الخطأ أيضًا access: رصيدك وعملياتك المضمّنة بعد العملية.

رموز العمليات (token) غير المعروفة أو منتهية الصلاحية، ورموز الحسابات الأخرى، تُعيد 404 مع {"status": "expired"}.

التنزيل

GET/api/mastering/<token>/<variant>.wav

يُعيد نسخة الماستر كمرفق WAV بدقة 24-bit يحمل اسم ملفك المرفوع، مثل My Mix - balanced.wav. قيمة variant إحدى القيم dynamic, balanced, loud, chart.

تُعاد 404 عند طلب نسخة غير معروفة، أو رمز عملية (token) تابع لحساب آخر، أو عملية انتهت صلاحيتها أو لم تكتمل بعد.

تحمل كل استجابة ماسترينغ Cache-Control: private, no-store.

أخطاء الماسترينغ

تُعيد الأخطاء {"error": "invalid_file", "message": "…"}.

الحالة الخطأ المعنى
400invalid_fileملف مفقود، أو صيغة غير مدعومة، أو محتوى لا يطابق الامتداد.
400invalid_settingsأحد الإعدادات ليس رقمًا أو ليس من الخيارات المسموحة له.
400invalid_idempotency_keyترويسة Idempotency-Key ليست من 1 إلى 64 حرفًا من الأحرف أو الأرقام أو _ أو -.
402insufficient_creditsالتوكنات غير كافية. يتضمن متن الاستجابة cost وbalance.
403Forbiddenمفتاح لحساب مجاني، أو مفتاح يفتقد نطاق الصلاحية الذي تتطلبه نقطة النهاية هذه. ويُعامَل مشترك Supporter الذي فشلت دفعة تجديده كحساب مجاني إلى أن تتم الدفعة، لذا يعمل الماسترينغ خلال ذلك في استوديو الماسترينغ فقط. لا يُخصم أي شيء.
403supporter_onlyالماسترينغ متاح حاليًا لحسابات Supporter فقط. لا يُخصم أي شيء.
413File too largeحجم الملف أكبر من 95 MB، لذا يُرفض الطلب قبل أن يصل إلى نقطة النهاية، وأحيانًا بدون متن JSON. أما الملف الذي يتجاوز الحد بقليل فيتلقى invalid_file بدلًا من ذلك.
429busyهناك عملية جارية أو قيد البدء لهذا الحساب، من API أو من الاستوديو. يتضمن متن الاستجابة رمز العملية token، وتكون قيمته null ما دامت تلك العملية قيد البدء.
429Rate Limit Exceededبلغ مفتاحك حد الطلبات في الدقيقة أو الساعة أو اليوم. توضح الرسالة أيّها.
503failedتعذر بدء العملية. يُعاد كل ما خُصم مقابلها.

مثال على الماسترينغ

1) بدء عملية

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) الاستعلام حتى الاكتمال

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

3) تنزيل نسخة ماستر

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

رموز الأخطاء

الحالة المعنى السبب المعتاد
400طلب غير صالحقيمة module/detail_level غير صالحة، أو حقل الملف مفقود، أو الملف فارغ.
401غير مصادَق عليهمفتاح API مفقود أو غير صالح أو منتهي الصلاحية.
403الوصول ممنوعفئة الحساب لا تسمح بالوصول إلى API.
404غير موجود/api/analyze/<file_id> الملف لم يعد متاحًا (حُذف لحماية الخصوصية).
413الحمولة كبيرة جدًاالملف أكبر من 95MB.
429تجاوز حد معدل الطلباتطلبات أكثر من المسموح في الدقيقة/الساعة/اليوم.
500خطأ في الخادمفشل في التحليل/وقت التشغيل.

ملاحظات للواجهة الأمامية

  • يُفضّل استخدام detail_level=summary لعملاء الويب/الهاتف.
  • اطلب الوحدات اللازمة للعرض الأول فقط لتقليل زمن الانتظار وحجم الحمولة.
  • عالج 429 و500 بإعادة المحاولة مع زيادة مدة الانتظار بين المحاولات.
  • لا تكشف مفاتيح الإنتاج طويلة الصلاحية في الحزم العامة.