واجهة استنساخ الصوت والتوليد بصوت محدد (غير موصى به)

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

⛔ مسار قديم، غير موصى به للتكاملات الجديدة. تصف هذه الصفحة مسار persona المبكر (voice_task_id / generate-with-voice). لا يزال يعمل، لكنه لم يعد موصى به للعملاء؛ وقد وُسم في القائمة على اليسار بأنه «غير موصى به».

للتكاملات الجديدة استخدم 【موصى به】 واجهة الملف الصوتي الشخصي: أنشئ ملفاً صوتياً شخصياً من عينة صوتية واحدة (POST /api/music/voice-profile/create)، ثم استخدمه لعمل كوفر لأغنية محددة أو لغناء أغنية جديدة. الملف الصوتي الشخصي مورد من الدرجة الأولى: يمكن سرده وقراءته وحذفه، ويُحفظ الصوت المصدر بشكل دائم.

إذا كان منتجك يحتاج الدورة الكاملة «إنشاء صوت → إعادة استخدام طويلة الأمد → كوفر»، فاختر المسار الجديد.

تنبيه مهم: قد ينتهي صلاحية الصوت المستنسخ.

إن voice_id / voice_task_id الناتجين عن استنساخ الصوت ليسا مورداً صالحاً للأبد؛ فقد يتوقفان عن العمل بسبب مدة الصلاحية أو حالة الحساب أو تغيّر حالة الصوت. على الجهة المتكاملة ألا تستنسخ مرة واحدة ثم تعيد استخدام معرّف صوت مخزَّن محلياً إلى الأبد.

الممارسة الموصى بها:

• احفظ voice_task_id وvoice_id وis_available وupdated_at ووقت آخر توليد ناجح.
• قبل كل توليد بصوت مستنسخ، استدعِ GET /api/voice/clone/tasks/{voice_task_id} أو POST /api/voice/clone/tasks/{voice_task_id}/check وأكّد أن is_available=true.
• إذا أعادت نقطة النهاية أن الصوت غير متاح أو أن المهمة غير موجودة أو selected voice is not ready، فاطلب من المستخدم إعادة الاستنساخ أو اختيار صوت آخر متاح.
• لا تَعِد المستخدم النهائي بأن الصوت المستنسخ «أصل دائم»؛ اعرض في واجهة المنتج أن «الصوت قد ينتهي صلاحيته ويحتاج إلى إعادة تحقق أو إعادة استنساخ».

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

تُنشئ هذه المجموعة صوتاً قابلاً لإعادة الاستخدام وتولّد أغاني به. لا يحتاج المستدعي إلا إلى مفتاح API الصادر من المنصة؛ ويتولى الخادم إرسال المهمة ومزامنة الحالة والفوترة والتنزيل.

المصادقة: Authorization: Bearer YOUR_API_KEY

الفوترة:

• التحقق من الصوت، واستنساخ الصوت، وطلب الحالة، والحذف، والتنزيل: مجاني.
• مدخل الاستنساخ بخطوة واحدة في مساحة العمل: 5 يوان ثابتة لكل طلب؛ يُكمل التحقق من الصوت المصدر وملف التحقق الثاني تلقائياً، ويُرد المبلغ عند الفشل.
• المتابعة تلقائياً إلى ملف التحقق الصوتي بعد استنساخ عادي: 5 يوان ثابتة لكل طلب؛ ويُرد المبلغ عند الفشل وفق المسار الحالي.
• توليد أغنية بصوت مستنسخ: مدفوع، 1.2 يوان ثابتة لكل طلب، وكل طلب يعيد عادة مهمتي حجز مؤقت.
• عند تشغيل Max Mode (max_mode: true في POST /api/music/generate-with-voice) تُحاسَب الـ 1.2 يوان لكل طلب بمضاعف 2، أي 2.4 يوان لكل طلب؛ ويدعم توليد الصوت أيضاً variety (من 0 إلى 4، دون رسوم إضافية)؛ وترد قواعد القيم في قسم «المعاملات المتقدمة» في نظرة عامة على الـ API الجديد.

