البدء السريع

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

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

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

الخطوة 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" \
  -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"
  }
}

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

• احفظ المفتاح على الخادم، ولا تضعه في المتصفح أو التطبيقات الموزَّعة.
• استعلم كل 10–15 ثانية بدل حلقة متلاحقة.
• احتفظ بقيم song_id، فهي المعرّف الوحيد لاسترجاع الصوت لاحقًا.
• أعد الإرسال عند 429 و500، وعالج السبب أولًا قبل الإعادة عند 400 و401.
• عمليات الإنشاء الفاشلة تُرد تلقائيًا، لذا لا تكلفك المهمة الفاشلة شيئًا.

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

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