API گواهی مجوز تجاری موسیقی

به‌روزرسانی 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 تابع گواهی واقعاً صادرشده است.