【موصى به】 واجهة الملف الصوتي الشخصي

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

✅ نوصي بهذا المسار للتكاملات الجديدة. بحسب تقييمات فعلية من مستخدمين كثيرين، الأغاني المولَّدة عبر هذا المسار تحافظ على الصوت الأصلي بدرجة عالية: تصبح الأصوات في الملف النهائي أقرب إلى الشخص في النموذج الذي رفعته، لذلك هو المسار الذي نوصي به للعملاء حالياً.

للمقارنة: واجهة استنساخ الصوت والتوليد بصوت محدد السابقة ما زالت تعمل، لكن القائمة تضع عليها وسم «غير موصى به» ولم تعد موصى بها للتكاملات الجديدة.

• تاريخ المستند: 2026-09-26
• النطاق: إنشاء صوتك الخاص → استخدامه لعمل كوفر لأغنية محددة / غناء أغنية جديدة → متابعة التقدّم → تنزيل الناتج
• جميع نقاط النهاية والحقول والاستجابات تحقّقت بنداءات حقيقية (ما وُسم بـ«مقيس» تم التحقق منه بالتفصيل)

ملاحظة: هذا المستند يشرح فقط نقاط النهاية التي تستدعيها. معالجة المواد وجدولة المهام وفحص المحتوى يقوم بها الخادم تلقائياً؛ العميل لا ينفذها.

0. البدء في خمس دقائق

أربع خطوات تكفي لتحويل نموذج صوتي واحد إلى أغنيتين جاهزتين.

① إنشاء الصوت   POST /api/music/voice-profile/create      → احصل على voice_id (status=ready)
② عمل كوفر      POST /api/music/voice-profile/cover       → احصل فوراً على song_id اثنين
③ المتابعة      POST /api/music/query                     → استعلم حتى status=completed
④ التنزيل       GET  /api/music/download?song_id=…&kind=mp3

أصغر مثال عامل (curl):

API_KEY="sk-مفتاحك"
BASE="https://www.suno-api.io"

