واجهة شهادة الترخيص التجاري للموسيقى

آخر تحديث 2026-09-18 · فريق Suno-API

وصف نقطة النهاية

تُستخدم واجهات شهادة الترخيص التجاري للموسيقى لحصر الأغاني التي يمكن لمستخدم مفتاح API الحالي ترخيصها، وإنشاء شهادة PDF، والاستعلام عن سجل الشهادات، وتنزيل الملفات الصادرة.

تستخدم كل الواجهات مفتاح New API Key بشكل موحّد:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

العنوان الأساسي:

https://www.suno-api.io

المتطلبات المسبقة

• يجب أن يكون مفتاح API صالحاً وأن يخص المستخدم الذي يحتاج الشهادة.
• على المستخدم أولاً إكمال ربط هوية الترخيص (انظر «0. أهلية الترخيص والهوية»)؛ وبعد تأكيدها تُقفل الهوية وفق قواعد المنتج.
• على المستخدم استيفاء شرط الشحن المتراكم للأفراد أو الشركات.
• تعيد الواجهات العادية معلومات هوية مُقنّعة فقط، ولا تعيد أرقام الهوية أو الهاتف أو رموز الائتمان الاجتماعي الموحّد كنص صريح.
• لكل أغنية شهادة واحدة ناجحة فقط؛ والشهادة التي يفشل إنشاؤها لا تستهلك أهلية الأغنية.
• المدعوم حالياً هو أنواع التوليد المحددة التي اكتملت ولها صوت ومعرّف Suno Song ID حقيقي. ويحدد قابلية اختيار الأغنية الحقل authorization.selectable في قائمة الأغاني.

0. أهلية الترخيص والهوية

قبل إصدار الشهادة يلزم الاستعلام عن الأهلية وربط الهوية. وهاتان الواجهتان مجانيتان.

0.1 الاستعلام عن الأهلية والهوية

نقطة النهاية: GET /api/music/authorization/context

{
  "code": 200,
  "message": "success",
  "data": {
    "identity": {
      "exists": false
    },
    "eligibility": {
      "current_amount": 216.3,
      "personal_required_amount": 200,
      "company_required_amount": 500,
      "personal_eligible": true,
      "company_eligible": false
    },
    "stats": {
      "authorized_song_count": 0,
      "certificate_count": 0
    }
  }
}

0.2 ربط هوية الترخيص

نقطة النهاية: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "محمد أحمد",
  "id_number": "110101199001010000",
  "contact_name": "محمد أحمد",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "شارع الملك فهد، الرياض",
  "confirm_locked": true
}

يعيد الرد معلومات الهوية المُقنّعة: {"identity": {...}}. وبعد نجاح الربط، تحقق عبر واجهة context من أن identity.exists أصبحت true، ثم استدعِ قائمة الأغاني وواجهات الإصدار. وإذا لزم تغيير معلومات الهوية فتواصل مع خدمة العملاء.

1. حصر الأغاني القابلة للترخيص

نقطة النهاية: GET /api/music/authorization/songs

معاملات الاستعلام

مثال الطلب

curl "https://www.suno-api.io/api/music/authorization/songs?p=1&page_size=20&status=selectable" \
  -H "Authorization: Bearer YOUR_API_KEY"

مثال الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "أغنية مثال",
        "generation_type": "generate",
        "completed_at": 1784000000,
        "created_at": 1783999000,
        "audio_url": "https://example.com/audio.mp3",
        "model_name": "suno-v6",
        "authorization": {
          "selectable": true
        }
      }
    ]
  }
}

عند authorization.selectable=false يوضّح الرد السبب عبر reason_code وreason. أما الأغاني التي صدرت لها شهادة فتعيد أيضاً certificate_id وcertificate_no.

2. إنشاء الشهادة

نقطة النهاية: POST /api/music/authorization/certificates

معاملات جسم الطلب

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/authorization/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["suno-song-id-1", "suno-song-id-2"],
    "confirm_risk_terms": true
  }'

مثال الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "certificate": {
      "id": 101,
      "certificate_no": "CERTIFICATE-NO",
      "verification_code": "VERIFY-CODE",
      "status": "issued",
      "song_count": 2,
      "identity_type_snapshot": "personal",
      "licensee_name_masked": "م*",
      "document_no_masked_snapshot": "11**************34",
      "phone_masked_snapshot": "138****0000",
      "pdf_sha256": "PDF_SHA256",
      "issued_at": 1784000100,
      "created_at": 1784000000,
      "updated_at": 1784000100,
      "download_url": "/api/music/authorization/certificates/101/download",
      "songs": []
    }
  }
}

في الرد الناجح تكون status هي issued. وإذا فشل توليد PDF تُوسم الشهادة بـ failed، ويمكن إعادة إرسال الأغاني المعنية بعد إصلاح المشكلة.

3. الاستعلام عن سجل الشهادات

نقطة النهاية: GET /api/music/authorization/certificates

معاملات الاستعلام

مثال الطلب

curl "https://www.suno-api.io/api/music/authorization/certificates?p=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

بنية الاستجابة

data في الرد كائن مُقسّم إلى صفحات يتضمّن page وpage_size وtotal وitems. وكل عنصر في items ملخّص للشهادة ويتضمّن لقطة أغاني تلك الشهادة.

4. الاستعلام عن تفاصيل الشهادة

نقطة النهاية: GET /api/music/authorization/certificates/:id

المعامل id في المسار هو المعرّف الرقمي للشهادة. ولا تسمح الواجهة بالوصول إلا إلى شهادات المستخدم صاحب مفتاح API الحالي.

مثال الطلب

curl https://www.suno-api.io/api/music/authorization/certificates/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

بنية الاستجابة

عند النجاح يعيد data.certificate، وتشمل حقوله رقم الشهادة والحالة ومعلومات المرخّص له المُقنّعة ووقت الإصدار وقيمة تحقق PDF وعنوان التنزيل ولقطة الأغاني المرخّصة.

5. تنزيل PDF الشهادة

نقطة النهاية: GET /api/music/authorization/certificates/:id/download

لا يمكن تنزيل إلا الشهادات التي حالتها issued. ويظل طلب التنزيل بحاجة إلى مفتاح API صالح، ولا يمكن تنزيل إلا شهاداتك الخاصة.

مثال الطلب

curl https://www.suno-api.io/api/music/authorization/certificates/101/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output authorization-certificate.pdf

الاستجابة الناجحة هي تدفق ملف application/pdf، ويأتي اسم الملف وفق Content-Disposition من الخادم.

أسباب الفشل الشائعة

ملاحظات

• استخدم suno_song_id الذي تعيده قائمة الأغاني، ولا تستخدم معرّفات pending:* البديلة أو معرّفات جدول المهام.
• عنوان التنزيل ليس رابطاً عاماً؛ فلا تُزل المصادقة بمفتاح API.
• سجلات الشهادات تخص المستخدم المقابل لمفتاح API، ولا يمكن الاستعلام عنها أو تنزيلها بين مستخدمين مختلفين.
• نطاق الترخيص وبنود القيود ومحتوى PDF النهائي تخضع للشهادة الصادرة فعلاً.