【توصیه‌شده】 API پروفایل صدا

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

✅ برای یکپارچه‌سازی‌های تازه این مسیر را توصیه می‌کنیم. بر اساس ارزیابی‌های واقعی کاربران بسیاری، آهنگ‌های ساخته‌شده با این مسیر صدای اصلی را خوب حفظ می‌کنند: صدای خواننده در خروجی نهایی به شخصِ نمونه‌ای که بارگذاری کرده‌اید نزدیک‌تر است، بنابراین این مسیر همان است که اکنون به مشتریان توصیه می‌کنیم.

برای مقایسه: API کلون صدا و ساخت با صدای تعیین‌شده پیشین همچنان کار می‌کند، اما در منو با برچسب «توصیه نمی‌شود» مشخص شده و برای یکپارچه‌سازی تازه توصیه نمی‌شود.

• تاریخ سند: 2026-09-26
• دامنه: ساخت صدای خودتان → استفاده از آن برای کاور آهنگی مشخص / خواندن آهنگ تازه → پیگیری پیشرفت → دانلود خروجی
• همه نقاط پایانی، فیلدها و پاسخ‌ها با فراخوانی واقعی بررسی شده‌اند (مواردی که «اندازه‌گیری‌شده» علامت خورده‌اند با جزئیات تأیید شده‌اند)

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

0. شروع در پنج دقیقه

چهار گام کافی است تا از یک نمونه صدا دو آهنگ آماده به دست آورید.

① ساخت صدا     POST /api/music/voice-profile/create      → دریافت voice_id (status=ready)
② کاور          POST /api/music/voice-profile/cover       → دریافت فوری ۲ song_id
③ پیگیری        POST /api/music/query                     → پرس‌وجو تا status=completed
④ دانلود        GET  /api/music/download?song_id=…&kind=mp3

کمترین مثال کارساز (curl):

API_KEY="sk-کلید-شما"
BASE="https://www.suno-api.io"

# ① ساخت صدا (یک نمونه صدا بارگذاری کنید؛ ۱۰ ثانیه یا بیشتر، زیر ۱۰ مگابایت توصیه می‌شود)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=صدای من" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② با این صدا یک آهنگ را کاور کنید (song_clip_id = شناسه clip آهنگ موردنظر)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nمتن ترانه…",
        "style_requirements": "فولک آرام، گیتار آکوستیک",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ پرس‌وجو (چند شناسه را یک‌جا با کاما جدا کنید)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ پس از پایان mp3 را دانلود کنید (فایل فقط با status=completed می‌آید)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. قواعد مشترک

1.1 دامنه و محیط

همه مسیرهای زیر نسبت به Base URL هستند؛ مثلاً نشانی کامل POST /api/music/voice-profile/create چنین است: https://www.suno-api.io/api/music/voice-profile/create.

1.2 احراز هویت

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

Authorization: Bearer sk-xxxxxxxx

• پیشوند Bearer اختیاری است؛ پیشوند sk- هم (Authorization: sk-xxx نیز کار می‌کند).
• کلید نبودن یا نامعتبر بودن → HTTP 401، بدنه به شکل {"success":false,"message":"…"} (متن بسته به زبان درخواست تغییر می‌کند).
• هر کلید فقط آهنگ‌ها و صداهای حساب خودش را می‌بیند و می‌تواند تغییر دهد.

1.3 قالب بدنه درخواست

• ساخت صدا: multipart/form-data (بارگذاری فایل) توصیه می‌شود؛ application/json (نشانی یا base64) هم پشتیبانی می‌شود.
• دیگر نقاط پایانی: application/json.

1.4 دو پوشش پاسخ (مشتری فقط باید این دو را بشناسد)

نقاط پایانی «مدیریت صدا» (create / create-from-clip / list / detail / delete) از پوشش کسب‌وکار استفاده می‌کنند:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

«کاور با صدا» از کانال ساخت می‌گذرد و از پوشش ساخت استفاده می‌کند: موفقیت code/message/data و شکست شیء error است:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

روش تصمیم: نخست کد وضعیت HTTP، سپس success === false و در آخر code !== 200 یا وجود error. شکست کسب‌وکار تضمین نمی‌کند HTTP غیر از 200 باشد (نقاط مدیریت صدا حتی در خطا هم HTTP 200 برمی‌گردانند)، پس نمی‌توانید فقط به کد وضعیت تکیه کنید.