# ① إنشاء الصوت (ارفع نموذجاً صوتياً؛ يُفضَّل 10 ثوانٍ أو أكثر، أقل من 10 ميجابايت)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=صوتي" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② اعمل كوفر لأغنية بهذا الصوت (song_clip_id = معرّف clip للأغنية المطلوب كوفرها)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nنص الكلمات…",
        "style_requirements": "فولك بطيء، جيتار أكوستيك",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ الاستعلام (أرسل عدة معرّفات مرة واحدة، مفصولة بفواصل)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ نزّل mp3 بعد الانتهاء (الملف متاح فقط عند status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. الأعراف المشتركة

1.1 النطاق والبيئة

كل المسارات أدناه نسبية بالنسبة إلى Base URL؛ مثلاً العنوان الكامل لـ POST /api/music/voice-profile/create هو https://www.suno-api.io/api/music/voice-profile/create.

1.2 المصادقة

كل نقاط النهاية تستخدم الترويسة نفسها، وقيمتها مفتاح API الذي أنشأته في لوحة التحكم:

Authorization: Bearer sk-xxxxxxxx

• بادئة Bearer اختيارية، وبادئة sk- كذلك (Authorization: sk-xxx يعمل أيضاً).
• المفتاح مفقود أو غير صالح → HTTP 401، والجسم بالشكل {"success":false,"message":"…"} (النص يتغيّر حسب لغة الطلب).
• كل مفتاح يرى ويعالج فقط أغاني وصوت حسابه هو.

1.3 صيغ جسم الطلب

• إنشاء صوت: يُفضَّل multipart/form-data (رفع ملف)؛ ويدعم application/json (رابط أو base64).
• بقية نقاط النهاية: application/json.

1.4 غلافا الاستجابة (على العميل معرفة هذين فقط)

نقاط نهاية «إدارة الأصوات» (create / create-from-clip / list / detail / delete) تستخدم غلاف الأعمال:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

«الكوفر بالصوت» يمر عبر قناة التوليد ويستخدم غلاف التوليد: النجاح code/message/data، والفشل كائن error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

كيف تقرر: انظر أولاً إلى رمز حالة HTTP، ثم success === false، وأخيراً code !== 200 أو وجود error. فشل العمل لا يضمن أن يكون HTTP غير 200 (نقاط إدارة الأصوات ترد HTTP 200 حتى عند الخطأ)، لذلك لا تعتمد على رمز الحالة وحده.

1.5 منع التكرار (idempotency)

إنشاء الصوت (بما في ذلك «الإنشاء من صوت موجود») تكراره آمن فعلاً: تحت المفتاح نفسه، إعادة إرسال client_request_id نفسه تنشئ صوتاً واحداً فقط، والمحاولة الثانية تعيد نتيجة الأولى مباشرة (success=true، وvoice_id نفسه). الطريقة المقصودة أن يولّد العميل معرّفاً بنفسه (مثل UUID) ويعيد استخدام القيمة نفسها عند إعادة المحاولة بعد انتهاء المهلة.

إرسال الكوفر لا يزيل التكرار على مستوى الطلب (فهو توليد مدفوع)، لذا انتبه لأمرين:

1. معرّف الإرسال يوضع في الترويسة X-Create-Ui-Client-Request-Id: <معرّف إرسالك>. يُكتب في سجل المهمة على الخادم لتسهيل الفحص لاحقاً؛ لكنه لا يمنع خصماً مكرراً.
2. انتهاء المهلة ≠ فشل: قد يكون الطلب قُبل فعلاً ويجري التوليد. قبل إعادة المحاولة افحص بـ GET /api/music/songs?p=1&page_size=20 (معاملات الترقيم p / page_size، والصيغة المتوافقة ps تعمل أيضاً) هل ظهرت أغنية جديدة بـ generation_type=voice_profile_cover، وأعد الإرسال فقط إن لم تظهر.

جسم create وcreate-from-clip يقبل أيضاً الحقل client_request_id (انظر §3 و§4).

1.6 نظرة عامة على الفوترة

يمكن قراءة الأسعار في أي وقت من نقطة نهاية عامة، فلا تكتبها ثابتة (انظر §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← السعر الأساسي للكوفر بالصوت
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← سعر الاستنساخ المعزّز
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

الكوفر يعمل بنمط خصم مسبق + إعادة المبلغ عند الفشل:

• الطلب المرفوض (معاملات خاطئة، أو 4xx/5xx من المنصة، أو الرصيد غير الكافي في ذاته) لا يُخصم منه — وعند الإرسال بصوت غير موجود لم يتغيّر الرصيد إطلاقاً في قياساتنا (delta = 0)؛
• المهمة المقبولة التي تفشل في النهاية (بما في ذلك خلل خدمة المنصة) تمر عبر مسار الإرجاع على الخادم وتعيد المبلغ المخصوم مسبقاً.

1.7 قاموس الحالات

status الخاصة بالصوت:

status الخاصة بالأغنية (القيمة التي تعيدها نقاط الاستعلام):

2. نظرة عامة على نقاط النهاية

3. إنشاء صوت

POST /api/music/voice-profile/create

سجّل مقطعاً صوتياً غنائياً كـ«صوت» واحصل على voice_id. بالنسبة للمنصة، الصوت ليس إلا «ملف صوتي + معرّف clip له في المكتبة»، لذلك بعد نجاح الإنشاء يبقى ملف الصوت المصدر محفوظاً بشكل دائم (لاستخدامه في الكوفرات اللاحقة).

3.1 ثلاث صيغ للإدخال (اختر واحدة)

الصيغة أ: رفع ملف multipart (موصى بها)

Content-Type: multipart/form-data

file=<بيانات الصوت الثنائية>   # إلزامي
title=<اسم الصوت>              # اختياري؛ إن كان فارغاً يُستخدم اسم الملف دون الامتداد
file_name=<اسم الملف الأصلي>
source_file_name=<اسم الملف الأصلي>
source_kind=upload|record      # اختياري، علامة المصدر (رفع / تسجيل)؛ الافتراضي upload
enhanced=false|true            # اختياري، true = الاستنساخ المعزّز (انظر §3.5)
client_request_id=<مفتاح منع التكرار>   # اختياري
voice_id=<معرّف خاص>           # اختياري، نادر الاستخدام

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=صوتي" \
  -F "source_kind=upload"

الصيغة ب: JSON + رابط صوت عام

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "صوتي"
      }'

• يجب أن يكون الرابط مباشراً عبر HTTPS ومتاحاً للعامة؛ ينزّله الخادم مرة واحدة وينقله إلى تخزين الكائنات لدينا.
• يمكن أيضاً وضع العنوان في الحقل audio_url والنتيجة نفسها (عند إرسال الاثنين يُعتمد file_url).
• إذا كان العنوان موجوداً أصلاً في تخزين كائنات هذه المنصة (*.myqcloud.com/create-ui/voice-source/...) فلا يُنزَّل مرة أخرى: يُسجَّل مباشرة.

الصيغة ج: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "صوتي"
}

