شروع سریع

به‌روزرسانی 2026-09-18 · تیم Suno-API

این راهنما در حدود پنج دقیقه شما را از ساخت کلید API تا اولین آهنگ ساخته‌شده، بررسی پیشرفت و دانلود فایل صوتی می‌برد. نمونه‌ها را می‌توانید همان‌طور کپی و اجرا کنید.

مدل پیش‌فرض فعلی suno-v6 است. مدل‌های ساخت از suno-v2 تا suno-v5-5 غیرفعال شده‌اند: ممکن است در کارهای قدیمی دیده شوند، اما درخواست جدید نمی‌پذیرند.

suno-api agent kit را از این نشانی دانلود، نصب و پیکربندی کنید  https://www.suno-api.io/suno-agent-kit.zip

روش پیشنهادی: تکمیل اتصال توسط هوش مصنوعی

هوش مصنوعی فایل 00_START_HERE.md را می‌خواند و برای ثبت‌نام، ذخیره API Key، بررسی موجودی، معرفی امکانات و اولین ساخت کمک می‌کند. عملیات دارای هزینه پیش از اجرا تأیید می‌شود و timeout به‌طور خودکار تکرار نمی‌شود.

گام ۱: کلید API بگیرید

1. https://www.suno-api.io را باز کنید.
2. روی دریافت کلید API بزنید و ثبت‌نام کنید. فقط ایمیل لازم است، نه شماره تلفن.
3. در کنسول بخش مدیریت توکن را باز کنید و یک کلید بسازید.
4. فوراً کپی کنید، چون کلید تنها یک بار نمایش داده می‌شود. پیش از اولین فراخوانی پرداختی، موجودی را با کد شارژ افزایش دهید.

گام ۲: درخواست را تنظیم کنید

همه فراخوانی‌ها از یک نشانی پایه و یک سرآیند استفاده می‌کنند:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

گام ۳: اولین درخواست را بفرستید

نمونه ۱ — ساخت از روی توضیح

موسیقی را توصیف کنید و API متن، ملودی و تنظیم را می‌نویسد:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -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"
  }
]

هر اجرا دو نسخه متفاوت برای انتخاب برمی‌گرداند. هر ساخت ۰,۶ ¥ هزینه دارد.

نمونه ۲ — بررسی پیشرفت

مقدارهای 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.

گام ۴: فایل را دانلود کنید

وقتی status برابر completed شد، فقط audio_url را درخواست کنید. دانلود MP3 و WAV نامحدود است و هزینه اضافی ندارد. اگر برای تدوین به صدای بدون افت نیاز دارید، از نقطه پایانی WAV استفاده کنید.

سناریوهای رایج

موسیقی پس‌زمینه ویدیو

{
  "description": "پس‌زمینه لو-فای آرام برای ویدیوی محصول، بدون خواننده، دینامیک پایدار",
  "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"
  }
}

زمان‌های انتظار و مهلت‌ها (مهم): نقاط پایانی تولید همزمان‌اند — سفارش تنها زمانی پذیرفته و به تولید سپرده می‌شود که پاسخ برسد. بر پایه اندازه‌گیری، بیشتر درخواست‌ها در 1-3 ثانیه پاسخ می‌دهند، حدود 10% بیش از 30 ثانیه طول می‌کشند و طولانی‌ترین حدود 230 ثانیه است. مهلت سمت کلاینت را 300 ثانیه یا بیشتر بگذارید (--max-time 300 در نمونه)؛ نبود پاسخ به معنای تولید نشدن نیست، و بلافاصله پس از مهلت دوباره تلاش نکنید (سفارش را تکرار می‌کند و دوباره هزینه می‌گیرد). اگر اتصال قطع شد، بعداً با GET /api/music/songs بررسی کنید. بخش «زمان‌های انتظار و تنظیم مهلت» در مرور کلی API جدید را ببینید.

بهترین شیوه‌ها

• کلید را روی سرور نگه دارید، هرگز در مرورگر یا برنامه‌های توزیع‌شده.
• هر ۱۰ تا ۱۵ ثانیه پرس‌وجو کنید، نه در حلقه‌ای فشرده.
• مقدارهای song_id را ذخیره کنید؛ تنها شناسه بازیابی صدا در آینده همین است.
• در 429 و 500 دوباره بفرستید؛ در 400 و 401 ابتدا علت را برطرف کنید.
• ساخت‌های ناموفق به‌صورت خودکار بازگردانده می‌شوند، پس کار ناموفق هزینه‌ای ندارد.
• مهلت سمت کلاینت: نقطه پایانی تولید تنها با رسیدن پاسخ پذیرفته‌شده به حساب می‌آید؛ مهلت را 300 ثانیه یا بیشتر بگذارید.
• تلاش دوباره: تنها در خطاهای روشن (4xx/5xx) دوباره تلاش کنید. پس از مهلت یا قطع اتصال، نخست با GET /api/music/songs بررسی کنید سفارش پذیرفته شده یا نه، تا سفارش تکراری و کسر دوباره پیش نیاید.

گام‌های بعدی

• احراز هویت — کلیدها، خطاها و محدودیت‌ها
• مدل‌های پشتیبانی‌شده — نام مدل‌ها، جداسازی استم و مدل‌های غیرفعال