1.5 ناتکرارپذیری (idempotency)

ساخت صدا (شامل «ساخت از صدای موجود») واقعاً ناتکرارپذیر است: زیر همان کلید، ارسال دوباره همان client_request_id فقط یک صدا می‌سازد و تلاش دوم مستقیم نتیجه اول را برمی‌گرداند (success=true و همان voice_id). روش استفاده این است که کلاینت خودش یک شناسه (مثلاً UUID) بسازد و در تلاش دوباره پس از مهلت، همان مقدار را به کار ببرد.

ارسال کاور در سطح درخواست حذف تکرار نمی‌کند (این یک ساخت پرداختی است)، پس دو نکته را در نظر بگیرید:

1. شناسه ارسال در سرآیند X-Create-Ui-Client-Request-Id: <شناسه ارسال شما> قرار می‌گیرد. در رکورد کار سمت سرور نوشته می‌شود تا بررسی بعدی ساده‌تر شود؛ اما از کسر دوباره جلوگیری نمی‌کند.
2. پایان مهلت ≠ شکست: ممکن است درخواست پذیرفته شده و در حال ساخت باشد. پیش از تلاش دوباره با GET /api/music/songs?p=1&page_size=20 (پارامترهای صفحه‌بندی p / page_size و نوشتار سازگار ps هم کار می‌کند) بررسی کنید آهنگ تازه‌ای با generation_type=voice_profile_cover آمده یا نه، و تنها اگر نیامده همان درخواست را دوباره بفرستید.

بدنه create و create-from-clip هم فیلد client_request_id را می‌پذیرد (بخش §3 و §4).

1.6 نگاه کلی به صورت‌حساب

قیمت‌ها هر زمان از یک نقطه پایانی عمومی خواندنی‌اند، پس آن‌ها را ثابت ننویسید (بخش §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← قیمت پایه کاور با صدا
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← قیمت کلون تقویت‌شده
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

کاور بر پایه کسر پیش از موعد + بازگشت در صورت شکست کار می‌کند:

• درخواست ردشده (پارامتر نادرست، 4xx/5xx پلتفرم، یا خود کمبود موجودی) کسر نمی‌شود — در آزمون ارسال با صدایی که وجود ندارد، موجودی در اندازه‌گیری ما به‌کلی تغییر نکرد (delta = 0)؛
• کاری که پذیرفته شده اما در نهایت شکست خورده (شامل خطای سرویس پلتفرم) از مسیر بازگشت سمت سرور می‌گذرد و مبلغ کسرشده را برمی‌گرداند.

1.7 فرهنگ وضعیت‌ها

status صدا:

status آهنگ (مقداری که نقاط پرس‌وجو برمی‌گردانند):

2. نگاه کلی به نقاط پایانی

3. ساخت صدا

POST /api/music/voice-profile/create

یک قطعه صدای آواز را به‌عنوان «صدا» ثبت کنید و voice_id بگیرید. برای پلتفرم، صدا چیزی نیست جز «یک فایل صوتی + clip آن در آرشیو»، بنابراین پس از ساخت موفق، آن فایل صوتی مبدأ برای همیشه نگه داشته می‌شود (برای کاورهای بعدی).

3.1 سه شکل ورودی (یکی را انتخاب کنید)

شکل A: بارگذاری فایل multipart (توصیه‌شده)

Content-Type: multipart/form-data

file=<داده دودویی صدا>       # الزامی
title=<نام صدا>              # اختیاری؛ اگر خالی باشد، نام فایل بدون پسوند
file_name=<نام فایل اصلی>
source_file_name=<نام فایل اصلی>
source_kind=upload|record    # اختیاری، نشانه منبع (بارگذاری / ضبط)؛ پیش‌فرض upload
enhanced=false|true          # اختیاری، true = کلون تقویت‌شده (بخش §3.5)
client_request_id=<کلید ناتکرارپذیری>   # اختیاری
voice_id=<شناسه دلخواه>       # اختیاری، به‌ندرت استفاده می‌شود

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=صدای من" \
  -F "source_kind=upload"

شکل B: JSON + نشانی عمومی صدا

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "صدای من"
      }'

