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

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

تغطي هذه الصفحة ثلاث نقاط نهاية مجانية للاستعلام:

إذا استخدمت وضع إيصال القبول (accept_mode=async) على نقطة نهاية إنشاء، فإن ما تملكه رقم إيصال لا معرّف أغنية. تابع التقدم عبر GET /api/music/requests/{request_id} ثم عُد إلى نقاط النهاية في هذه الصفحة بعد الحصول على song_id الحقيقي. راجع "وضع إيصال القبول" في واجهة التوليد بالوضع المبسّط.

المصادقة ونطاق البيانات

تستخدم نقاط النهاية الثلاث المفتاح نفسه:

Authorization: Bearer YOUR_API_KEY

سجل الأغاني معزول حسب user_id الذي ينتمي إليه مفتاح API. وعدة مفاتيح أُنشئت تحت الحساب الرئيسي نفسه يمكنها قراءة سجل ذلك الحساب، لكنها لا تستطيع قراءة أغاني مستخدم آخر أو حساب موقع فرعي آخر.

لا تُعيد نقاط نهاية السجل إلا الأغاني المُولَّدة فعلاً. وهي لا تشمل:

• سجلات الحجز المؤقت للتوليد التي تبدأ بـ pending:؛
• رفع الصوت المصدر وسجلات الرفع المعزّز؛
• النتائج الفرعية مثل فصل الغناء/الموسيقى والمسارات؛
• أغاني مستخدمين آخرين أو حسابات المواقع الفرعية.

1. استعلام حالة التوليد

يُستخدم لمعرفة الحالة الحالية والنتيجة النهائية لمعرّف أغنية واحد أو أكثر.

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

الفوترة: مجاني.

Headers

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

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

