API کالیبراسیون مهر زمانی متن ترانه

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

این تشخیص گفتار نیست. متن همیشه همان متن ترانه اصلی خودتان است؛ ما فقط هر نویسه را در لحظه درست می‌گذاریم — بنابراین «جابه‌جایی متن به‌خاطر نویسه‌های اشتباه شنیده‌شده» رخ نمی‌دهد.

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

متن ترانه موجود را با صدا هم‌تراز می‌کند و مهر زمانی سطح خط و سطح نویسه برمی‌گرداند؛ برای برجسته‌سازی نویسه‌به‌نویسه سبک کاراوکه، متن ترانه چرخان و ساخت زیرنویس.

نقطه پایانی: POST /api/music/lyrics-align

احراز هویت: احراز هویت را ببینید؛ سرآیند Authorization: Bearer YOUR_API_KEY

صورت‌حساب: برای هر فراخوانی (فعلاً پیش‌فرض 0.1 یوان برای هر فراخوانی)؛ اگر آهنگ از پلتفرم باشد و جداسازی آواز را تیک بزنید، یک‌بار دیگر با قیمت «جداسازی آواز/موسیقی همراهی» پلتفرم حساب می‌شود. مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.

زمان میانگین: ۵ تا ۱۵ ثانیه (بسته به طول صدا و اینکه جداسازی آواز همان لحظه لازم باشد یا نه)

چرا کالیبراسیون لازم است: مهرهای زمانی سمت تولید همیشه دقیق نیستند

API متن ترانه با مهر زمانی مهرهای زمانی واژه‌به‌واژه سمت تولید را مستقیم برمی‌گرداند و آن‌ها دقیق نیستند:

• تکرارها، هارمونی‌های متراکم، رپ و نت‌های بلند اغلب کل بخش را جابه‌جا می‌کنند یا چند نویسه را می‌لغزاند؛
• بعضی آهنگ‌ها ابتدایشان یک بخش کم دارد (مثلاً مقدمه بی‌کلام، و اولین قطعه از ثانیه پانزدهم شروع می‌شود)؛
• بعضی خطوط را سخت می‌توان به لنگر زمانی روشن وصل کرد.

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

روش پیشنهادی (سه گام، بهترین نتیجه)

1. ابتدا آواز خالص را جدا کنید (جداسازی آواز/موسیقی همراهی) و فقط مسیر آواز را هم‌تراز کنید — موسیقی همراهی و هارمونی دیگر مزاحم نیستند. مبنای اندازه‌گیری: در مقایسه خط‌به‌خط «میکس کامل در برابر مسیر آواز» از همان آهنگ، ۵ خط از ۲۸ خط بیش از ۰.۲۵ ثانیه اختلاف داشتند (بیشترین ۲.۶۴ ثانیه)؛ دو موتور مستقل روی مسیر آواز به‌طور میانگین ۰.۲۳۹ ثانیه و روی میکس کامل ۰.۵۰۸ ثانیه اختلاف داشتند — یعنی هم‌خوانی تقریباً نصف. بنابراین برای برجسته‌سازی نویسه‌ای (KTV/زیرنویس) توصیه می‌شود روشن باشد. (میزان دقیق بهبود با موتور جدید در حال اندازه‌گیری مجدد است.)
2. متن ترانه کامل بدهید: کل آهنگ، خط‌به‌خط، یک‌به‌یک با صدا. یک جمله یا بند جاافتاده همه خطوط بعدی را جابه‌جا می‌کند؛ مهر زمانی‌هایی مثل [00:23.82] را در متن نگذارید (خودکار نادیده گرفته می‌شوند).
3. برای آهنگ پلتفرم کافی است vocal_separate: true را تیک بزنید تا «جداسازی + هم‌ترازی» را یک‌مرحله‌ای انجام دهیم.

سه روش استفاده

رابطه پارامترها (بیشترین محل اشتباه — با دقت بخوانید)

• ارسال song_id → مسیر آهنگ پلتفرم: lyrics / audio_url / audio_object_key را دیگر نفرستید؛
• ارسال audio_url یا audio_object_key → مسیر آهنگ بیرونی: فقط یکی از این دو، و song_id را نفرستید؛
• vocal_separate تنها برای آهنگ‌های پلتفرم کار می‌کند؛ برای آهنگ بیرونی رد می‌شود (صدا سمت ما نیست، جداسازی ممکن نیست).

جدید: بارگذاری مستقیم فایل محلی (صدا از سرورهای ما نمی‌گذرد)

این را وقتی استفاده کنید که صدا روی رایانه خودتان است و نمی‌خواهید اول آن را به فضای ذخیره‌سازی عمومی خود بفرستید. دو گام:

