API تولید متن ترانه

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

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

تولید متن ترانه از روی موضوع، بافت متن موجود و نیازهای سبکی، متن را می‌سازد یا بازنویسی می‌کند. این نقطه پایانی به جدیدترین قرارداد تولید متن ارتقا یافته و مستقیماً برای تولید در حالت حرفه‌ای قابل استفاده است.

نقطه پایانی: POST /api/lyrics/generate

صورت‌حساب: در محدوده سهمیه رایگان است (حداکثر 10 فراخوانی در دقیقه و 300 در روز برای هر کاربر)؛ بیش از سهمیه رایگان 0.1 یوان برای هر فراخوانی.

تشخیص عبور از سهمیه: وقتی از سهمیه رایگان عبور شود، درخواست همچنان به‌طور عادی اجرا می‌شود و سرآیندهای پاسخ شامل X-Suno-Helper-Free: false و X-Suno-Helper-Over-Limit: minute (یا day) است، بنابراین کلاینت می‌تواند اعلام کند که این فراخوانی هزینه‌دار بوده است.

مدل پیشنهادی: suno-v6. می‌توان از suno-v6، suno-v6-wild و suno-v6-mini استفاده کرد.

احراز هویت

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

instruction فیلدهای قدیمی theme و prompt را هم می‌پذیرد. مقدار پیش‌فرض metadata.lyrics_model برابر default و metadata.enable_thinking برابر false است.

کنترل زبان

این نقطه پایانی فیلد درخواست language جداگانه‌ای ندارد. زبان متن با محتوای instruction تعیین می‌شود و style فقط نقش کمکی دارد.

برای گرفتن متن چینی، زبان مقصد را صریح در instruction بنویسید، مثلاً:

{
  "model": "suno-v6",
  "instruction": "请用中文写歌词，主题是夏夜海边重逢",
  "style": "Mandopop, 中文流行"
}

می‌توانید "Write the lyrics in Chinese about ..." هم بنویسید. برای متن انگلیسی "请用英文写歌词" یا "Write the lyrics in English" را بنویسید. اگر فقط موضوع انگلیسی بفرستید و زبان مقصد را ذکر نکنید، نتیجه ممکن است انگلیسی باشد.

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

curl -X POST https://www.suno-api.io/api/lyrics/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "instruction": "متن ترانهٔ فارسی دربارهٔ فصل فارغ‌التحصیلی و شروع دوباره",
    "style": "پاپ راک، صمیمی، همخوان به‌یادماندنی",
    "title": "شروع دوباره",
    "metadata": {
      "lyrics_model": "default",
      "enable_thinking": false
    }
  }'

پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "lyrics": "[Verse]\nباد از میان حیاط مدرسه می‌گذرد\nبرای دیروز دست تکان می‌دهیم",
    "edited_lyrics": "[Verse]\nباد از میان حیاط مدرسه می‌گذرد\nبرای دیروز دست تکان می‌دهیم",
    "lyrics_id": "lyrics_id",
    "lyrics_request_id": "lyrics_request_id"
  }
}

edited_lyrics متن کامل ترانه‌ای است که باید در کادر متن وارد شود. lyrics_id و lyrics_request_id برای رهگیری‌اند و بسته به پاسخ نقطه پایانی ممکن است خالی باشند؛ آن‌ها را شناسه آهنگ در نظر نگیرید.

نکات سازگاری

• فیلدهای قدیمی theme و prompt هنوز کار می‌کنند و به instruction نگاشت می‌شوند.
• مجموعه نقاط پایانی «پروژه متن / ترانه‌سرا» متوقف شده است: اگر باید نتایج تولیدشده را نگه دارید، edited_lyrics برگشتی از نقطه پایانی را خودتان ذخیره کنید.