• يدعم البادئة data:audio/xxx;base64, و base64 الخالص.
• الحجم محدود (base64 يضخّم 1.33 مرة)، للملفات الكبيرة استخدم الصيغة أ.

3.2 متطلبات الصوت

3.3 الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "صوتي",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

شرح الحقول (create / list / detail تشترك في المجموعة نفسها):

created_at / updated_at طوابع زمنية بمستوى الثانية (10 أرقام)، لا بالميلي ثانية.

3.4 أخطاء شائعة

3.5 الاستنساخ المعزّز (enhanced=true)

لحالات «النموذج الصوتي نفسه يحمل كلمات محمية بحقوق النشر / يلزم رفع معزّز». السعر سعر الرفع المعزّز (افتراضياً 10 يوان لكل طلب، ويُرد تلقائياً عند الفشل):

• الاستجابة تكون فوراً status=processing + task_id (بلا clip_id بعد) وتعمل بشكل غير متزامن؛
• أثناء المعالجة تابع بـ GET /api/music/voice-profile/{voice_id} الذي يعيد progress_percent / progress_stage / progress_message؛
• عند الانتهاء يصبح status هو ready وتُكمل clip_id وaudio_url وimage_url؛
• عند الفشل يصبح status=failed ويكون error_message نحو «فشل الرفع المعزّز؛ أُعيد المبلغ تلقائياً، أعد المحاولة لاحقاً»؛
• الاستنساخ المعزّز أطول بوضوح من الإنشاء العادي (دقائق)، فلا تنتظره بمنطق مهلة متزامن.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=صوتي" -F "enhanced=true"

4. إنشاء صوت من ملف صوتي موجود

إن لم ترغب في الرفع مرة أخرى: انسخ مباشرة ملفاً صوتياً رفعته سابقاً أو ولّدته سابقاً إلى صوت. مجاني ومنع تكراره آمن.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: معرّف clip لملف صوتي منتهٍ في حسابك (مثل song_id للأغنية).
• إعادة إرسال clip نفسه لا تنشئ سجلاً جديداً: يُعاد الصوت الموجود مباشرة مع reused: true (مقيس).

الاستجابة كل حقول §3.3 مع حقلي قراءة فقط:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

الأخطاء (message كما تُعاد؛ يُفضَّل عرضها أو ترجمتها):

5. القائمة / التفاصيل / الحذف

5.1 القائمة

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "صوتي", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

الحقول مطابقة تماماً §3.3. لا تُعاد الأصوات المحذوفة افتراضياً.

5.2 التفاصيل

GET /api/music/voice-profile/{voice_id}

تعيد كائن صوت واحداً (data هو الكائن نفسه لا مصفوفة). وأثناء عمل الاستنساخ المعزّز تُضاف:

5.3 الحذف

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• بعد الحذف يختفي الصوت من القائمة ولا يمكن استخدامه في كوفرات جديدة: الإرسال بـ voice_id نفسه يعيد 400 (انظر §6.4).
• الأغاني التي أُنتجت به سابقاً لا تتأثر إطلاقاً؛ التشغيل والتنزيل والاستكمال والاستبدال وفصل المسارات تعمل كما هي.
• حذف صوت غير موجود، أو لا يخص هذا الحساب، يعيد {"success":false,"message":"voice not found"}.

6. الكوفر بالصوت (نقطة النهاية المحورية)

POST /api/music/voice-profile/cover
Content-Type: application/json

إرسال واحد يولّد أغنيتين (مثل التوليد العادي).

