احراز هویت

به‌روزرسانی 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

با عبور از محدودیت، API کد 429 را برمی‌گرداند و پاسخ ممکن است مقدار retry_after را به ثانیه داشته باشد. تا آن زمان صبر کنید و سپس دوباره تلاش کنید؛ آهنگ درخواست‌ها را کم کنید، کار را در صف بگذارید یا با عقب‌نشینی نمایی دوباره تلاش کنید، نه در حلقه پشت‌سرهم.

سیاست تلاش دوباره

فقط در خطاهای روشن دوباره تلاش کنید. پس از مهلت خواندن یا اتصال دوباره تلاش نکنید: نقاط پایانی تولید همزمان‌اند، بنابراین مهلت می‌تواند به این معنا باشد که سفارش پذیرفته شده و در حال ساخت است — تلاش دوباره سفارش تکراری می‌سازد و دو بار هزینه می‌گیرد. مهلت کلاینت را 300 ثانیه یا بیشتر بگذارید و پس از قطع اتصال، پیش از ارسال دوباره سفارش را با GET /api/music/songs بررسی کنید. بخش «زمان‌های انتظار و تنظیم مهلت» در مرور کلی API جدید را ببینید.

به‌جای حلقه فشرده، با عقب‌نشینی نمایی دوباره بفرستید:

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

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

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

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

سقف ثابتی ندارد. برای هر برنامه یا محیط یک کلید بگذارید تا بتوانید جداگانه لغوشان کنید و کلیدهای بی‌استفاده را حذف کنید.

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

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

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

به کنسول وارد شوید: مصرف هر کلید در آنجا فهرست می‌شود؛ شامل تعداد درخواست، هزینه و کارهای اخیر.

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

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