API کلون صدا و ساخت با صدای تعیین‌شده (توصیه نمی‌شود)

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

⛔ مسیر قدیمی، برای یکپارچه‌سازی‌های تازه توصیه نمی‌شود. این صفحه مسیر ابتدایی persona (voice_task_id / generate-with-voice) را توضیح می‌دهد. هنوز کار می‌کند، اما دیگر به مشتریان توصیه نمی‌شود؛ در منوی سمت چپ با برچسب «توصیه نمی‌شود» مشخص شده است.

برای یکپارچه‌سازی تازه از 【توصیه‌شده】 API پروفایل صدا استفاده کنید: از یک نمونه صدا پروفایل بسازید (POST /api/music/voice-profile/create) و با آن آهنگ مشخصی را کاور کنید یا آهنگ تازه‌ای بخوانید. پروفایل صدا منبعی درجه‌یک است: می‌توان آن را فهرست، بازیابی و حذف کرد و صدای مبدأ به‌طور دائمی نگه داشته می‌شود.

اگر محصول شما به چرخه کامل «ساخت صدا → استفاده بلندمدت → کاور» نیاز دارد، مسیر تازه را در اولویت بگذارید.

نکته مهم: صدای کلون‌شده ممکن است منقضی شود.

voice_id / voice_task_id که از کلون صدا به دست می‌آید منبعی همیشگی نیست: ممکن است به‌دلیل مدت اعتبار، وضعیت حساب یا تغییر وضعیت صدا از کار بیفتد. طرف یکپارچه‌ساز نباید یک‌بار کلون کند و بعد شناسه صدای ذخیره‌شده در حافظه محلی را تا ابد بازاستفاده کند.

رویه پیشنهادی:

• voice_task_id، voice_id، is_available، updated_at و زمان آخرین ساخت موفق را ذخیره کنید.
• پیش از هر ساخت با صدای کلون‌شده، GET /api/voice/clone/tasks/{voice_task_id} یا POST /api/voice/clone/tasks/{voice_task_id}/check را فراخوانی کنید و مطمئن شوید is_available=true است.
• اگر نقطه پایانی پاسخ داد که صدا در دسترس نیست، کار وجود ندارد یا selected voice is not ready برگرداند، از کاربر بخواهید دوباره کلون کند یا صدای دیگری انتخاب کند.
• به کاربر نهایی وعده ندهید که صدای کلون‌شده یک «دارایی دائمی» است؛ در رابط محصول نشان دهید که «صدا ممکن است منقضی شود و به اعتبارسنجی یا کلون مجدد نیاز داشته باشد».

توضیح نقطه پایانی

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

احراز هویت: Authorization: Bearer YOUR_API_KEY

صورت‌حساب:

• اعتبارسنجی صدا، کلون صدا، پرس‌وجوی وضعیت، حذف و دانلود: رایگان.
• ورودی کلون یک‌مرحله‌ای در فضای کار: ثابت 5 یوان برای هر فراخوانی؛ اعتبارسنجی صدای مبدأ و فایل صوتی تأیید دوم را خودکار انجام می‌دهد و در صورت شکست مبلغ را برمی‌گرداند.
• ادامه خودکار به فایل صوتی تأیید پس از کلون معمولی: ثابت 5 یوان برای هر فراخوانی؛ در صورت شکست طبق روال موجود بازگشت داده می‌شود.
• ساخت آهنگ با صدای کلون‌شده: پرداختی، ثابت 1.2 یوان برای هر فراخوانی؛ هر فراخوانی معمولاً 2 کار جانگهدار برمی‌گرداند.
• با فعال‌بودن Max Mode (max_mode: true در POST /api/music/generate-with-voice)، همان 1.2 یوان برای هر فراخوانی با ضریب 2 یعنی 2.4 یوان برای هر فراخوانی محاسبه می‌شود؛ ساخت صدا هم variety را پشتیبانی می‌کند (0 تا 4، بدون هزینه اضافه)؛ قواعد مقدار در بخش «پارامترهای پیشرفته» مرور کلی API تازه آمده است.

روند فراخوانی

