API تولید گفتار

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

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

Speech یک متن سخنرانی یا یک توضیح یک‌خطی را به صدای «گفتار/سخنرانی» تبدیل می‌کند، با موسیقی پس‌زمینه به‌صورت اختیاری. برای سخنرانی، خوش‌آمدگویی، روایت، متن گویندگی، محتوای صوتی و موارد مشابه مناسب است.

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

نقطه پایانی: POST /api/music/speech

صورت‌حساب: پرداختی، فعلاً به‌طور پیش‌فرض 0.6 یوان برای هر فراخوانی. هر فراخوانی معمولاً 2 فایل صوتی برمی‌گرداند؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.

Max Mode / Variety: این نقطه پایانی دو پارامتر اختیاری max_mode و variety (0-4) را پشتیبانی می‌کند. با روشن‌بودن max_mode این فراخوانی با 2 برابر قیمت حساب می‌شود (0.6 → 1.2 یوان برای هر فراخوانی)؛ variety هزینه اضافی ندارد. معنی و روش ارسال آن‌ها در بخش «پارامترهای پیشرفته» در مرور کلی API جدید آمده است.

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

سازگاری محتوا: پلتفرم متن را از نظر حق نشر و سیاست محتوا بررسی می‌کند. اگر شامل مواد محافظت‌شده تشخیص داده شود (مثلاً نقل متن ترانه دیگری یا متن عین یک اثر شناخته‌شده)، این فراخوانی ناموفق می‌شود و کل مبلغ به‌طور خودکار برگشت داده می‌شود. به بیان خودتان تغییر دهید یا نقل را به بازگویی تبدیل کنید و دوباره تلاش کنید.

پارامترهای درخواست

Headers

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

این نقطه پایانی duration را پشتیبانی نمی‌کند: فرستادن آن HTTP 400 برمی‌گرداند، نه اینکه بی‌صدا نادیده گرفته شود. طول سخنرانی با طول محتوای script تعیین می‌شود.

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

کوچک‌ترین درخواست (فقط متن)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "صبح بخیر به همه! سخنرانی امروز من درباره بهره‌گیری درست از زمان و حرکت رو به جلو است."
  }'

درخواست کامل (با تعیین لحن، جنسیت و خاموش‌کردن موسیقی پس‌زمینه)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

نمونه پایتون

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'ظهر بخیر همکاران. گزارش پیشرفت این هفته را ارائه می‌کنم.',
        'tone': 'آرام و شفاف، گزارش جلسه',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # معمولاً ۲ مورد
for item in items:
    print(item['song_id'], item['status'])

توضیح پارامترها

script (متن سخنرانی، الزامی)

• محتوایی که می‌خواهید بگویید را بچسبانید؛ می‌توانید یک توضیح بنویسید و بگذارید مدل خودش متن را بنویسد (مثلاً «یک سخن انگیزشی در نیمهٔ مسابقه برای تیمی که بیست امتیاز عقب است، از زمزمهٔ آهسته تا فریاد بلند»).
• خطوط جدید، پاراگراف‌ها و دستورهای صحنه مانند [وقفه] را می‌توانید مستقیم بنویسید و مدل تا حد امکان رعایت می‌کند.
• حد ۳۰۰۰ نویسه است (بر پایه نویسه یونیکد؛ یک نویسه چینی ۱ حساب می‌شود)؛ بیشتر از آن 400 برمی‌گرداند و هزینه‌ای ندارد.

tone (لحن و فضا، اختیاری)

توضیح می‌دهد چگونه بگویید، نه چه بگویید. بهتر است چهار نوع اطلاعات داشته باشد: لحن، سرعت/ریتم، احساس و فضا.

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

حد ۱۰۰۰ نویسه است. اگر نفرستید، مدل بر پایه محتوای script تصمیم می‌گیرد.

gender / vocal_gender (جنسیت سخنران، اختیاری)

• برای صدای مردانه m یا male و برای زنانه f یا female بفرستید؛ سرور آن‌ها را به m / f یکسان می‌کند.
• هر دو نام فیلد کار می‌کنند، فقط یکی را بفرستید: gender شکل توصیه‌شده در این نقطه پایانی است؛ اگر از قبل حالت سفارشی را استفاده می‌کنید، می‌توانید vocal_gender را نگه دارید.
• نفرستادن یعنی «بدون محدودیت» و مدل تصمیم می‌گیرد.

