توثيق Mixanalytic API
المرجع الرسمي لواجهة API على https://mixanalytic.com. استخدمها لرفع الصوت وتلقي تحليل مكس مدعوم بـ AI، مع اختيار الوحدات وأنماط استجابة مختصرة أو كاملة.
عنوان URL الأساسي: https://mixanalytic.com/api
المصادقة
أرسل مفتاح API في ترويسة X-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
| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| file | multipart file | نعم | الصيغ المسموحة: mp3, wav, flac, m4a, aac, ogg. الحد الأقصى 95MB. |
| modules | string/list | لا | تُستخدم جميع الوحدات افتراضيًا إذا لم يُحدّد هذا الحقل. |
| detail_level | string | لا | 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) رفع + تحليل كامل
2) رفع + وحدات مختارة
3) رفع + وحدات مختارة + حمولة ملخصة
4) نقطة نهاية الاختبار
5) JavaScript من جهة العميل
البيانات الوصفية القياسية للاستجابة
تتضمن استجابات التحليل الناجحة:
- 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 وحده مطلوب.
| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| file | multipart file | نعم | الصيغ المسموحة: mp3, wav, flac, aiff, m4a, aac, ogg. الحد الأقصى 95 MB و12 دقيقة. يجب أن يطابق محتوى الملف امتداده. |
| tone | number | لا | إمالة النغمة حول 1 kHz بوحدة dB. القيمة السالبة أدفأ، والموجبة أكثر سطوعًا. من -2 إلى 2 بخطوات قدرها 0.5. القيمة الافتراضية 0. |
| width | number | لا | مستوى الجوانب فوق 120 Hz بوحدة dB. القيمة السالبة أضيق، والموجبة أعرض. يبقى الباس في المنتصف. من -3 إلى 2 بخطوات قدرها 0.5. القيمة الافتراضية 0. |
| punch | number | لا | الضغط اللاصق كمضاعف للمقدار الذي قيس للمكس. القيمة 0 توقف الضغط اللاصق. من 0 إلى 1.5 بخطوات قدرها 0.25. القيمة الافتراضية 1. |
| loudness | number | لا | يحرّك أهداف الجهارة الأربعة معًا بوحدة LU. إذا كانت الجهارة الأعلى ستسحق الطبول، يتوقف الماستر قبل ذلك ويذكر هذا في قائمة تغييراته. من -3 إلى 1.5 بخطوات قدرها 0.5. القيمة الافتراضية 0. |
| mono | string | لا | يجعل الباس أحادي القناة تحت 120 Hz. تطبّقه القيمة auto فقط عندما يُظهر قياس المكس حاجة إليه. إحدى القيم auto, on, off. القيمة الافتراضية auto. |
| deharsh | string | لا | يخفض 4–9 kHz فقط في اللحظات التي تبرز فيها. تطبّقه القيمة auto فقط عندما يُظهر قياس المكس حاجة إليه. إحدى القيم auto, on, off. القيمة الافتراضية auto. |
| source | string | لا | يحدد هدف الترددات العالية. لا تحرّك القيمة ai نطاق الهواء فوق 10 kHz أبدًا، وتستهدف مستوى أخفض للترددات العالية. تستهدف القيمة recorded ترددات عالية أكثر سطوعًا. تستخدم القيمة auto نتيجة كشف موسيقى الذكاء الاصطناعي من تقرير song_id، أو تفحص الملف المرفوع بنفسها. إحدى القيم auto, ai, recorded. القيمة الافتراضية auto. |
| style | string | لا | يحدد ثقل الترددات المنخفضة ونسخة الماستر الموصى بها. تستخدم القيمة auto النوع الموسيقي من تقرير song_id. بدون song_id لا يُطبَّق أي نوع موسيقي: تبقى الترددات المنخفضة محايدة وتعتمد التوصية على نطاق علوّ الصوت، لذا أرسل نمطًا لتختار نوعًا موسيقيًا. إحدى القيم auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. القيمة الافتراضية auto. |
| song_id | integer | لا | معرّف أغنية حلّلتها. يُعاد استخدام تقريرها المحفوظ بدلًا من قياس الملف المرفوع. ارفع المكس نفسه. |
| Idempotency-Key | header | لا | من 1 إلى 64 حرفًا: أحرف وأرقام و_ و-. |
تُقيَّد الأرقام الخارجة عن النطاق بحدوده وتُقرَّب إلى خطوته. القيمة غير الرقمية أو الخيار غير المعروف يُعيد 400 مع invalid_settings.
أرسل ترويسة Idempotency-Key لإعادة المحاولة بأمان، واستخدم مفتاحًا جديدًا لكل مكس. إذا كرر حسابك مفتاحًا والعملية لا تزال موجودة، فلن يُخصم شيء ولن تبدأ عملية جديدة: تتلقى 200 مع متن الاستجابة الأصلي و"replayed": true. إذا وصل التكرار والطلب الأول لا يزال قيد البدء، تتلقى 429 busy. بعد 503 failed أعد المحاولة بمفتاح جديد.
استجابة البدء
تُعيد العملية الجديدة 202:
العملية المحتسبة من حصة 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": "…"}.
| الحالة | الخطأ | المعنى |
|---|---|---|
| 400 | invalid_file | ملف مفقود، أو صيغة غير مدعومة، أو محتوى لا يطابق الامتداد. |
| 400 | invalid_settings | أحد الإعدادات ليس رقمًا أو ليس من الخيارات المسموحة له. |
| 400 | invalid_idempotency_key | ترويسة Idempotency-Key ليست من 1 إلى 64 حرفًا من الأحرف أو الأرقام أو _ أو -. |
| 402 | insufficient_credits | التوكنات غير كافية. يتضمن متن الاستجابة cost وbalance. |
| 403 | Forbidden | مفتاح لحساب مجاني، أو مفتاح يفتقد نطاق الصلاحية الذي تتطلبه نقطة النهاية هذه. ويُعامَل مشترك Supporter الذي فشلت دفعة تجديده كحساب مجاني إلى أن تتم الدفعة، لذا يعمل الماسترينغ خلال ذلك في استوديو الماسترينغ فقط. لا يُخصم أي شيء. |
| 403 | supporter_only | الماسترينغ متاح حاليًا لحسابات Supporter فقط. لا يُخصم أي شيء. |
| 413 | File too large | حجم الملف أكبر من 95 MB، لذا يُرفض الطلب قبل أن يصل إلى نقطة النهاية، وأحيانًا بدون متن JSON. أما الملف الذي يتجاوز الحد بقليل فيتلقى invalid_file بدلًا من ذلك. |
| 429 | busy | هناك عملية جارية أو قيد البدء لهذا الحساب، من API أو من الاستوديو. يتضمن متن الاستجابة رمز العملية token، وتكون قيمته null ما دامت تلك العملية قيد البدء. |
| 429 | Rate Limit Exceeded | بلغ مفتاحك حد الطلبات في الدقيقة أو الساعة أو اليوم. توضح الرسالة أيّها. |
| 503 | failed | تعذر بدء العملية. يُعاد كل ما خُصم مقابلها. |
مثال على الماسترينغ
1) بدء عملية
2) الاستعلام حتى الاكتمال
3) تنزيل نسخة ماستر
رموز الأخطاء
| الحالة | المعنى | السبب المعتاد |
|---|---|---|
| 400 | طلب غير صالح | قيمة module/detail_level غير صالحة، أو حقل الملف مفقود، أو الملف فارغ. |
| 401 | غير مصادَق عليه | مفتاح API مفقود أو غير صالح أو منتهي الصلاحية. |
| 403 | الوصول ممنوع | فئة الحساب لا تسمح بالوصول إلى API. |
| 404 | غير موجود | /api/analyze/<file_id> الملف لم يعد متاحًا (حُذف لحماية الخصوصية). |
| 413 | الحمولة كبيرة جدًا | الملف أكبر من 95MB. |
| 429 | تجاوز حد معدل الطلبات | طلبات أكثر من المسموح في الدقيقة/الساعة/اليوم. |
| 500 | خطأ في الخادم | فشل في التحليل/وقت التشغيل. |
ملاحظات للواجهة الأمامية
- يُفضّل استخدام detail_level=summary لعملاء الويب/الهاتف.
- اطلب الوحدات اللازمة للعرض الأول فقط لتقليل زمن الانتظار وحجم الحمولة.
- عالج 429 و500 بإعادة المحاولة مع زيادة مدة الانتظار بين المحاولات.
- لا تكشف مفاتيح الإنتاج طويلة الصلاحية في الحزم العامة.