• نشانی باید لینک مستقیم HTTPS و در دسترس عموم باشد؛ سرور یک‌بار آن را دانلود و به فضای ذخیره‌سازی شیئی ما منتقل می‌کند.
• می‌توانید نشانی را در فیلد audio_url هم بگذارید، اثرش یکسان است (اگر هر دو ارسال شود، file_url اولویت دارد).
• اگر نشانی از قبل در ذخیره‌سازی شیئی همین پلتفرم باشد (*.myqcloud.com/create-ui/voice-source/...)، دوباره دانلود نمی‌شود: مستقیم ثبت می‌گردد.

شکل C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "صدای من"
}

• هم پیشوند data:audio/xxx;base64, و هم base64 خالص پذیرفته می‌شود.
• اندازه محدود است (base64 حدود ۱.۳۳ برابر بزرگ‌تر می‌کند)، برای فایل بزرگ شکل A را به کار ببرید.

3.2 الزامات فایل صوتی

3.3 پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "صدای من",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

توضیح فیلدها (create / list / detail همین مجموعه را به اشتراک می‌گذارند):

created_at / updated_at مُهر زمانی در سطح ثانیه هستند (۱۰ رقم) نه میلی‌ثانیه.

3.4 خطاهای رایج

3.5 کلون تقویت‌شده (enhanced=true)

برای مواردی که «خودِ نمونه صدا ترانه دارای حق نشر دارد / بارگذاری تقویت‌شده لازم است». قیمت همان قیمت بارگذاری تقویت‌شده است (پیش‌فرض ۱۰ یوان هر فراخوانی، در صورت شکست خودکار برگشت داده می‌شود):

• پاسخ بی‌درنگ status=processing + task_id است (در این مرحله clip_id نیست) و ناهمگام اجرا می‌شود؛
• در حین پردازش با GET /api/music/voice-profile/{voice_id} پیشرفت را ببینید که progress_percent / progress_stage / progress_message برمی‌گرداند؛
• پس از پایان status به ready می‌رسد و clip_id، audio_url و image_url تکمیل می‌شوند؛
• در صورت شکست status=failed و error_message چیزی مانند «بارگذاری تقویت‌شده شکست خورد؛ هزینه خودکار برگشت داده شد، بعداً دوباره تلاش کنید» است؛
• کلون تقویت‌شده به‌طور محسوس طولانی‌تر از ساخت عادی است (در حد دقیقه)، پس با منطق مهلت همگام منتظر آن نمانید.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=صدای من" -F "enhanced=true"

4. ساخت صدا از فایل صوتی موجود

اگر نمی‌خواهید دوباره بارگذاری کنید: فایل صوتی‌ای را که قبلاً بارگذاری کرده یا ساخته‌اید مستقیم به صدا کپی کنید. رایگان و ناتکرارپذیر.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: شناسه clip یک فایل صوتی تمام‌شده در حساب شما (همان song_id آهنگ).
• ارسال دوباره همان clip رکورد تازه نمی‌سازد: صدای موجود همراه reused: true برگردانده می‌شود (اندازه‌گیری‌شده).

پاسخ همان همه فیلدهای §3.3 به‌علاوه دو فیلد فقط-خواندنی است:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

خطاها (message عیناً؛ بهتر است نمایش دهید یا بومی‌سازی کنید):

5. فهرست / جزئیات / حذف صدا

5.1 فهرست

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "صدای من", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

فیلدها دقیقاً همان §3.3 هستند. صداهای حذف‌شده به‌طور پیش‌فرض بازنمی‌گردند.

5.2 جزئیات

GET /api/music/voice-profile/{voice_id}

یک شیء صدا برمی‌گرداند (data خودِ شیء است نه آرایه). هنگام اجرای کلون تقویت‌شده اینها اضافه می‌شوند:

5.3 حذف

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• پس از حذف، صدا از فهرست می‌رود و در کاورهای تازه قابل استفاده نیست: ارسال با همان voice_id پاسخ 400 می‌دهد (بخش §6.4).
• آهنگ‌هایی که پیش‌تر با آن ساخته شده‌اند به‌کلی اثر نمی‌گیرند؛ پخش، دانلود، ادامه، جایگزینی و جداسازی مسیرها مثل قبل کار می‌کنند.
• حذف صدایی که وجود ندارد یا مال این حساب نیست، {"success":false,"message":"voice not found"} برمی‌گرداند.

6. کاور با صدا (نقطه پایانی اصلی)

POST /api/music/voice-profile/cover
Content-Type: application/json

یک ارسال ۲ آهنگ می‌سازد (مانند ساخت عادی).

6.1 دو سناریو

