المصادقة

آخر تحديث 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 من خادمك، وقدّم للمستخدمين نقطة نهاية خاصة بك.

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

Linux / macOS

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

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

.env

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

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

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

بدّل المفاتيح كل 3-6 أشهر، وفوراً عند الشك في تسريب. واحذف المفاتيح التي لم تعد تستخدمها: المفتاح غير المستخدم ليس إلا خطراً غير مستخدم.

حد الطلبات

الطلبات محدودة لكل مفتاح:

429 Too Many Requests

عند تجاوز الحد تُعيد الواجهة 429، وقد تحمل الاستجابة قيمة retry_after بالثواني. انتظر هذه المدة قبل المحاولة التالية، وقلّل معدل الطلبات أو ضع العمل في قائمة انتظار أو أعد المحاولة مع تراجع أُسّي بدل التكرار السريع.

سياسة إعادة المحاولة

أعد المحاولة فقط عند فشل واضح. لا تُعد المحاولة بعد انتهاء مهلة القراءة أو الاتصال: نقاط نهاية التوليد متزامنة، لذا قد تعني المهلة أن الطلب قُبل فعلاً ويجري توليده — وإعادة المحاولة تُنشئ طلباً مكرراً وتخصم مرتين. اضبط مهلة العميل على 300 ثانية أو أكثر، وبعد انقطاع الاتصال تحقق من الطلب عبر GET /api/music/songs قبل إعادة إرساله. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

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

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- ثم حروف وأرقام، بطول إجمالي نحو 50-60 حرفاً.

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

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

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

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

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

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

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

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

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

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

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

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

صفحات ذات صلة

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