1. POST /api/voice/clone/validate را برای بارگذاری صدای مبدأ فراخوانی کنید و voice_task_id بگیرید.
2. منتظر بمانید یا GET /api/voice/clone/tasks/{voice_task_id} را پرس‌وجو کنید تا validate_info به دست آید.
3. کاربر آن متن را بلند می‌خواند و فایل صوتی تأیید را ضبط می‌کند.
4. POST /api/voice/clone/tasks/{voice_task_id}/generate را برای ارسال فایل صوتی تأیید فراخوانی کنید.
5. POST /api/voice/clone/tasks/{voice_task_id}/check را فراخوانی کنید یا کار را پرس‌وجو کنید تا is_available=true شود.
6. POST /api/music/generate-with-voice را برای ساخت آهنگ با آن صدا فراخوانی کنید.
7. نقطه پایانی ساخت ابتدا کارهای جانگهدار را برمی‌گرداند؛ وقتی ساخت تمام شد و song_id واقعی را گرفتید، می‌توانید با نقاط پایانی دانلود یک فایل یا یک بسته بگیرید.
8. (اختیاری) وقتی دیگر به این صدا نیاز ندارید، DELETE /api/voice/clone/voices/{voice_task_id} را برای حذف فراخوانی کنید؛ معنای آن در بخش 6 آمده است.

کلون یک‌مرحله‌ای هم وجود دارد: در نخستین صفحه ضبط/بارگذاری صدای مبدأ در فضای کار می‌توانید تک‌مرحله‌ای تمام کنید؛ سیستم اعتبارسنجی و ساخت صدا را یک‌جا انجام می‌دهد، پس نیازی به ضبط فایل صوتی تأیید دوم ندارید؛ هزینه 5 یوان برای هر فراخوانی است و در صورت شکست بازگردانده می‌شود.

فیلدهای کار صدا

1. ارسال صدای مبدأ برای اعتبارسنجی

نقطه پایانی: POST /api/voice/clone/validate

پارامترهای بدنه

vocal_end_s - vocal_start_s باید حداقل طول بخش آوازی را برآورده کند. ضبط آواز تمیز، بدون همراهی یا نویز آشکار، بارگذاری کنید.

نمونه درخواست

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "صدای زنانه چینی من",
    "description": "صدای زنانه چینی شفاف و طبیعی",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "صدای زنانه چینی من",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. پرس‌وجوی کار صدا

نقطه پایانی: GET /api/voice/clone/tasks/{voice_task_id}

نمونه درخواست

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "صدای زنانه چینی من",
      "validate_info": "متن تأییدی که اینجا برگردانده شده را بلند بخوانید",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. ساخت مجدد متن تأیید

نقطه پایانی: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

وقتی متن تأیید برای بلندخوانی مناسب نیست یا اعتبارسنجی باید تکرار شود، این را فراخوانی کنید.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. ارسال فایل صوتی تأیید و ساخت صدا

نقطه پایانی: POST /api/voice/clone/tasks/{voice_task_id}/generate

پارامترهای بدنه

نمونه درخواست

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "صدای زنانه چینی من"
  }'

5. بررسی قابل‌استفاده‌بودن صدا

نقطه پایانی: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

وقتی کار قابل استفاده باشد، is_available در پاسخ true است و voice_id برگردانده می‌شود.

6. حذف صدا

نقطه پایانی: DELETE /api/voice/clone/voices/{voice_task_id}

صورت‌حساب: رایگان.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

پس از حذف چه می‌شود