resolved_scene در پاسخ مقدار cover یا sing را بازتاب می‌دهد تا بدانید کدام مسیر رفته است.

6.2 فیلدهای درخواست

توصیه می‌شود سرآیند X-Create-Ui-Client-Request-Id: <همان شناسه ارسال> را هم بفرستید: تنها همین در رکورد کار سمت سرور نوشته می‌شود و کلید اصلی بررسی بعدی است (بخش §1.5).

هشدار واحدها: audio_weight / style_weight / weirdness_constraint کسر ۰ تا ۱، variety عدد صحیح ۰ تا ۴ و duration بر حسب ثانیه است. اشتباه گرفتن آن‌ها به رد شدن یا نتیجه غیرعادی می‌انجامد.

ترانه در سناریو ب اختیاری است (مدل خودش مدیریت می‌کند)، اما وقتی محتوای مشخصی باید خوانده شود حتماً lyrics را بفرستید.

6.3 پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[کار] این یک کاور است. … (بخش ساختاری ثابت سرور + الزامات کاور / سبک که وارد کرده‌اید)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

نکات کلیدی:

1. خروجی‌های نهایی را با clips[].song_id شناسایی کنید (این نقطه پایانی فیلد id برنمی‌گرداند).
2. بی‌درنگ دو مقدار song_id می‌گیرید، در حالی که status هنوز processing است (یعنی فقط پذیرفته شده) و audio_url خالی است؛ برای دانلود باید تا completed پرس‌وجو کنید. play_url جریان پیش‌نمایش پلتفرم است، ممکن است از مرحله ارسال ظاهر شود و منقضی می‌گردد.
3. description همان پرامپتی است که سرور نهایتاً می‌فرستد (بخش ساختاری ثابت + cover_requirements / style_requirements که وارد کرده‌اید)؛ هنگام بررسی نتیجه بسیار مفید است.
4. source_updates نتیجه پردازش مواد در سرور است و کلاینت می‌تواند نادیده بگیرد.
5. title که می‌فرستید در رکورد کار سمت سرور نوشته می‌شود و در پرس‌وجوهای بعدی به‌شکل song_title دیده می‌شود؛ اینکه clips[].song_title در پاسخ ارسال معمولاً خالی است طبیعی است.

6.4 خطاها

