المطوّرون

وثائق 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 غير صالح أو تم إبطاله.
401	revoked_api_key	تم إبطال مفتاح API ولا يمكن استخدامه بعد الآن.
403	api_terms_not_accepted	حساب API غير جاهز لأن شروط API لم تُقبل بعد.
403	insufficient_scope	يفتقر مفتاح API إلى نطاق مطلوب.
400	invalid_request	نص الطلب أو المعلمات غير صالحة.
400	invalid_model	معرّف النموذج المطلوب غير موجود.
402	insufficient_credits	رصيد MeloLab غير كافٍ لإنشاء هذا التوليد.
400	idempotency_key_required	يتطلب هذا الطلب ترويسة Idempotency-Key.
409	idempotency_key_conflict	أُعيد استخدام Idempotency-Key مع شكل طلب مختلف.
409	idempotency_conflict	أُعيد استخدام Idempotency-Key مع نص طلب مختلف.
409	generation_concurrency_exceeded	هناك عدد كبير جدًا من مهام التوليد قيد التشغيل لهذا الحساب.
404	job_not_found	المهمة المطلوبة غير موجودة أو لا تنتمي إلى هذا الحساب.
404	track_not_found	المقطع المطلوب غير موجود أو غير متاح لهذا الحساب.
404	playlist_not_found	قائمة التشغيل المطلوبة غير موجودة أو غير متاحة لهذا الحساب.
404	webhook_endpoint_not_found	نقطة نهاية webhook المطلوبة غير موجودة أو ليست لك.
400	webhook_url_invalid	عنوان URL الخاص بـ webhook غير صالح.
400	webhook_https_required	يجب أن تستخدم نقاط نهاية webhook بروتوكول HTTPS.
400	webhook_credentials_forbidden	لا يمكن أن تحتوي عناوين URL الخاصة بـ webhook على بيانات اعتماد مضمّنة.
400	webhook_host_blocked	لا يمكن أن تشير عناوين URL الخاصة بـ webhook إلى localhost أو مضيفين خاصين أو محظورين.
429	rate_limited	طلبات كثيرة جدًا؛ خفّف السرعة وأعد المحاولة لاحقًا.
502	provider_unavailable	المزوّد الأساسي غير متاح مؤقتًا.
502	provider_timeout	انتهت مهلة المزوّد الأساسي.
500	generation_failed	فشل التوليد بعد قبوله.
500	internal_error	خطأ غير متوقع في منصة API.

وثائق API

البدء

الحساب

النماذج

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

المكتبة

Webhooks

السجلات

حدود المعدّل

الأخطاء

ابدأ مجانًا

إنشاء

Transform

Analyze

الشركة