• دیگر نمی‌توان با آن آهنگ تازه ساخت: فراخوانی POST /api/music/generate-with-voice با این voice_task_id (یا voice_id آن) رد می‌شود، پیام خطا selected voice is not ready است و هیچ مبلغی کسر نمی‌شود.
• آهنگ‌هایی که پیش‌تر با آن ساخته شده‌اند هیچ تأثیری نمی‌بینند: پخش، دانلود، ادامه، جایگزینی و جداسازی ترک مثل قبل کار می‌کنند.
• این کار صدا از پرس‌وجوها ناپدید می‌شود: GET /api/voice/clone/tasks/{voice_task_id} مقدار record not found برمی‌گرداند.
• صدای مبدأ طبق سیاست نگهداری دائمی پلتفرم نگه داشته می‌شود (از 2026-09-23 حذف، نمونه صدای بارگذاشته‌شده را پاک نمی‌کند)، اما این به‌معنای قابل بازیابی‌بودن نیست: آن کار قدیمی پایان یافته است و برای ادامه با همان صدا باید کل فرایند کلون را دوباره طی کنید و voice_task_id تازه‌ای بگیرید.
• حذف تکراری: حذف دوباره همان کار مقدار record not found برمی‌گرداند (کار در وضعیت حذف‌شده است و پیدا نمی‌شود).

7. ساخت آهنگ با صدای کلون‌شده

نقطه پایانی: POST /api/music/generate-with-voice

صورت‌حساب: 1.2 یوان برای هر فراخوانی.

پارامترهای بدنه

مدل‌های suno-v6، suno-v6-wild و suno-v6-mini پشتیبانی می‌شوند؛ مدل خالی مانند suno-v6 در نظر گرفته می‌شود. مدل‌های قدیمی V5/V5.5 بازنشسته شده‌اند، اما در کارهای تاریخی ممکن است نام مدل‌های قدیمی دیده شود.

ساختار مشترک درخواست فیلدهای سازگاری Create UI مانند task، soundType، soundLoop، soundBpm، soundKey، voiceTaskId و voiceId را هم می‌خواند، اما این‌ها پارامتر معتبر مشتری برای این نقطه پایانی نیستند: کار صدا باید با voice_task_id فرستاده شود، بررسی اختیاری صدا با voice_id، و ساخت موسیقی با صدا هرگز فیلدهای sound را نمی‌خواند.

نحوه پر کردن پارامترهای ساخت

• با customMode=false، prompt توضیح آهنگ را دارد؛ با customMode=true، prompt متن کامل آهنگ را دارد و style و title هم باید پر شوند. متن آهنگ را به فیلد توضیح حالت الهام نفرستید و توضیح آهنگ را متن حالت پیشرفته در نظر نگیرید.
• weirdnessConstraint و styleWeight نسبت‌های اعشاری از 0.0 تا 1.0 هستند؛ نمی‌توان 50 یا 50% فرستاد. مقدار 0.5 متعادل است؛ حذف آن‌ها یعنی «مشخص‌نشده» و 0 مقداری صریح و معتبر است.
• vocalGender تنها m، male، f یا female را می‌پذیرد. instrumental در این نقطه پایانی فقط فیلد سازگاری است: ساخت با صدای کلون‌شده همیشه آهنگ با خواننده در نظر گرفته می‌شود.
• waitAudio اینجا رفتار را تغییر نمی‌دهد؛ نقطه پایانی همیشه کارهای جانگهدار را ناهمگام برمی‌گرداند. خالی‌بودن audio_url در نتیجه اول طبیعی است: با client_request_id پرس‌وجو کنید و نشانی صدا را تنها پس از کامل‌شدن نتیجه بخوانید.

پارامترهای سرآیند

رفتار Idempotency-Key:

• نخستین درخواست پیش از صورتحساب یک رکورد پایدار حذف تکرار می‌نویسد؛
• اگر همان کلید با همان درخواست پیش‌تر کامل شده باشد، نخستین پاسخ پذیرش دوباره فرستاده می‌شود، بدون کسر دوم و بدون کار دوم؛
• همان کلید با بدنه متفاوت رد می‌شود؛
• همان کلید که هنوز در حال پردازش است خطای پایدار «در حال پردازش» برمی‌گرداند و client_request_id ایمن را تنها پس از تولید برمی‌گرداند؛
• اگر نخستین درخواست با یک کلید شکست بخورد، در وضعیت شکست می‌ماند و تلاش دوباره به کلید تازه نیاز دارد.

شرایط کاور با sourceClipId

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

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