تسلسل الاستدعاء

1. استدعِ POST /api/voice/clone/validate لرفع الصوت المصدر والحصول على voice_task_id.
2. انتظر أو استعلم GET /api/voice/clone/tasks/{voice_task_id} حتى تحصل على validate_info.
3. يقرأ المستخدم النص بصوت مرتفع ويسجّل ملف التحقق.
4. استدعِ POST /api/voice/clone/tasks/{voice_task_id}/generate لإرسال ملف التحقق.
5. استدعِ POST /api/voice/clone/tasks/{voice_task_id}/check أو واصل طلب المهمة حتى is_available=true.
6. استدعِ POST /api/music/generate-with-voice لتوليد أغنية بذلك الصوت.
7. تُعيد نقطة نهاية التوليد أولاً مهام حجز مؤقت؛ وبعد اكتمال التوليد والحصول على song_id الحقيقي، يمكنك استخدام نقاط نهاية التنزيل للحصول على ملف واحد أو حزمة.
8. (اختياري) عند عدم الحاجة إلى هذا الصوت، استدعِ DELETE /api/voice/clone/voices/{voice_task_id} لحذفه؛ والدلالة في القسم 6.

يوجد أيضاً استنساخ بخطوة واحدة: في أول صفحة لتسجيل/رفع الصوت المصدر في مساحة العمل يمكنك اختيار الإكمال بخطوة واحدة؛ وينجز النظام التحقق وإنشاء الصوت معاً، فلا تحتاج إلى تسجيل ملف تحقق ثانٍ؛ ويُحاسَب بـ 5 يوان لكل طلب ويُرد المبلغ عند الفشل.

حقول مهمة الصوت

1. إرسال الصوت المصدر للتحقق

نقطة النهاية: POST /api/voice/clone/validate

معاملات الطلب

يجب أن يستوفي vocal_end_s - vocal_start_s الحد الأدنى لطول المقطع الغنائي. ارفع تسجيلاً صوتياً واضحاً دون موسيقى مصاحبة أو ضجيج ظاهر.

مثال الطلب

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "صوتي النسائي الصيني",
    "description": "صوت نسائي صيني صافٍ وطبيعي",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

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

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "صوتي النسائي الصيني",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. طلب مهمة الصوت

نقطة النهاية: GET /api/voice/clone/tasks/{voice_task_id}

مثال الطلب

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "صوتي النسائي الصيني",
      "validate_info": "اقرأ بصوت مرتفع نص التحقق المُعاد هنا",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. إعادة توليد نص التحقق

نقطة النهاية: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

يُستدعى عندما لا يصلح نص التحقق للقراءة بصوت مرتفع أو عند الحاجة إلى إعادة التحقق.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. إرسال ملف التحقق وإنشاء الصوت

نقطة النهاية: POST /api/voice/clone/tasks/{voice_task_id}/generate

معاملات الطلب

مثال الطلب

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "صوتي النسائي الصيني"
  }'

5. التحقق من صلاحية الصوت

نقطة النهاية: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

عند صيرورة المهمة قابلة للاستخدام تكون قيمة is_available في الاستجابة true، ويُعاد voice_id.

6. حذف صوت

نقطة النهاية: DELETE /api/voice/clone/voices/{voice_task_id}

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

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

ما يحدث بعد الحذف

