المطوّرون

وثائق API

كل ما تحتاجه للبناء باستخدام MeloLab API: المصادقة، الرصيد، التوليد، المهام، webhooks، والبحث في المكتبة.

البدء

صادِق على كل طلب باستخدام مفتاح API عبر ترويسة Authorization: Bearer. عنوان URL الأساسي هو https://melolab.ai. لا تستهلك نقاط النهاية الخاصة بالقراءة أي رصيد؛ يستخدم إنشاء التوليد رصيد MeloLab الحالي بنفس قواعد التكلفة والاسترداد المطبّقة في تطبيق الويب. أرسِل ترويسة Idempotency-Key عند إنشاء توليد حتى تكون إعادة المحاولة آمنة. تُغلّف الاستجابات الناجحة داخل كائن data؛ وتُعيد الأخطاء الحقول code وmessage وrequest_id.

الحساب

اقرأ ملف API الشخصي، ورصيد النقاط، والاستخدام الأخير.

GET/api/v1/meprofile:read

يعيد ملف API الشخصي المصادَق عليه، بما في ذلك مستوى الحساب وتوفّر API.

curl -X GET https://melolab.ai/api/v1/me \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/creditscredits:read

يعيد رصيد نقاط MeloLab الحالي. لا يستهلك أي نقاط.

curl -X GET https://melolab.ai/api/v1/credits \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/usageprofile:read

يعيد ملخّص الاستخدام وأحداث الطلبات الأخيرة بعد إخفاء البيانات الحسّاسة.

curl -X GET https://melolab.ai/api/v1/usage \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

النماذج

اعرض نماذج MeloLab المتاحة وتكلفتها بالنقاط.

GET/api/v1/modelsmodels:read

يعرض نماذج MeloLab المتاحة مع تكلفتها بالنقاط.

curl -X GET https://melolab.ai/api/v1/models \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/models/{model_id}models:read

يعيد نموذجًا واحدًا حسب المعرّف.

curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

عمليات التوليد

أنشئ توليد موسيقى، واعرض عمليات التوليد الأخيرة، واستعلم عن مهمة حتى تنتهي.

POST/api/v1/generationsgenerations:create

ينشئ توليد موسيقى غير متزامن. يستخدم رصيد MeloLab الحالي؛ ويتطلّب ترويسة Idempotency-Key.

curl -X POST https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"suno/v5-5","prompt":"warm lofi beat for a focus playlist"}'

GET/api/v1/generationsgenerations:read

يعرض مهام التوليد الأخيرة الخاصة بك.

curl -X GET https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/generations/{id}generations:read

يستعلم عن توليد ويعيد مقاطعه بعد اكتماله.

curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/jobs/{job_id}

يستعلم عن مهمة غير متزامنة (موسيقى، فصل المقاطع، أو إزالة الصوت) ويعيد المخرجات بعد انتهاء المزوّد.

curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

المكتبة

ابحث عن المقاطع وقوائم التشغيل القابلة للتشغيل، واقرأ تفاصيل كل مقطع أو قائمة تشغيل.

GET/api/v1/library/searchlibrary:read

يبحث عن المقاطع وقوائم التشغيل القابلة للتشغيل، بما في ذلك عناصرك الخاصة.

curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/tracks/{id}library:read

يعيد البيانات الوصفية القابلة للتشغيل لمقطع.

curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlistslibrary:read

يعرض قوائم التشغيل المتاحة لك.

curl -X GET https://melolab.ai/api/v1/playlists \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlists/{id}library:read

يعيد قائمة تشغيل ومقاطعها.

curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Webhooks

سجّل نقاط نهاية HTTPS لتلقّي إشعار عند انتهاء المهام غير المتزامنة، دون الحاجة إلى الاستعلام المتكرّر. يظهر السر الكامل للتوقيع مرة واحدة فقط عند إنشاء نقطة النهاية.

GET/api/v1/webhook-endpoints

يعرض نقاط نهاية webhook النشطة لديك.

curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

POST/api/v1/webhook-endpoints

يسجّل نقطة نهاية webhook عامة عبر HTTPS. يُعاد سرّ التوقيع مرة واحدة فقط.

curl -X POST https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/melolab/webhook"}'

PATCH/api/v1/webhook-endpoints/{id}

يحدّث عنوان URL أو حالة نقطة نهاية webhook.

curl -X PATCH https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

DELETE/api/v1/webhook-endpoints/{id}

يحذف نقطة نهاية webhook.

curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

السجلات

راجع سجلات طلبات API خلال آخر 30 يومًا.

GET/api/v1/logs

يعرض سجلات طلبات API خلال آخر 30 يومًا.

curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

حدود المعدّل

تسمح نقاط نهاية القراءة بـ 600 طلب في الدقيقة (50,000 في اليوم). يسمح توليد الموسيقى بـ 12 طلبًا في الدقيقة (500 في اليوم). المصادقة محدودة بـ 120 طلبًا في الدقيقة لكل عنوان IP. تجاوز الحد يُعيد 429 rate_limited.

الأخطاء

تُعيد الأخطاء حالة HTTP بالإضافة إلى نص JSON بالشكل { error: { code, message, request_id } }. أرفِق request_id عند التواصل مع الدعم.

الحالة	الرمز	المعنى
401	authentication_required	لم يتم تقديم مفتاح API في ترويسة Authorization.
401	invalid_api_key	مفتاح API غير صالح أو تم إبطاله.
403	insufficient_scope	يفتقر مفتاح API إلى نطاق مطلوب.
400	invalid_request	نص الطلب أو المعلمات غير صالحة.
400	invalid_model	معرّف النموذج المطلوب غير موجود.
402	insufficient_credits	رصيد MeloLab غير كافٍ لإنشاء هذا التوليد.
409	idempotency_conflict	أُعيد استخدام Idempotency-Key مع نص طلب مختلف.
404	not_found	المورد المطلوب غير موجود أو ليس ملكك.
429	rate_limited	طلبات كثيرة جدًا؛ خفّف السرعة وأعد المحاولة لاحقًا.
502	provider_unavailable	المزوّد الأساسي غير متاح مؤقتًا.

وثائق API

البدء

الحساب

النماذج

عمليات التوليد

المكتبة

Webhooks

السجلات

حدود المعدّل

الأخطاء

ابدأ مجانًا

إنشاء

أنماط موسيقية

حالات مزاجية

آلات

موسيقى خلفية

مقارنة

نماذج AI

مؤثرات صوتية

نماذج AI

الشركة