6.1 سيناريوهان

يعكس resolved_scene في الاستجابة قيمة cover أو sing، فتعرف أي مسار سُلك.

6.2 حقول الطلب

يُفضَّل إرسال الترويسة X-Create-Ui-Client-Request-Id: <المعرّف نفسه> أيضاً: فهي وحدها تُكتب في سجل المهمة على الخادم وتكون مفتاحاً أساسياً للفحص لاحقاً (انظر §1.5).

تنبيه على الوحدات: audio_weight / style_weight / weirdness_constraint كسور من 0 إلى 1، وvariety عدد صحيح من 0 إلى 4، وduration بالـثواني. الخلط بينها يؤدي إلى الرفض أو نتائج غريبة.

الكلمات اختيارية في السيناريو ب (النموذج يتولى الأمر)، لكن أرسل lyrics دائماً عندما تريد غناء محتوى معين.

6.3 الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[مهمة] هذا كوفر. … (الجزء البنيوي الثابت من الخادم + متطلبات الكوفر / الأسلوب التي أدخلتها)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

النقاط المهمة:

1. حدّد النواتج النهائية عبر clips[].song_id (هذه النقطة لا تعيد الحقل id).
2. تحصل فوراً على قيمتَي song_id، وstatus ما زال processing (يعني القبول فقط) وaudio_url فارغاً؛ ولا بد من الاستعلام حتى completed قبل التنزيل. أما play_url فهو بث المعاينة من المنصة، وقد يظهر من مرحلة الإرسال وسينتهي.
3. description هو الـ prompt الذي يرسله الخادم في النهاية (الجزء البنيوي الثابت + ما أدخلته في cover_requirements / style_requirements)؛ ومفيد جداً عند تحليل النواتج.
4. source_updates نتيجة معالجة المواد على الخادم، ويمكن للعميل تجاهلها.
5. title الذي ترسله يُكتب في سجل المهمة على الخادم ويظهر كـ song_title في الاستعلامات اللاحقة؛ وكون clips[].song_title فارغاً في ردّ الإرسال أمر طبيعي.

6.4 الأخطاء