• لا يمكن استخدامه لتوليد أغانٍ جديدة: استدعاء POST /api/music/generate-with-voice بمعرّف voice_task_id هذا (أو بمعرّف voice_id الخاص به) يُرفض برسالة selected voice is not ready، دون أي خصم.
• الأغاني المُولَّدة به مسبقاً لا تتأثر إطلاقاً: التشغيل والتنزيل والإكمال والاستبدال وفصل المسارات تعمل كما هي.
• تختفي مهمة الصوت هذه من الاستعلامات: يُعيد GET /api/voice/clone/tasks/{voice_task_id} القيمة record not found.
• يُحفظ الصوت المصدر وفق سياسة الحفظ الدائم للمنصة (منذ 2026-09-23 لم يعد الحذف ينظّف العينة الصوتية التي رفعتها)، لكن هذا لا يعني إمكانية الاستعادة: المهمة القديمة انتهت، ولمواصلة استخدام الصوت نفسه يجب المرور بمسار الاستنساخ من جديد، وستحصل على voice_task_id جديد.
• الحذف المتكرر: حذف المهمة نفسها مرة أخرى يعيد record not found (فهي في حالة محذوفة ولا يمكن العثور عليها).

7. توليد أغنية بصوت مستنسخ

نقطة النهاية: POST /api/music/generate-with-voice

الفوترة: 1.2 يوان لكل طلب.

معاملات الطلب

النماذج المدعومة: suno-v6 وsuno-v6-wild وsuno-v6-mini؛ والنموذج الفارغ يُعالَج كـ suno-v6. وقد أُوقفت نماذج V5/V5.5 القديمة، لكن المهام التاريخية قد تعرض أسماء النماذج القديمة.

تُفسِّر بنية الطلب المشتركة أيضاً حقول توافق Create UI مثل task وsoundType وsoundLoop وsoundBpm وsoundKey وvoiceTaskId وvoiceId، لكنها ليست معاملات عميل صالحة لهذه الواجهة: إذ يجب إرسال مهمة الصوت عبر voice_task_id، والتحقق الاختياري من الصوت عبر voice_id، ولا يقرأ توليد الموسيقى بالصوت حقول sound إطلاقاً.

كيف تُملأ معاملات التوليد

• عند customMode=false يحمل prompt وصف الأغنية؛ وعند customMode=true يحمل prompt الكلمات كاملة، ويجب أيضاً ملء style وtitle. لا ترسل الكلمات إلى حقل الوصف في نمط الإلهام، ولا تعامل وصف الأغنية ككلمات في النمط المتقدم.
• weirdnessConstraint وstyleWeight نسب عشرية من 0.0 إلى 1.0؛ ولا يمكن إرسال 50 أو 50%. والقيمة 0.5 قيمة متوازنة؛ وحذفهما يعني «غير محدد»، بينما 0 قيمة صريحة صالحة.
• يقبل vocalGender القيم m وmale وf وfemale فقط. وinstrumental هنا مجرد حقل توافق: فالتوليد بالصوت المستنسخ يُعالَج دائماً كأغنية غنائية.
• لا يغيّر waitAudio السلوك هنا؛ إذ تعيد الواجهة دائماً مهام حجز مؤقت بشكل غير متزامن. وكون audio_url فارغاً في النتيجة الأولى أمر طبيعي: استعلم بـ client_request_id واقرأ عنوان الصوت بعد اكتمال النتيجة فقط.

معاملات الترويسة

سلوك Idempotency-Key:

• يكتب الطلب الأول سجل إزالة تكرار دائماً قبل الفوترة؛
• وإذا كان المفتاح نفسه مع الطلب نفسه قد اكتمل، تُعاد استجابة القبول الأولى دون خصم ثانٍ أو مهمة ثانية؛
• ويُرفض المفتاح نفسه مع جسم طلب مختلف؛
• ويعيد المفتاح نفسه وهو قيد المعالجة خطأ «قيد المعالجة» مستقراً، ولا يكشف client_request_id آمناً إلا بعد توليده؛
• وإذا فشل الطلب الأول بمفتاح معيّن يبقى في حالة فشل، ويتطلب إعادة المحاولة مفتاحاً جديداً.

شروط الكوفر عبر sourceClipId

