البدء السريع

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

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

النموذج الافتراضي الحالي هو suno-v6. أما نماذج الإنشاء من suno-v2 إلى suno-v5-5 فقد أُوقفت: قد تظهر في المهام القديمة لكنها لا تقبل طلبات جديدة.

نزّل وثبّت واضبط suno-api agent kit من هذا العنوان  https://www.suno-api.io/suno-agent-kit.zip

الربط الموصى به: اترك الذكاء الاصطناعي يكمل الإعداد

سيقرأ الذكاء الاصطناعي ملف 00_START_HERE.md ويساعد في التسجيل وحفظ API Key وفحص الرصيد وتعريف الميزات وأول عملية إنشاء. تؤكد العمليات المدفوعة قبل التنفيذ، ولا يعاد إرسال المهلة تلقائيًا.

الخطوة 1: احصل على مفتاح API

1. افتح https://www.suno-api.io.
2. اضغط احصل على مفتاح API ثم سجّل. يكفي البريد الإلكتروني، دون رقم هاتف.
3. في لوحة التحكم، افتح إدارة الرموز وأنشئ مفتاحًا.
4. انسخه فورًا، فالمفتاح يظهر مرة واحدة فقط. اشحن الرصيد بكود تفعيل قبل أول طلب مدفوع.

الخطوة 2: اضبط الطلب

تستخدم كل الطلبات عنوان الأساس نفسه والترويسات نفسها:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

الخطوة 3: أرسل أول طلب

المثال 1 — الإنشاء من وصف

صِف الموسيقى، وسيكتب الـ API الكلمات واللحن والتوزيع:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "أغنية فولك مبهجة عن أول يوم من الربيع",
    "model": "suno-v6"
  }'

الاستجابة:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "حكاية الربيع",
    "description": "أغنية فولك مبهجة عن أول يوم من الربيع",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "خطوات الربيع",
    "description": "أغنية فولك مبهجة عن أول يوم من الربيع",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

كل تشغيل يعيد نسختين مختلفتين لتختار بينهما. تكلفة الإنشاء الواحد 0,6 ¥.

المثال 2 — متابعة التقدم

أرسل قيم song_id التي استلمتها إلى نقطة الاستعلام:

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

أثناء تنفيذ المهمة:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "حكاية الربيع",
    "progress": "60%"
  }
]

وعند الانتهاء:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "حكاية الربيع",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

يمر status بالقيم pending ثم submitted ثم processing وينتهي عند completed. قد تبقى العناوين فارغة أثناء التنفيذ، فاعتمد على status لا على وجود audio_url.

الخطوة 4: نزّل الملف

عندما يصبح status مساويًا completed اطلب audio_url مباشرة. التنزيل بصيغة MP3 و WAV غير محدود ولا يضيف تكلفة. إذا احتجت صوتًا بلا فقدان للمونتاج فاستخدم نقطة WAV.

سيناريوهات شائعة

موسيقى خلفية لفيديو

{
  "description": "خلفية lo-fi هادئة لفيديو منتج، بلا غناء، بديناميكية ثابتة",
  "instrumental": true,
  "model": "suno-v6"
}

عند ضبط instrumental على true لن تحتوي النتيجة على غناء.

كلمات ونمط خاص بك

{
  "lyrics": "[Verse 1]\nأضواء المدينة تخفت ببطء\n\n[Chorus]\nنمضي قدمًا",
  "style": "acoustic pop, غناء نسائي دافئ, 92 BPM",
  "model": "suno-v6"
}

الاستعلام حتى الانتهاء

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "أغنية فولك مبهجة عن الربيع", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

معالجة الأخطاء

أهم الرموز

صيغة الخطأ

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

أوقات الانتظار والمهلات (مهم): نقاط نهاية التوليد متزامنة — لا يُقبل الطلب ويُسلَّم إلى التوليد إلا عند وصول الاستجابة. ووفق القياس، تعود معظم الطلبات في 1-3 ثوانٍ، ونحو 10% تتجاوز 30 ثانية، وأطولها نحو 230 ثانية. اضبط مهلة العميل على 300 ثانية أو أكثر (--max-time 300 في المثال)؛ وعدم وصول استجابة لا يعني عدم التوليد، ولا تُعد المحاولة فوراً بعد انتهاء المهلة (فذلك يكرر الطلب ويخصم مرة أخرى). وإن انقطع الاتصال فتحقق لاحقاً عبر GET /api/music/songs. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

أفضل الممارسات

• احفظ المفتاح على الخادم، ولا تضعه في المتصفح أو التطبيقات الموزَّعة.
• استعلم كل 10–15 ثانية بدل حلقة متلاحقة.
• احتفظ بقيم song_id، فهي المعرّف الوحيد لاسترجاع الصوت لاحقًا.
• أعد الإرسال عند 429 و500، وعالج السبب أولًا قبل الإعادة عند 400 و401.
• عمليات الإنشاء الفاشلة تُرد تلقائيًا، لذا لا تكلفك المهمة الفاشلة شيئًا.
• مهلة العميل: لا تُعد نقطة نهاية التوليد مقبولة إلا عند وصول الاستجابة؛ اضبط المهلة على 300 ثانية أو أكثر.
• إعادة المحاولة: أعد المحاولة فقط عند فشل واضح (4xx/5xx). وبعد انتهاء المهلة أو انقطاع الاتصال، تحقق أولاً عبر GET /api/music/songs هل قُبل الطلب، لتجنب تكرار الطلب والخصم مرتين.

الخطوات التالية

• المصادقة — المفاتيح والأخطاء والحدود
• النماذج المدعومة — أسماء النماذج وفصل المسارات والنماذج الموقوفة