[
  {
    "song_id": "clip_id_1",
    "song_title": "عنوان الأغنية",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "نص الكلمات",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

ملاحظات التوافق

قد تعرض الوثائق القديمة song_ids كمصفوفة. والتوصية اليوم هي سلسلة مفصولة بفواصل، وهو ما يطابق طريقة استدعاء نقطة النهاية فعلياً.

يجب أن يحمل song_ids معرّفات أغانٍ حقيقية. فالمعرّف الذي يبدأ بـ pending: ليس song_id نهائياً ولا يمكن استخدامه هنا؛ واستعلام المعرّفات المؤقتة وحدها قد يعيد مصفوفة فارغة [].

قد تحتفظ قيمة model أو model_version أو model_name الخاصة بالمنصة في الاستجابة بقيم تاريخية. وينبغي للمهام الجديدة استخدام suno-v6 أو suno-v6-wild أو suno-v6-mini؛ أما suno-v2 حتى suno-v5-5 فقد أُلغيت، وظهور تلك الأسماء في السجل لا يعني أنه يمكن إرسال النموذج بعد الآن.

ما دامت المهمة في حالة pending أو submitted أو processing فقد تكون audio_url و video_url و cover_url فارغة — وهذا طبيعي لمهمة لم تكتمل. لا تستنتج الفشل من فراغ العنوان وحده؛ اعتمد على status وأعد الاستعلام بعد اكتمال الحالة. وفقط عندما تكتمل الحالة وتبقى العناوين فارغة، يُستحسن التواصل مع الدعم مع إرفاق song_id.

⚠️ عناوين الملفات الصوتية تعيش 7 أيام — انقل ملفاتك في الوقت المناسب

audio_url و video_url (وأي عناوين وسائط أخرى مثل WAV) التي تُعيدها هذه النقطة تُقدَّم من التخزين الكائني للمنصة وتنتهي صلاحيتها افتراضياً بعد 7 أيام: تُعاد الملفات للتخزين الدوري ويعيد العنوان القديم 404.

• خلال هذه الأيام السبعة انقل الملفات إلى مخزنك الخاص؛ ولا تعتبر العنوان رابطاً طويل الأجل.
• العنوان المنتهي لا يحتاج إلى إعادة توليد الأغنية ولا يُحاسَب عليه مرة أخرى: استدعِ هذه النقطة (POST /api/music/query) مرة أخرى للحصول على عنوان جديد صالح لتلك الأغنية.

2. استعلام سجل أغاني الحساب

يسرد الأغاني التي أنشأها الحساب الرئيسي الذي ينتمي إليه مفتاح API الحالي. مناسب لبناء قائمة أغانيك أو منتقي أو صفحة سجل خاصة بك.

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

الفوترة: مجاني.

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

تُرتَّب النتائج تنازلياً حسب created_at ثم معرّف السجل الداخلي، بحيث يبقى ترتيب الصفحات مستقراً.

طريقة العثور على إرسال انتهت مهلته: نقاط نهاية التوليد لا تُصدر استجابة وسيطة قبل القبول. فإذا انتهت مهلة عميلك أو انقطع الاتصال أثناء الإرسال، فقد يكون الطلب قد قُبل وهو قيد التوليد. ألقِ نظرة على هذه النقطة (الأحدث أولاً): الأغاني المقبولة تظهر في القائمة بشكل طبيعي. ولا تُعد الإرسال إلا بعد التأكد من غيابها فعلاً، حتى لا تدفع مرتين. راجع "أوقات الانتظار وإعدادات المهلة" في نظرة عامة على الواجهة الجديدة.

مثال الطلب

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

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

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "مدينة في الليل",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

حقول الاستجابة

لا تُعيد نقطة القائمة البرومبتات ولا حقول الفوترة ولا معلومات الحساب ولا الاستجابات الخام. وللحصول على البرومبتات ومعاملات التوليد، استدعِ نقطة تفاصيل الأغنية.

3. استعلام معاملات التوليد

يبحث عن البرومبت والأسلوب والنموذج والأغنية المصدر التي حفظتها المنصة عند توليد الأغنية.

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

الفوترة: مجاني.

لا يمكن قراءة إلا أغاني الحساب الرئيسي الذي ينتمي إليه مفتاح API الحالي. أما أغاني المستخدمين الآخرين أو حسابات المواقع الفرعية فتُعامَل دائماً على أنها "الأغنية غير موجودة".

معامل المسار

مثال الطلب

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "مدينة في الليل",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "شوارع مدينة بعد المطر، كلمات عن لقاء من جديد",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "مدينة في الليل",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

حقول parameters

حقل prompt_view (عرض البرومبت، أُضيف في 2026-09-28)

prompt_view بنية مُوحَّدة مخصّصة لعرض البرومبت: تنظّم البيانات في أقسام ثابتة حسب نوع التوليد، فلا يحتاج العميل إلى تحديد أي حقل يعرضه. وهو حقل إضافي بحت — الحقول القديمة (parameters و parameter_retention) تحتفظ بالاسم والمعنى، والعملاء الذين لا يحلّلون الحقل الجديد لا يتأثرون إطلاقاً.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "الوضع المتقدم",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "الرابعة فجراً#701f37", "title_base": "الرابعة فجراً", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "…", "user_text_kind": "lyrics",
    "user_style": "إلكتروني غوتشاو، بيس عميق، سينث رجعي",
    "style_tags": "إلكتروني غوتشاو، بيس عميق، سينث رجعي",
    "style_source": "user", "lyrics": "…",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

الحقول التي قد تظهر في extended: vocal_gender و style_weight و audio_weight و weirdness_constraint و variety و lyrics_mode و custom_mode، إضافة إلى مجموعة المؤثرات الصوتية sound_type / sound_bpm / sound_key / sound_loop. ولا تُعاد القيم الفارغة إطلاقاً.

ثلاث قواعد للعرض (اتبعها بدل التخمين):

1. ميِّز مصدر الأسلوب: عند style_source=suno_derived اعرضه كـ "أسلوب (استنتجه Suno من وصفك)"، ولا تكتب "أسلوبك"؛
2. البرومبتات الداخلية لا تظهر أبداً: أنواع الكوفر الصوتي لا تُعيد إلا 【متطلبات الأسلوب】/【متطلبات الكوفر】 التي كتبها المستخدم؛ والبنية الثابتة التي نجمعها للنموذج لا تظهر في أي حقل (والبيانات التاريخية مُنقّاة بالطريقة ذاتها)؛
3. لا تخمّن المعاملات المحفوظة: إن لم تكن في extended فلم تُسجَّل حينها — استخدم retention لتفسير السبب.

ملاحظات حفظ المعاملات

يفصل parameter_retention بين "تمرير قيمة فارغة صراحةً" و"عدم حفظ الحقل تاريخياً":

• core_parameters_available: هل يوجد سجل مهمة الأغنية الرئيسي؛ ويكون عادة true في التفاصيل السليمة؛
• extended_parameters_available: هل وُجد سجل مهمة موسيقية موسّعة مرتبط؛
• sources: من أي جداول بيانات جاءت هذه الاستجابة؛
• unavailable_fields: حقول لا يمكن استرجاعها بموثوقية من البيانات التاريخية، وتُعاد بـ null داخل parameters.

الأغاني التاريخية العادية حفظت عادة البرومبت والأسلوب والعنوان الحالي والنموذج ونوع التوليد والأغنية المصدر، لكنها لم تحفظ كل المعاملات المتقدمة بشكل منفصل. ولا تخمّن المنصة القيم المفقودة من generation_type أبداً.

بعض مهام الموسيقى الموسّعة حفظت أيضاً البرومبت الأصلي والأسلوب والعنوان والنموذج، إضافة إلى custom_mode و negative_tags و vocal_gender و style_weight و weirdness_constraint. وحتى مع وجود سجل موسّع، قد تبقى instrumental و lyrics_mode و wait_audio غير قابلة للاسترجاع.

يمكن للمستخدم إعادة تسمية الأغاني لاحقاً. وعندما لا تحفظ مهمة تاريخية عادية عنواناً أصلياً منفصلاً، فقد يكون parameters.title هو العنوان الحالي؛ وعند وجود سجل مهمة موسّعة يُعطى الأولوية لعنوان التوليد الأصلي المحفوظ فيه.

غير موجودة أو بلا صلاحية

تستخدم أخطاء العمل مغلف استجابة موحّداً. وعندما لا توجد الأغنية أو لا تنتمي إلى الحساب الحالي:

{
  "success": false,
  "message": "song not found"
}

يُعاد خطأ العمل هذا حالياً مع HTTP 200، لذا احكم على النتيجة من الحقل success. أما مفتاح API المفقود أو غير الصالح أو المنتهي أو المُعطَّل فيُعيد HTTP 401.

ملاحظات أمنية

لا تُعيد نقاط نهاية السجل والتفاصيل أبداً:

• مفاتيح API أو معرّفات الرموز؛
• حقول الحصة أو الفوترة أو الاسترداد؛
• معلومات الحساب أو الاستجابات الخام؛
• مفاتيح التخزين الكائني الداخلية؛
• أخطاء المشرف أو أخطاء الموارد الداخلية.