يتولى الخادم بالكامل الكوفر من مصدر في واجهة العميل: فالخادم يحلّ الوصول إلى الأغنية المصدر، ولا يرسل العميل أي معلومات حساب. وتحدد الاستجابة الفعلية للواجهة إمكانية ذلك.

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "اكتب أغنية بوب صينية عن شاطئ البحر في ليلة صيفية",
    "style": "Mandopop, warm piano, emotional",
    "title": "نسيم البحر في ليلة صيفية",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

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

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "نسيم البحر في ليلة صيفية",
        "prompt": "اكتب أغنية بوب صينية عن شاطئ البحر في ليلة صيفية"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "نسيم البحر في ليلة صيفية",
        "prompt": "اكتب أغنية بوب صينية عن شاطئ البحر في ليلة صيفية"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

حول مهام الحجز المؤقت وsong_id النهائي

generate-with-voice واجهة توليد غير متزامنة. فالاستجابة الناجحة تعني فقط أن مهمة التوليد قد أُرسلت، وليس أن الأغنية اكتملت.

معنى الحقول المهمة في الاستجابة:

تنبيه: لا يصلح placeholder_id الذي يبدأ بـ pending: كـ song_id نهائي، ولا يمكن تمريره مباشرة إلى /api/music/query أو نقاط نهاية التنزيل. واستدعاء /api/music/query بقيم pending:* فقط قد يعيد مصفوفة فارغة []، لأن الأغنية الحقيقية لم تكتمل بعد أو لأن مهمة الحجز المؤقت لم تُستبدل بعد بمعرّف الأغنية النهائي.

مثال خاطئ:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

التسلسل الصحيح:

1. استدعِ POST /api/music/generate-with-voice لإرسال مهمة توليد الموسيقى بالصوت.
2. احفظ client_request_id وitems[].placeholder_id وitems[].client_request_index من الاستجابة.
3. استعلم بشكل متكرر GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. عندما تصبح لـ items[].song_id قيمة لا تبدأ بـ pending:، استدعِ /api/music/query أو /api/music/download-file أو /api/music/download-all.

يضيف الإصدار الحالي نقطة نهاية استعلام عامة:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

وهي تعيد نتائج المهام لنفس client_request_id تحت المستخدم الحالي، ليتمكن العميل من البحث بنفسه عن song_id النهائي. وفي القائمة المُعادة:

• song_id هو معرّف الأغنية الحقيقي؛
• ويظهر placeholder_id فقط ما دامت المهمة في حالة الحجز المؤقت؛
• ولا يمكن استخدام قيمة تبدأ بـ pending: مع /api/music/query أو نقاط نهاية التنزيل.

إذا حفظت فقط client_request_id أو معرّف حجز مؤقت pending:*، فاستدعِ نقطة نهاية النتائج أولاً؛ وإن لم تجد song_id الحقيقي بعد، فأرسل client_request_id إلى الدعم الفني للتعقّب.

استعلام نتائج توليد الموسيقى بالصوت

نقطة النهاية: GET /api/music/generate-with-voice/results

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

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

مثال الطلب

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

مثال استجابة أثناء التوليد

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "نسيم البحر في ليلة صيفية"
      }
    ]
  }
}

مثال استجابة بعد الاكتمال

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "نسيم البحر في ليلة صيفية",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

معنى status في المستوى الأعلى

8. تنزيل ملف واحد

نقطة النهاية: POST /api/music/download-file

معاملات الطلب

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

الاستجابة تدفّق ملف؛ ويتبع Content-Type واسم الملف ما يعيده الخادم الخلفي.

9. تنزيل موارد الأغنية كحزمة

نقطة النهاية: POST /api/music/download-all

معاملات الطلب

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

تحتوي الحزمة عادة على الصوت والغلاف وmetadata.json؛ وإذا لم يكن نوع مورد ما قد وُلّد بعد فلن يُضاف إلى الأرشيف.

أخطاء شائعة

أخطاء هذه المجموعة تعيد دائماً HTTP 200: فاحكم على النتيجة من حقل success في الجسم (false تعني الفشل، والسبب في message) ولا تنظر إلى رمز حالة HTTP وحده. والدلالة الكاملة لحذف الصوت (هل يبقى صالحاً للاستخدام، وهل يمكن استعادته) في القسم 6.