{ "error": { "message": "هذا الصوت غير موجود أو تم حذفه (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

قلة الرصيد تُعيد خطأ فوترة مباشرة عند الإرسال ولا تترك مهمة نصف منتهية.

6.5 النماذج المتاحة (أسماء العملاء)

استخدم أسماء النماذج المخصّصة للعملاء (الواردة أعلاه). أما chirp-* فهي أسماء داخلية للمنصة ولا تُستخدم مباشرة.

7. متابعة التقدّم

7.1 استعلام دفعة واحدة (موصى به)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids سلسلة مفصولة بفواصل (ليست مصفوفة).
• الاستجابة مصفوفة مجرّدة (تبدأ بـ [...] مباشرة، بلا غلاف success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "نمران",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[مهمة] هذا كوفر. … (prompt الخادم النهائي)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

توصية الاستعلام: كل 5–10 ثوانٍ، بمهلة إجمالية 10–15 دقيقة (أبطأ حساب «بارد» في القياسات استغرق نحو 4.5 دقيقة؛ وقليل جداً أكثر). لا تحكم على الانتهاء من فراغ audio_url، بل من status.

ملاحظة توافق: هذه النقطة تعرّف الأغاني بـ song_id؛ وقد ظهر الحقل id في بعض الاستجابات المبكرة، لذا row.song_id || row.id هي القراءة الآمنة.

7.2 تفاصيل أغنية واحدة

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "نمران",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "نمران",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• هنا created_at / completed_at بـثواني Unix (بخلاف سلاسل ISO في الاستعلام الجماعي، فعلى العميل التفريق).
• wav_url / video_url هما مدخلا التنزيل في هذه المنصة (نسبيان للنطاق الحالي)، وGET يجلب الملف؛ وهما سلسلتان فارغتان إن لم تُنتج المنصة ذلك الناتج.
• parameter_retention يوضح أي معاملات إرسال يمكن تتبّعها لهذه الأغنية: core_parameters_available=true يعني أن المعاملات الأساسية (الكلمات / الأسلوب / المصدر) قابلة للاستعلام، وعند extended_parameters_available=false تكون المعاملات الموسّعة المذكورة أعلاه غير محفوظة (والكوفرات بالصوت تقع حالياً في هذه الفئة).

7.3 أعمالي

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=كلمة مفتاحية

معاملات الترقيم: p (رقم الصفحة من 1) / page_size (عدد العناصر في الصفحة؛ والصيغة المتوافقة ps). واختياري status وq (كلمة مفتاحية في العنوان). الترتيب الافتراضي بحسب زمن الإنشاء تنازلياً.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "نمران",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

بواسطة generation_type=voice_profile_cover تميّز «الأغاني الناتجة من كوفر بالصوت» عن بقية نتائج التوليد.

8. تنزيل النواتج

8.1 أخذ mp3 مباشرة (موصى به، مجاني)

كل الطرق الثلاث تعمل؛ اختر واحدة:

1. استخدم audio_url من نتيجة الاستعلام (رابط مباشر إلى تخزين الكائنات، الأسهل).
2. GET /api/music/download?song_id=<id>&kind=mp3 → يعيد بث بايتات الصوت مباشرة (واسم الملف موجود في Content-Disposition).
3. POST /api/music/download-url (للحصول على عنوان مؤقت موقّع).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

قيم kind: mp3 (مكافئ لـ song) / playback (تشغيل بثّي) / wav / video / lyrics / timestamped_lyrics. وtimestamped_lyrics (.lrc) متاح حالياً لبعض الأغاني فقط؛ وعند فشله أنشئ الملف بنفسك عبر واجهة الكلمات بمُهر زمني. الاستجابة هي بث بايتات الملف كما هو، وContent-Type وContent-Disposition (اسم الملف) مضبوطان؛ أما wav_url / video_url التي يعيدها GET /api/music/songs/{song_id} فهي المدخل نفسه مع kind=wav|video.

8.2 تحويل إلى wav / كلمات / بيانات وصفية (مدفوع)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files يقبل: mp3 / wav / lyrics / metadata، وبحد أقصى 10 أغانٍ في المرة.
• الفوترة بحسب عدد الأغاني الناجحة (0.2 يوان للأغنية)؛ والأغنية الفاشلة كلياً لا تُحاسَب، والصيغة الفاشلة تظهر فقط في songs[].errors.
• لإعادة الحصول على ملفات سبق تنزيلها، استخدم أولاً المجاني POST /api/music/free2/cached (بالمعاملين نفسيهما song_ids + files) لجلب العناوين المؤرشفة؛ وsongs[].missing_files في ردّه يوضح الصيغ غير المخزّنة والتي تحتاج إعداداً جديداً.

9. استعلام الأسعار

GET /api/pricing/catalog

نقطة نهاية عامة لا تحتاج مصادقة. كل الأسعار التي يحتاج العميل عرضها في data.catalog.meta (سلاسل نصية):

تُعدَّل الأسعار في لوحة الإدارة، لذا اقرأها مباشرة ولا تكتبها ثابتة في العميل. والخصم الفعلي للكوفر = voice_generation_price × (وإذا كان max_mode صحيحاً يُضاف × max_mode_factor).

10. الحدود والتنبيهات

1. حجم الرفع: ≤ 10 ميجابايت (الخادم يقبل أكثر، لكن بوابة الدخول تقطع الأجسام الكبيرة عند 10 ميجابايت ثنائية وتظهر كأنها «مرفوضة من Suno»؛ فامنعها من جهتك أولاً).
2. مدة النموذج: 6 ثوانٍ على الأقل، ويُفضَّل 10–60 ثانية؛ وأقل من ذلك ترفضه المنصة.
3. محتوى النموذج: صوت غنائي نظيف؛ وتجنّب أي شيء يشبه تسجيلاً موجوداً (مقارنة المكتبة ترفضه).
4. حدود النصوص: lyrics ≤ 3000 حرف؛ ويُستحسن أن تبقى style_requirements / negative_tags / title ضمن 1000 / 1000 / 100 حرف (متطلبات الأسلوب والكوفر تُدمج في الـ prompt، فأبقِ الإجمالي ضمن 3000 حرف).
5. لا تُعاد كتابة الكلمات: ما ترسله هو ما يُغنّى (حرفاً بحرف) دون قطع محلي.
6. كل أغنية تُنتج نسختين؛ لا تفترض نتيجة واحدة.
7. الملف الصوتي المصدر محفوظ بشكل دائم: حذف الصوت لا يمسح ملف الصوت المصدر؛ وهذا يبقي الكوفرات اللاحقة ممكنة ويجعل الامتثال قابلاً للتتبّع.
8. يجب أن يكون الصوت ready: الصوت بحالة processing لا يصلح للكوفر.
9. مهلة الطلب: في حساب «بارد» استغرق أول إرسال في القياسات حتى نحو 4.5 دقيقة، فاضبط مهلة العميل على ≥ 6 دقائق. والكوفر لا يزيل التكرار على مستوى الطلب، لذا بعد انتهاء المهلة تحقق أولاً من عدم ظهور أغنية جديدة (§1.5) ثم قرر الإعادة.
10. ملكية الصوت: الأصوات تخص منشئها؛ والكوفر يقبل فقط الأصوات الجاهزة وغير المحذوفة. والصوت غير الموجود أو المحذوف أو التابع لحساب آخر يعيد 400: هذا الصوت غير موجود أو تم حذفه (voice_id=…).

11. الأسئلة الشائعة (FAQ)

س1. هل إنشاء الصوت مكلف؟ الإنشاء العادي و«الإنشاء من صوت موجود» مجانيان؛ ولا تُحاسَب إلا الكوفرات (1.2 يوان / MAX 2.4 يوان) والاستنساخ المعزّز (افتراضياً 10 يوان).

س2. هل يمكن استخدام أغنية نهائية بموسيقى مصاحبة كنموذج صوتي؟ غير موصى به. أي شيء يحتوي موسيقى أو يشبه جداً تسجيلاً موجوداً في المكتبة ترفضه المنصة (This audio matches an existing recording in our catalog.). استخدم تسجيلاً غنائياً خالصاً وجافاً.

س3. لماذا يكون audio_url فارغاً بعد إرسال الكوفر؟ الإرسال يعني القبول فقط وstatus ما زال processing. ويظهر عنوان قابل للتشغيل/التنزيل فقط بعد الاستعلام بـ /api/music/query حتى status=completed.

س4. هل أرسل الكلمات في السيناريو ب (بلا song_clip_id)؟ اختياري. أرسل lyrics لغناء محتوى محدد؛ وبدونه يتولى النموذج الأمر لكن بتحكّم أقل.

س5. هل يمكن استخدام ملف رفعه العميل كصوت مباشرة؟ نعم: عبر صيغة file_url في create، أو برفعه كأغنية أولاً ثم استدعاء create-from-clip.

س6. هل يُعاد المال عند الفشل؟ الطلب المرفوض مباشرة (معاملات خاطئة / خطأ من المنصة) لا يُخصم منه بحسب القياسات؛ والمهمة المقبولة التي تفشل في النهاية تعيد المبلغ المخصوم مسبقاً. وعند الفشل النهائي تُعيد المهمة status=failed مع error_message.

س7. بعد حذف الصوت، هل يمكن سماع الأغاني التي أُنتجت به؟ نعم. الحذف يؤثر فقط على إمكانية استخدام ذلك الصوت في كوفرات جديدة.

س8. ما أقصى طول أغنية يمكن كوفرها دفعة واحدة؟ duration يقبل من 1 إلى 480 ثانية؛ وإن لم ترسله تحدده المنصة بحسب الأغنية الأصلية / المادة. وانتبه: أقصر ناتج نهائي للمنصة نحو 30 ثانية؛ فالقيم الأصغر أعطت في القياسات 29.96 / 29.76 ثانية.

الملحق أ: مثال كامل (Node.js، مع الاستعلام والتنزيل)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① إنشاء الصوت (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② الكوفر
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "فولك بطيء، جيتار أكوستيك",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ الاستعلام حتى الانتهاء (كل 5 ثوانٍ، وبحد أقصى 15 دقيقة)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // مصفوفة مجرّدة
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ التنزيل
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "صوتي");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nكلمات…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

الملحق ب: سجل التغييرات