واجهة REST مُصدَّرة للتعرف على الأوتار وتحويل كلمات الأغاني وتصدير النوتات. جميع نقاط النهاية تحت /api/v1/، وتقبل JSON وتعيده (باستثناء الملفات المرفوعة والمولدة)، ومتاحة للمطورين المجهولين ضمن حصص استخدام عادلة.
كل نقطة نهاية موثقة تفاعلياً في المرجع المدمج أدناه، والذي يتم توليده مباشرة من التنفيذ ويظل محدثاً دائماً.
يعمل التحليل والتحويل بشكل غير متزامن: ترسل مهمة، تستلم job_id، تتفقد الحالة، ثم تجلب النتيجة الكاملة بعد انتهاء المعالجة.
أرسل تحليل الأوتار لرابط أغنية:
curl -X POST https://magic-chords.dev/api/v1/analyze/url \
-H "Content-Type: application/json" \
-d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'
يحتوي الرد على معرف المهمة:
{"job_id": "bBm3Zx8kQ7...", "status": "processing"}
تفقد الحالة حتى تصبح complete:
curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7...
اجلب الأوتار والإيقاع والمقام والبنية:
curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../result
أو نزّل ملف تصدير مباشرة (pdf، midi، musicxml، txt، csv، json):
curl -o chords.pdf \ "https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../export?format=pdf"
لتحليل ملف صوتي محلي بدلاً من رابط:
curl -X POST https://magic-chords.dev/api/v1/analyze \ -F "file=@song.mp3"
| الطريقة والمسار | الغرض |
|---|---|
POST /api/v1/analyze | إرسال صوت مرفوع لتحليل الأوتار (نموذج multipart) |
POST /api/v1/analyze/url | إرسال رابط وسائط لتحليل الأوتار |
POST /api/v1/transcribe | إرسال صوت مرفوع لتحويل كلمات الأغاني |
POST /api/v1/transcribe/url | إرسال رابط وسائط لتحويل كلمات الأغاني |
GET /api/v1/jobs/{job_id} | حالة مختصرة للاستطلاع |
GET /api/v1/jobs/{job_id}/result | الحصول على النتيجة الكاملة (الأوتار، الكلمات، الإيقاع، المقام…) |
GET /api/v1/jobs/{job_id}/export?format=… | تصدير تحليل مكتمل بصيغة pdf/midi/musicxml/txt/csv/json |
GET /api/v1/limits | سياسة الحصص الحالية (غير محسوبة) |
العملاء المجهولون مقيدين لكل عنوان IP. القيم الحالية (متاحة أيضاً مباشرة من /api/v1/limits):
| الفئة | الحد |
|---|---|
| إرسال المهام (heavy) | 20 في الساعة لكل عميل |
| قراءات الحالة/النتيجة/التصدير (light) | 60 في الدقيقة لكل عميل |
| المهام المتزامنة | مهمتان لكل عميل |
كل استجابة محسوبة تحمل الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. عند بلوغ حد ما ستستلم 429 مع ترويسة Retry-After — يرجى احترامها.
| الحالة | المعنى |
|---|---|
400 | طلب غير صالح (رابط خاطئ أو تنسيق غير معروف) |
404 | معرف مهمة غير معروف |
409 | المهمة موجودة لكنها غير مكتملة أو غير قابلة للتصدير |
413 | الرفع يتجاوز الحجم الأقصى |
415 | لم يُتعرف على الملف كصوت |
429 | تم تجاوز حد الطلبات أو حد التوازي |
503 | غير متاح مؤقتاً (خادم الحصئ متوقف) |
يتم تحميل المرجع الكامل أدناه — تصفح جميع نقاط النهاية وجرّب الطلبات مباشرة من هذه الصفحة.
جارٍ تحميل المرجع التفاعلي…