1. POST /api/music/lyrics-align/upload-ticket با file_name / file_size / content_type و یک put_url (نشانی امضاشده، بدون اعتبارنامه بلندمدت) و object_key می‌گیرید؛
2. فایل را با PUT به put_url بفرستید، و content_type موجود در پاسخ را عیناً همراه ببرید (در امضا نقش دارد؛ تغییر یک نویسه یعنی 403)؛
3. هنگام ارسال درخواست هم‌ترازی، به‌جای audio_url مقدار audio_object_key را بفرستید.

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

جدید: متن ترانه دیگر اجباری نیست

پیش‌تر آهنگ بیرونی متن لازم داشت. اکنون می‌توانید نفرستید: سرور یک‌بار تشخیص انجام می‌دهد و متن تشخیص‌داده‌شده را به‌عنوان متن ترانه به کار می‌برد.

باید هزینه‌اش را صریح گفت: متن آن‌گاه تابع نتیجه تشخیص است و ممکن است چند نویسه نادرست باشد. چنین پاسخ‌هایی با lyrics_source: "asr" و confidence: "low" علامت می‌خورند و در warnings[] مقدار {"code":"no_reference_lyrics"} می‌آید.

برای برجسته‌سازی نویسه‌ای / KTV همیشه متن اصلی را بدهید.

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

Headers

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

محدودیت‌ها

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

آهنگ بیرونی (متن + نشانی صدا)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "در خیابان‌های سرد قدم می‌زنم\nنسیم شب چشم‌هایم را نوازش می‌دهد\nزمان چون آب می‌گذرد",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

آهنگ پلتفرم (بدون جداسازی)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2"}'

آهنگ پلتفرم + جداسازی آواز (برای کاراوکه توصیه می‌شود)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2", "vocal_separate": true}'

پاسخ

پاسخ موفق

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "در خیابان‌های سرد قدم می‌زنم",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "د", "start": 21.66, "end": 21.74, "word": true},
        {"char": "ر", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

توضیح فیلدها

نحوه استفاده از coverage (سه سطح)

وضعیت و زمان‌ها

حد یک اجرا روی سرور ۸ دقیقه است؛ مهلت سمت کلاینت را ۱۲۰ ثانیه یا بیشتر بگذارید.

پاسخ‌های خطا

{
  "success": false,
  "message": "音频超过 6 分钟上限（实际 7.2 分钟）"
}

اصل: بدون نتیجه نهایی، بازپرداخت کامل. هزینه تنها زمانی کسر می‌شود که مهرهای زمانی نویسه‌ای واقعاً برگردند، و بازپرداخت خودکار است و درخواست لازم ندارد.

صورت‌حساب

ترکیب:

قابل پرداخت = قیمت پایه + (متن نمی‌دهید ? هزینه رونویسی : 0) + (جداسازی تیک خورده ? قیمت جداسازی : 0)

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

نمونه کامل (Python)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://www.suno-api.io"

def align_lyrics(song_id=None, lyrics=None, audio_url=None, vocal_separate=False):
    payload = {}
    if song_id:
        payload["song_id"] = song_id
        payload["vocal_separate"] = vocal_separate
    else:
        payload["lyrics"] = lyrics
        payload["audio_url"] = audio_url

    r = requests.post(
        f"{BASE}/api/music/lyrics-align",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=600,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("message"))
    return data


res = align_lyrics(song_id="17e52af7-b5df-4877-a98a-dce94e0e6aa2", vocal_separate=True)
print("کیفیت هم‌ترازی coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # کاراوکه نویسه‌ای: هر نویسه در line["chars"] مقدار start / end خودش را دارد

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

پ: خروجی نویسه‌ای است یا خطی؟ پاسخ: هر دو. lines[].start خطی است و lines[].chars[].start / end نویسه‌ای؛ پخش‌کننده هر کدام را لازم دارد برمی‌دارد.

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

پ: coverage بالاست اما هنوز کمی کج شنیده می‌شود. پاسخ: خطای نویسه‌ای معمولاً در حد ده‌ها میلی‌ثانیه است؛ اگر کل آهنگ با یک مقدار ثابت کج است، احتمالاً ابتدای صدا سکوت دارد — آن را ببرید و دوباره امتحان کنید.

پ: چرا همین حالا جداسازی کار می‌کرد و چند لحظه بعد «مسیر آواز در دسترس نیست» می‌گوید؟ پاسخ: نتایج جداسازی نشانی‌های موقت کوتاه‌عمر هستند (اندازه‌گیری: پس از حدود نیم‌ساعت منقضی می‌شوند). در این حالت نقطه پایانی خودکار دوباره جداسازی را امتحان می‌کند؛ اگر باز هم نشد بازپرداخت کامل انجام می‌شود. پس روش «اول جدا کن، بعد کالیبره کن» قابل اتکا نیست؛ هر دو را در یک جریان انجام دهید.

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

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

پ: نتیجه ذخیره می‌شود؟ پاسخ: این نقطه پایانی چیزی ذخیره نمی‌کند؛ مقدار برگشتی را خودتان نگه دارید (مهرهای زمانی خطی و نویسه‌ای در پاسخ هستند).