نمونه درخواست

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "یک آهنگ پاپ چینی درباره ساحل دریا در شب تابستان بنویس",
    "style": "Mandopop, warm piano, emotional",
    "title": "نسیم دریا در شب تابستان",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "نسیم دریا در شب تابستان",
        "prompt": "یک آهنگ پاپ چینی درباره ساحل دریا در شب تابستان بنویس"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "نسیم دریا در شب تابستان",
        "prompt": "یک آهنگ پاپ چینی درباره ساحل دریا در شب تابستان بنویس"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

درباره کارهای جانگهدار و song_id نهایی

generate-with-voice نقطه پایانی ساخت ناهمگام است. پاسخ موفق تنها یعنی کار ساخت ارسال شده، نه اینکه آهنگ کامل شده است.

معنای فیلدهای کلیدی پاسخ:

توجه: placeholder_id که با pending: شروع می‌شود نمی‌تواند song_id نهایی باشد و نمی‌توان آن را مستقیم به /api/music/query یا نقاط پایانی دانلود داد. فراخوانی /api/music/query تنها با مقادیر pending:* ممکن است آرایه خالی [] برگرداند، چون آهنگ واقعی هنوز کامل نشده یا کار جانگهدار هنوز با شناسه نهایی آهنگ جایگزین نشده است.

نمونه نادرست:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

روند درست:

1. POST /api/music/generate-with-voice را برای ارسال کار ساخت موسیقی با صدا فراخوانی کنید.
2. client_request_id، items[].placeholder_id و items[].client_request_index را از پاسخ ذخیره کنید.
3. GET /api/music/generate-with-voice/results?client_request_id=cu_xxx را پرس‌وجو کنید.
4. وقتی items[].song_id مقدار داشت و با pending: شروع نمی‌شد، /api/music/query، /api/music/download-file یا /api/music/download-all را فراخوانی کنید.

نسخه فعلی یک نقطه پایانی پرس‌وجوی عمومی اضافه کرده است:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

این نقطه پایانی نتایج کارهای همان client_request_id برای کاربر فعلی را برمی‌گرداند تا مشتری خودش song_id نهایی را پیدا کند. در فهرست برگشتی:

• song_id شناسه واقعی آهنگ است؛
• placeholder_id تنها تا زمانی که کار در وضعیت جانگهدار است دیده می‌شود؛
• مقدار شروع‌شده با pending: با /api/music/query یا نقاط پایانی دانلود قابل استفاده نیست.

اگر فقط client_request_id یا شناسه جانگهدار pending:* را ذخیره کرده‌اید، نخست این نقطه پایانی نتایج را فراخوانی کنید؛ اگر song_id واقعی باز هم پیدا نشد، client_request_id را برای ردیابی به پشتیبانی فنی بفرستید.

پرس‌وجوی نتایج ساخت موسیقی با صدا

نقطه پایانی: GET /api/music/generate-with-voice/results

صورت‌حساب: رایگان.

پارامترهای پرس‌وجو

نمونه درخواست

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ در حال ساخت

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "نسیم دریا در شب تابستان"
      }
    ]
  }
}

نمونه پاسخ پس از کامل‌شدن

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "نسیم دریا در شب تابستان",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

معنای status سطح بالا

8. دانلود یک فایل

نقطه پایانی: POST /api/music/download-file

پارامترهای بدنه

نمونه درخواست

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

پاسخ یک جریان فایل است؛ Content-Type و نام فایل بر پایه آنچه بک‌اند برمی‌گرداند است.

9. دانلود منابع آهنگ به‌صورت بسته

نقطه پایانی: POST /api/music/download-all

پارامترهای بدنه

نمونه درخواست

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

بسته معمولاً صدا، کاور و metadata.json را دارد؛ اگر نوعی منبع هنوز ساخته نشده باشد، در آرشیو قرار نمی‌گیرد.

خطاهای رایج

خطاهای این گروه همیشه HTTP 200 برمی‌گردانند: موفقیت را از فیلد success در بدنه تشخیص دهید (false یعنی شکست و علت در message است) و تنها به کد وضعیت HTTP نگاه نکنید. معنای کامل حذف صدا (آیا هنوز قابل استفاده است، آیا قابل بازیابی است) در بخش 6 آمده است.