المصادقة

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

تُصادَق كل الطلبات إلى Suno-API بمفتاح API. توضح هذه الصفحة كيفية إنشاء المفتاح، وكيفية إرساله، ومعنى كل خطأ، وكيفية الحفاظ على أمان المفتاح.

ما هو مفتاح API

المفتاح رمز bearer مرتبط بحسابك. وهو يحمل الرصيد، فمن يملك المفتاح يستطيع إنفاقه. يظهر المفتاح مرة واحدة عند الإنشاء: انسخه واحفظه في مكان آمن.

إنشاء مفتاح

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

تأتي المفاتيح بالشكل sk-…. ولا يمكن استعادة المفتاح المفقود: أنشئ مفتاحًا جديدًا واحذف القديم.

استخدام المفتاح

أرسل المفتاح في ترويسة Authorization مع كل طلب:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

مثال

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "مقطوعة بيانو هادئة لمقهى"}'

أخطاء المصادقة

401 Unauthorized

الترويسة مفقودة أو مشوّهة أو المفتاح غير موجود.

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

تأكد من أن الترويسة بالشكل Bearer <المفتاح> تمامًا (مع مسافة بعد Bearer) وأنه لم يلتصق بآخر المفتاح حرف سطر جديد.

403 Forbidden

المفتاح صالح لكنه لا يستطيع تنفيذ الطلب، وغالبًا بسبب رصيد غير كافٍ. اشحن الحساب وأعد الطلب نفسه.

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

لا تضع المفتاح في كود العميل

لا تضمّن المفتاح في صفحات الويب أو تطبيقات الجوال أو برامج الحاسوب. أي شخص يفتح أدوات فحص المتصفح يمكنه قراءته وإنفاق رصيدك. استدعِ الـ API من خادمك، وقدّم للمستخدمين نقطة نهاية خاصة بك.

استخدم متغيرات البيئة

# ~/.bashrc أو ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

# ملف .env — أضفه إلى .gitignore
SUNO_API_KEY=sk-your-key-here

بدّل المفتاح عند الحاجة

إذا شككت في تسريبه، أنشئ بديلًا واحذف القديم. تبديل المفتاح رخيص، أما المفتاح المكشوف فليس كذلك.

حد الطلبات

الطلبات محدودة لكل مفتاح. عند تجاوز الحد يرد الـ API بـ 429 Too Many Requests.

أعد الإرسال بتراجع أُسّي بدل حلقة متلاحقة:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

أسئلة شائعة

ما هي صيغة المفتاح؟

يبدأ بـ sk- ثم سلسلة عشوائية. تعامل مع القيمة كاملة كرمز واحد.

هل يمكنني استدعاء الـ API من المتصفح مباشرة؟

تقنيًا نعم، لكن لا تفعل ذلك في بيئة الإنتاج، فالمفتاح سيظهر لكل الزوار. مرّر الطلبات عبر خادمك.

كيف أعرف أن المفتاح ما زال صالحًا؟

أرسل أي طلب مصادَق. الرمز 200 يعني أنه يعمل، و401 يعني مفتاحًا غير صالح أو محذوفًا.

فقدت المفتاح، ماذا أفعل؟

لا يمكن استعادة المفاتيح. أنشئ مفتاحًا جديدًا في لوحة التحكم واحذف القديم.

كم مفتاحًا يمكن أن يمتلك الحساب؟

عدة مفاتيح. استخدم مفتاحًا لكل تطبيق أو بيئة حتى تتمكن من إلغائها كلًا على حدة.

هل تنتهي صلاحية المفاتيح؟

تبقى صالحة حتى تحذفها أو تغلق الحساب. التبديل الدوري ممارسة جيدة.

كيف أتابع الاستخدام؟

الرصيد والسجل في لوحة التحكم. كل عملية إنشاء تكلف 0,6 ¥ وتُرجع مقطوعتين، والعمليات الفاشلة تُرد تلقائيًا.

صفحات ذات صلة

• البدء السريع
• النماذج المدعومة