{ "error": { "message": "این صدا وجود ندارد یا حذف شده است (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

کمبود موجودی همان‌جا در مرحله ارسال خطای صورت‌حساب می‌دهد و کار نیمه‌کاره باقی نمی‌گذارد.

6.5 مدل‌های در دسترس (نام برای مشتری)

از نام‌های مدل مخصوص مشتری (همان بالا) استفاده کنید. chirp-* نام‌های داخلی پلتفرم‌اند و نباید مستقیم به کار روند.

7. پیگیری پیشرفت

7.1 پرس‌وجوی گروهی (توصیه‌شده)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids یک رشته جدا‌شده با کاما است (نه آرایه).
• پاسخ یک آرایه برهنه است (مستقیم [...]، بدون پوشش success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "دو ببر",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[کار] این یک کاور است. … (پرامپت نهایی سرور)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

توصیه پرس‌وجو: هر ۵ تا ۱۰ ثانیه، با مهلت کلی ۱۰ تا ۱۵ دقیقه (کندترین حساب «سرد» در اندازه‌گیری حدود ۴ دقیقه و نیم بود؛ موارد خیلی کمی بیشتر). پایان را از خالی بودن audio_url حدس نزنید، از status استفاده کنید.

نکته سازگاری: این نقطه پایانی آهنگ‌ها را با song_id شناسایی می‌کند؛ در چند پاسخ اولیه فیلد id ظاهر شده بود، پس row.song_id || row.id خواندن ایمن است.

7.2 جزئیات یک آهنگ

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "دو ببر",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "دو ببر",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• اینجا created_at / completed_at ثانیه Unix هستند (برخلاف رشته‌های ISO پرس‌وجوی گروهی، پس کلاینت باید تفاوت را بداند).
• wav_url / video_url ورودی‌های دانلود همین پلتفرم هستند (نسبت به دامنه فعلی) و GET فایل را می‌دهد؛ اگر پلتفرم آن خروجی را نساخته باشد رشته خالی‌اند.
• parameter_retention می‌گوید کدام پارامترهای ارسال برای این آهنگ قابل ردیابی است: core_parameters_available=true یعنی پارامترهای اصلی (ترانه / سبک / منبع) قابل پرس‌وجو هستند، و با extended_parameters_available=false پارامترهای گسترده بالا نگه داشته نشده‌اند (کاور با صدا فعلاً در این دسته است).

7.3 آثار من

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=کلیدواژه

پارامترهای صفحه‌بندی: p (شماره صفحه از ۱) / page_size (تعداد در هر صفحه؛ نوشتار سازگار ps). به‌اختیار status و q (کلیدواژه عنوان). ترتیب پیش‌فرض، زمان ساخت نزولی.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "دو ببر",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

با generation_type=voice_profile_cover می‌توانید «آهنگ‌های برآمده از کاور با صدا» را از دیگر نتایج ساخت جدا کنید.

8. دانلود خروجی‌ها

8.1 گرفتن مستقیم mp3 (توصیه‌شده، رایگان)

هر سه روش کار می‌کند؛ یکی را انتخاب کنید:

1. استفاده از audio_url در نتیجه پرس‌وجو (لینک مستقیم به ذخیره‌سازی شیئی، ساده‌ترین).
2. GET /api/music/download?song_id=<id>&kind=mp3 → مستقیم جریان بایت صدا را می‌دهد (نام فایل در Content-Disposition هست).
3. POST /api/music/download-url (برای نشانی موقت امضاشده).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

مقادیر kind: mp3 (معادل song) / playback (پخش جریانی) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) فعلاً برای برخی آهنگ‌ها موجود است؛ اگر شکست خورد خودتان با API ترانه با مُهر زمانی فایل را بسازید. پاسخ خودِ جریان بایت فایل است و Content-Type و Content-Disposition (نام فایل) تنظیم شده‌اند؛ wav_url / video_url که GET /api/music/songs/{song_id} می‌دهد همان ورودی با kind=wav|video است.

8.2 تبدیل به wav / گرفتن ترانه / متادیتا (پرداختی)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files این‌ها را می‌پذیرد: mp3 / wav / lyrics / metadata، هر بار حداکثر ۱۰ آهنگ.
• صورت‌حساب بر پایه تعداد آهنگ‌های موفق (۰.۲ یوان هر آهنگ)؛ آهنگی که کلاً شکست بخورد حساب نمی‌شود و قالب شکست‌خورده فقط در songs[].errors می‌آید.
• برای گرفتن دوباره فایل‌هایی که پیش‌تر گرفته‌اید، نخست از رایگان POST /api/music/free2/cached (همان song_ids + files) نشانی بایگانی را بگیرید؛ songs[].missing_files در پاسخش قالب‌های بدون کش را که باید دوباره آماده شوند فهرست می‌کند.

9. استعلام قیمت

GET /api/pricing/catalog

نقطه پایانی عمومی بدون احراز هویت. همه قیمت‌های واحدی که باید به مشتری نشان داده شود در data.catalog.meta (رشته‌ها) است:

قیمت‌ها در پنل مدیریت تنظیم می‌شوند، پس زنده بخوانید و در کلاینت ثابت ننویسید. هزینه واقعی کاور = voice_generation_price × (اگر max_mode درست باشد دوباره × max_mode_factor).

10. محدودیت‌ها و هشدارها

1. حجم بارگذاری: ≤ ۱۰ مگابایت (سرور بیشتر می‌پذیرد، اما دروازه ورودی بدنه‌های بزرگ‌تر از ۱۰ مبی‌بایت را می‌بُرد و «رد شدن توسط Suno» دیده می‌شود؛ از سمت خودتان جلوگیری کنید).
2. مدت نمونه: حداقل ۶ ثانیه، ۱۰ تا ۶۰ ثانیه توصیه می‌شود؛ کوتاه‌تر از آن پلتفرم رد می‌کند.
3. محتوای نمونه: آواز تمیز؛ از هر چیزی که بسیار شبیه ضبط موجود است بپرهیزید (تطبیق با آرشیو آن را رد می‌کند).
4. محدودیت متن: lyrics ≤ ۳۰۰۰ نویسه؛ برای style_requirements / negative_tags / title بهتر است به‌ترتیب در ۱۰۰۰ / ۱۰۰۰ / ۱۰۰ نویسه بمانید (الزامات سبک و کاور به پرامپت افزوده می‌شوند، پس مجموع را زیر ۳۰۰۰ نویسه نگه دارید).
5. ترانه بازنویسی نمی‌شود: هر چه بفرستید همان خوانده می‌شود (حرف‌به‌حرف)، بدون برش محلی.
6. هر آهنگ دو نسخه می‌دهد؛ فرض نکنید یک نتیجه است.
7. فایل صوتی مبدأ برای همیشه می‌ماند: حذف صدا، فایل مبدأ را پاک نمی‌کند؛ این کار کاورهای بعدی را ممکن و ردیابی انطباق را حفظ می‌کند.
8. صدا باید ready باشد: صدای processing برای کاور به کار نمی‌آید.
9. مهلت درخواست: در حساب «سرد» نخستین ارسال در اندازه‌گیری تا حدود ۴ دقیقه و نیم طول کشید، پس مهلت کلاینت را ≥ ۶ دقیقه بگذارید. کاور حذف تکرار در سطح درخواست انجام نمی‌دهد، بنابراین پس از پایان مهلت نخست بررسی کنید آهنگ تازه‌ای ساخته نشده باشد (بخش §1.5) و سپس تصمیم به ارسال دوباره بگیرید.
10. مالکیت صدا: صداها به سازنده‌شان تعلق دارند؛ کاور فقط صداهای آماده و حذف‌نشده را می‌پذیرد. صدای ناموجود، حذف‌شده یا متعلق به حساب دیگر 400 برمی‌گرداند: این صدا وجود ندارد یا حذف شده است (voice_id=…).

11. پرسش‌های متداول (FAQ)

پ۱. ساخت صدا هزینه دارد؟ ساخت عادی و «ساخت از صدای موجود» رایگان‌اند؛ تنها کاور (۱.۲ یوان / MAX ۲.۴ یوان) و کلون تقویت‌شده (پیش‌فرض ۱۰ یوان) هزینه دارند.

پ۲. آیا می‌توان از آهنگ نهایی با موسیقی همراه به‌عنوان نمونه صدا استفاده کرد؟ توصیه نمی‌شود. هر چیزی که موسیقی دارد یا بسیار شبیه ضبط موجود در آرشیو است، پلتفرم رد می‌کند (This audio matches an existing recording in our catalog.). از نمونه صوتی صرفاً آوازی و خشک استفاده کنید.

پ۳. چرا پس از ارسال کاور، audio_url خالی است؟ ارسال فقط یعنی پذیرفته شده و status هنوز processing است. نشانی قابل پخش/دانلود تنها پس از پرس‌وجوی /api/music/query تا status=completed پدید می‌آید.

پ۴. در سناریو ب (بدون song_clip_id) باید ترانه بفرستم؟ اختیاری. اگر می‌خواهید محتوای مشخصی خوانده شود lyrics را بفرستید؛ در غیر این صورت مدل خودش تصمیم می‌گیرد اما کنترل کمتری دارید.

پ۵. آیا فایل صوتی‌ای که مشتری خودش بارگذاری کرده می‌تواند مستقیم صدا شود؟ بله: با شکل file_url در create، یا اینکه آن را نخست به‌عنوان آهنگ بارگذاری کنید و سپس create-from-clip را فراخوانی کنید.

پ۶. در صورت شکست پول بازمی‌گردد؟ درخواستی که مستقیماً رد شود (پارامتر نادرست / خطای پلتفرم) بر پایه اندازه‌گیری کسر نمی‌شود؛ کاری که پذیرفته اما در نهایت شکست خورده مبلغ کسرشده را برمی‌گرداند. در شکست نهایی، کار status=failed و error_message برمی‌گرداند.

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

پ۸. هر بار چه مدت آهنگی را می‌توان کاور کرد؟ duration مقدار ۱ تا ۴۸۰ ثانیه می‌پذیرد؛ اگر نفرستید پلتفرم بر پایه آهنگ اصلی / ماده تصمیم می‌گیرد. توجه: حداقل خروجی نهایی پلتفرم حدود ۳۰ ثانیه است؛ با مقدار کمتر در اندازه‌گیری باز هم ۲۹.۹۶ / ۲۹.۷۶ ثانیه به دست آمد.

پیوست A: نمونه کامل (Node.js، همراه پرس‌وجو و دانلود)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① ساخت صدا (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② کاور
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "فولک آرام، گیتار آکوستیک",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ پرس‌وجو تا پایان (هر ۵ ثانیه، حداکثر ۱۵ دقیقه)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // آرایه برهنه
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ دانلود
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "صدای من");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nترانه…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

پیوست B: تاریخچه تغییرات