احراز هویت

به‌روزرسانی 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 یعنی کلید نامعتبر یا حذف‌شده است.

کلیدم را گم کرده‌ام. چه کنم؟

کلیدها بازیابی نمی‌شوند. کلید تازه‌ای در کنسول بسازید و قدیمی را حذف کنید.

یک حساب چند کلید می‌تواند داشته باشد؟

چند کلید. برای هر برنامه یا محیط یک کلید بگذارید تا بتوانید جداگانه لغوشان کنید.

آیا کلیدها منقضی می‌شوند؟

تا زمانی که حذفشان کنید یا حساب را ببندید معتبرند. چرخش دوره‌ای شیوه خوبی است.

مصرف را چگونه پیگیری کنم؟

موجودی و تاریخچه در کنسول است. هر ساخت ۰,۶ ¥ هزینه دارد و دو قطعه برمی‌گرداند؛ ساخت‌های ناموفق خودکار بازگردانده می‌شوند.

صفحه‌های مرتبط

• شروع سریع
• مدل‌های پشتیبانی‌شده