backing_music (موسیقی پس‌زمینه، اختیاری)

• پیش‌فرض true (با موسیقی پس‌زمینه) است، مانند پیش‌فرض نسخه وب سونو.
• false یک سخنرانی تنها با صدا می‌دهد، مناسب اگر بخواهید بعداً موسیقی یا گویندگی خود را اضافه کنید.
• باید مقدار منطقی JSON یعنی true / false باشد؛ رشته‌های "true" و "1" هم پذیرفته می‌شوند اما مقدار منطقی توصیه می‌شود.

model (مدل، اختیاری)

هر سه مدل مشتری با قیمت یکسان (0.6 یوان برای هر فراخوانی) در دسترس‌اند. سخنرانی با خانواده Suno v6 تولید می‌شود؛ اگر نفرستید مانند suno-v6 در نظر گرفته می‌شود. اگر ترجیح خاصی ندارید، معمولاً نیازی به فرستادن این فیلد نیست.

اعتبارسنجی پارامترها و حد متن

موارد زیر HTTP 400 برمی‌گردانند و همه پیش از هزینه‌کردن متوقف می‌شوند، پس هزینه‌ای ایجاد نمی‌شود:

سقف فیلدهای متنی

عبور از سقف هم HTTP 400 برمی‌گرداند و به تولید نمی‌رود و پیش‌پرداخت هم انجام نمی‌شود. شمارش بر پایه نویسه یونیکد است (یک نویسه چینی ۱ نویسه) و فاصله‌های ابتدا و انتها هم حساب می‌شوند:

شکل پیام خطا script must not exceed 3000 characters; received 4120 است: واژه نخست نام فیلدی است که از سقف گذشته و پایان آن تعداد واقعی است، پس با دریافت 400 می‌توانید با همان دو عدد کوتاه کنید.

پاسخ

پاسخ یک آرایه آهنگ دقیقاً مانند دیگر نقاط پایانی تولید است (معمولاً ۲ مورد)؛ song_id را ذخیره کنید و با API پرس‌وجوی آهنگ و تاریخچه وضعیت نهایی و نشانی صدا را بپرسید:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "بهره‌گیری درست از زمان",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

شکست تولید و بازپرداخت

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

شایع‌ترین دلیل تشخیص محتوای دارای مواد محافظت‌شده است، مثلاً:

Your lyrics contain copyrighted material. Please change it and try again.

در این حالت متن را با بیان خودتان جایگزین کنید (یا نقل را به بازگویی تبدیل کنید) و دوباره بفرستید.

پرسش‌های رایج

پ: چرا نتیجه «گفتار» است و نه آواز؟ پاسخ: این نقطه پایانی سخنرانی است و خروجی آن صدای گفتار است. برای آواز از نقاط پایانی تولید یا حالت سفارشی استفاده کنید.

پ: چرا هر بار ۲ مورد برمی‌گردد؟ پاسخ: مانند دیگر نقاط پایانی تولید در این پلتفرم، یک تولید ۲ گزینه می‌سازد؛ آن‌ها را جداگانه با song_id بپرسید و هر کدام را خواستید نگه دارید.

پ: چگونه طول را کنترل کنم؟ پاسخ: با طول script تعیین می‌شود؛ این نقطه پایانی پارامتر duration را نمی‌پذیرد.

پ: آیا می‌توانم صدا (مثلاً صدای کلون‌شده خودم) را تعیین کنم؟ پاسخ: نسخه کنونی پشتیبانی نمی‌کند. سخنرانی از مجموعه صدای گفتار ثابت استفاده می‌کند و با gender می‌توان مردانه یا زنانه را انتخاب کرد؛ اگر صدای خودتان لازم است، از قابلیت مربوط در API ساخت پروفایل صدا (توصیه‌شده) استفاده کنید.

پ: اگر tone را نفرستم چه می‌شود؟ پاسخ: مدل لحن و ریتم را از محتوای script تشخیص می‌دهد. برای بازتولید پایدار یک سبک، لحن و سرعت و فضا را در tone بنویسید.

فیلدهای سازگار

در اتصال‌های تازه از snake_case به‌طور یکسان استفاده کنید. بقیه فیلدها (script، tone، song_title، backing_music) نام جایگزین camelCase ندارند.

گام‌های بعدی

پس از گرفتن song_id:

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