歌詞タイムスタンプ校正 API

2026-09-18 更新 · Suno-API チーム

これは音声認識ではありません。 文字は必ずお客様が渡した歌詞原文をそのまま採用し、私たちは各文字を正しい時刻に置くだけです——だから「認識ミスで歌詞がずれる」ことは起きません。

インターフェースの説明

既存の歌詞と音声を揃え、行単位＋文字単位のタイムスタンプを出力します。カラオケの逐字ハイライト、スクロール歌詞、字幕生成に使えます。

エンドポイント: POST /api/music/lyrics-align

認証: 認証を参照。リクエストヘッダーは Authorization: Bearer YOUR_API_KEY

課金: 1 回ごとの課金（現在は既定で 1 回 0.1 元）。プラットフォーム楽曲で人声分離を選んだ場合は、プラットフォームの「人声／伴奏分離」価格でもう 1 回課金されます。実際の請求額は現在の管理画面の価格設定に従います。

平均所要時間: 5〜15 秒（音声の長さ、およびその場で人声分離が必要かどうかによります）

校正が必要な理由：生成側のタイムスタンプは常に正確とは限らない

タイムライン歌詞 API は生成側の逐語タイムスタンプをそのまま返しますが、不正確さがあります：

• 繰り返し、ハモリが多い曲、ラップ、ロングトーンでは全体がずれたり一部の文字がずれたりしやすい；
• 一部の曲は冒頭が欠ける（例：純粋な前奏で、最初の断片が十数秒から始まる）；
• 明確な時間アンカーが取りにくい歌詞行がある。

歌詞タイムスタンプ校正は、お客様が提供した歌詞を土台に時間合わせをやり直すもので、時間だけを校正し、文字は変えません。「合うかどうか」が重要な用途（KTV の逐字ハイライト、逐字字幕、歌ってみたの採点）に向いています。

推奨手順（3 ステップ、最も効果的）

1. まず純粋な人声を抽出（人声／伴奏分離）し、人声トラックだけを揃えます——伴奏とハモリが邪魔をしなくなります。 実測根拠：同じ曲の「フルミックス vs 人声トラック」を行ごとに比較すると、28 行のうち 5 行が 0.25 秒以上ずれ（最大 2.64 秒）ていました。 独立した 2 つのエンジンは、人声トラックでは平均差 0.239 秒、フルミックスでは 0.508 秒——一致度がほぼ半分です。 そのため逐字ハイライト（KTV／字幕）では有効化を推奨します。（改善幅は新しいエンジンで再測定中です。）
2. 完全な歌詞を渡す：曲全体、行単位、音声と一対一。文や段落が抜けると後続の行が全体的にずれます。歌詞に [00:23.82] のようなタイムスタンプを入れないでください（入っていても自動で無視されます）。
3. プラットフォーム楽曲なら vocal_separate: true を付けるだけで、「分離＋整列」を一度に済ませられます。

3 つの使い方

パラメータの関係（最も間違えやすいので必ず確認してください）

• song_id を渡す → プラットフォーム楽曲の経路：lyrics / audio_url / audio_object_key は渡さないでください；
• audio_url または audio_object_key を渡す → 外部曲の経路：どちらか一方だけを渡し、song_id は渡さないでください；
• vocal_separate はプラットフォーム楽曲にのみ有効で、外部曲で渡すと拒否されます（音声がこちらに無いため分離できません）。

追加：ローカルファイル直送（音声が当社サーバーを通りません）

音声が手元にあり、自分の公開ストレージに先に上げたくない場合に使います。2 ステップです：

1. POST /api/music/lyrics-align/upload-ticket に file_name / file_size / content_type を付けて呼び、 put_url（長期の資格情報を含まない署名 URL）と object_key を受け取ります；
2. ファイルを put_url に PUT します。レスポンスの content_type をそのまま付けてください（署名の対象なので 1 文字変えると 403 です）；
3. 整列を送信するときは audio_url ではなく audio_object_key を渡します。

資格情報は使い捨てです：整列が終わると（成功・失敗を問わず）サーバーがこのオブジェクトを削除し、同じ key を再使用するとエラーになります。

追加：歌詞は省略可能になりました

以前は外部曲に歌詞が必須でした。今は渡さなくても使えます——サーバーが先に一度認識を行い、認識した文字を歌詞として使います。

代償は明確にしておきます：文字は認識結果が基準で、一部の文字が不正確なことがあります。そのようなレスポンスには lyrics_source: "asr"、confidence: "low" が明示され、warnings[] に {"code":"no_reference_lyrics"} が入ります。

逐字ハイライト／KTV を作るなら、必ず歌詞原文を提供してください。

リクエストパラメータ

Headers

Body パラメータ

制限

リクエスト例

外部曲（歌詞＋音声アドレス）

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 の使い方（3 段階の目安）

状態と所要時間

サーバー側の 1 回の実行上限は 8 分です。クライアントのタイムアウトは 120 秒以上を推奨します。

エラー応答

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

原則：最終結果が得られなければ全額返金。 逐字タイムスタンプが実際に返ったときだけ課金され、返金は自動で完了します（申請不要）。

課金

組み合わせ：

実払い = 基準価格 + （歌詞を提供しない ? 転写追加料金 : 0） + （分離を指定 ? 分離価格 : 0）

人声分離の費用は 1 回だけ：すでに分離済みで人声トラックを直接取得できる場合は本エンドポイントが、その場で分離が必要な場合は分離のステップが課金します。

完全な例（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 があります

よくある質問

Q：返るのは逐字ですか行単位ですか？ A：両方です。lines[].start は行単位、lines[].chars[].start / end は逐字で、プレイヤーが必要な方を使います。

Q：なぜ返る文字が渡したものとまったく同じなのですか？ A：設計どおりです。私たちは認識による書き換えを行わず、時間合わせだけを行うので、歌詞が「誤字に直される」ことはありません。

Q：coverage は高いのに、まだ少しずれて聞こえます。 A：逐字整列の誤差は通常数十ミリ秒程度です。曲全体が一定量ずれているなら、音声の冒頭に無音がある可能性が高いので、切り詰めてから再試行してください。

Q：さっきは人声分離で使えたのに、しばらくすると「人声トラックが使えません」と言われます。 A：分離結果は短命な一時アドレスです（実測で約 30 分後に失効）。その場合エンドポイントは自動で再分離を試みます。それでも失敗すると全額返金します。つまり「先に分離して、あとで校正」は当てにできません。同じフローの中で続けて行ってください。

Q：プラットフォーム楽曲は自分で先に分離する必要がありますか？ A：不要です。vocal_separate: true を付けると、その曲に人声トラックがあるかを確認します。使える人声トラックが無ければエラーにして返金します（原曲でごまかすことはしません）。

Q：バッチ処理はできますか？ A：1 リクエスト 1 曲です。バッチはループしてください。毎回きちんと課金されるので、結果をローカルにキャッシュすることをおすすめします。

Q：結果は保存されますか？ A：本エンドポイントは永続化しません。返却値をご自身で保存してください（行単位＋逐字のタイムスタンプはレスポンスに含まれています）。