API de calibrage des horodatages des paroles

Mis à jour le 2026-09-18 · équipe Suno-API

Ce n'est pas de la reconnaissance vocale. Le texte reprend toujours les paroles d'origine que vous fournissez ; nous ne faisons que placer chaque caractère au bon instant — vous n'aurez donc jamais de « paroles décalées à cause de caractères mal reconnus ».

Description du point d'accès

Il aligne des paroles existantes sur un audio et renvoie des horodatages par ligne et par caractère, pour le surlignage caractère par caractère type karaoké, les paroles défilantes et la génération de sous-titres.

Point d'accès : POST /api/music/lyrics-align

Authentification : voir Authentification ; l'en-tête est Authorization: Bearer YOUR_API_KEY

Facturation : facturé à l'appel (actuellement 0,1 ¥ par appel par défaut) ; sur un morceau de la plateforme avec séparation de la voix cochée, le tarif « séparation voix/accompagnement » de la plateforme est facturé une fois de plus. Le montant réellement facturé suit la configuration tarifaire du back-office.

Durée moyenne : 5 à 15 secondes (selon la longueur de l'audio et la nécessité de séparer la voix sur place)

Pourquoi calibrer : les horodatages du côté génération ne sont pas toujours exacts

L'API de paroles horodatées renvoie directement les horodatages mot par mot du côté génération, et ils comportent des imprécisions :

• les reprises, les harmonies denses, le rap et les notes tenues dérivent souvent globalement ou décalent des caractères isolés ;
• certains morceaux perdent un passage au début (par exemple une intro pure, avec le premier fragment qui ne commence qu'à la quinzaine de secondes) ;
• certaines lignes sont difficiles à rattacher à un instant précis.

Le calibrage refait l'alignement temporel sur les paroles que vous fournissez : seul le temps est corrigé, jamais le texte, ce qui convient aux cas où « est-ce que ça tombe juste » compte (surlignage par caractère type KTV, sous-titres par caractère, notation de chant).

Approche recommandée (trois étapes, meilleur résultat)

1. Extrayez d'abord la voix (séparation voix/accompagnement) et n'alignez que la piste de voix — l'accompagnement et les harmonies cessent de perturber. Base mesurée : dans une comparaison ligne à ligne « mixage complet vs piste de voix » du même morceau, 5 lignes sur 28 différaient de plus de 0,25 s (la plus grande de 2,64 s) ; deux moteurs indépendants différaient en moyenne de 0,239 s sur la piste de voix et de 0,508 s sur le mixage complet — presque deux fois moins de concordance. Pour un surlignage par caractère (KTV/sous-titres), il est donc conseillé de l'activer. (Le gain exact est en cours de remesure avec le nouveau moteur.)
2. Fournissez les paroles complètes : tout le morceau, ligne par ligne, en correspondance une à une avec l'audio. Une phrase ou une section manquante décale toutes les lignes suivantes ; n'incluez pas d'horodatages comme [00:23.82] dans les paroles (ils sont ignorés automatiquement).
3. Sur un morceau de la plateforme, il suffit de cocher vocal_separate: true et nous faisons « séparation + alignement » en une seule étape.

Trois façons d'utiliser l'API

Relations entre les paramètres (c'est là qu'on se trompe le plus, à lire attentivement)

• Envoyer song_id → voie morceau de la plateforme : n'envoyez pas en plus lyrics / audio_url / audio_object_key ;
• Envoyer audio_url ou audio_object_key → voie morceau externe : un seul des deux, et n'envoyez pas song_id ;
• vocal_separate ne fonctionne que pour les morceaux de la plateforme ; l'envoyer pour un morceau externe est refusé (l'audio n'est pas chez nous, il ne peut pas être séparé).

Nouveau : envoi direct d'un fichier local (l'audio ne passe pas par nos serveurs)

À utiliser quand l'audio est sur votre machine et que vous préférez ne pas le déposer d'abord dans votre propre stockage public. Deux étapes :

1. POST /api/music/lyrics-align/upload-ticket avec file_name / file_size / content_type et vous recevez une put_url (URL signée, sans identifiant longue durée) et un object_key ;
2. Faites un PUT du fichier vers put_url, en portant le content_type de la réponse tel quel (il participe à la signature ; un caractère modifié donne 403) ;
3. Lors de l'envoi de l'alignement, transmettez audio_object_key au lieu de audio_url.

L'identifiant est à usage unique : une fois l'alignement terminé (succès ou échec) le serveur supprime l'objet, et réutiliser la même clé renvoie une erreur.

Nouveau : les paroles sont devenues facultatives

Avant, un morceau externe exigeait des paroles. Désormais vous pouvez les omettre : le serveur fait une reconnaissance et utilise le texte reconnu comme paroles.

Le compromis doit être dit clairement : le texte dépend alors du résultat de la reconnaissance, donc des caractères peuvent être faux. Ces réponses sont marquées lyrics_source: "asr", confidence: "low" et, dans warnings[], {"code":"no_reference_lyrics"}.

Pour un surlignage par caractère / KTV, fournissez toujours les paroles d'origine.

Paramètres de la requête

Headers

Paramètres du body

Limites

Exemples de requête

Morceau externe (paroles + adresse de l'audio)

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": "Je marche dans les rues froides\nLa brise du soir effleure mes yeux\nLe temps coule comme l'\''eau",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Morceau de la plateforme (sans séparation)

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"}'

Morceau de la plateforme + séparation de la voix (recommandé pour le karaoké)

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}'

Réponse

Réponse de succès

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Je marche dans les rues froides",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "J", "start": 21.66, "end": 21.74, "word": true},
        {"char": "e", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Référence des champs

Comment utiliser coverage (trois paliers)

État et durées

La limite d'une exécution côté serveur est de 8 minutes ; réglez le timeout du client à 120 secondes ou plus.

Réponses d'erreur

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

Principe : pas de résultat final, remboursement intégral. La facturation n'intervient que si les horodatages par caractère sont réellement renvoyés, et le remboursement est automatique, sans demande.

Facturation

La combinaison :

à payer = prix de base + (pas de paroles ? supplément de transcription : 0) + (séparation cochée ? prix de la séparation : 0)

La séparation de la voix n'est facturée qu'une fois : si vous avez déjà séparé le morceau et que la piste de voix est disponible, c'est ce point d'accès qui la facture ; si la séparation doit se faire sur place, c'est l'étape de séparation qui la facture.

Exemple complet (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("qualité d'alignement coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoké par caractère : chaque caractère de line["chars"] a son propre start / end

Questions fréquentes

Q : La sortie est-elle par caractère ou par ligne ? R : Les deux. lines[].start est par ligne, lines[].chars[].start / end par caractère ; le lecteur prend ce dont il a besoin.

Q : Pourquoi le texte renvoyé est-il identique à ce que j'ai envoyé ? R : C'est voulu. Nous ne reconnaissons ni ne réécrivons, nous ne faisons qu'aligner le temps : les paroles ne peuvent donc jamais être « corrigées en faute ».

Q : Le coverage est élevé mais ça sonne encore un peu décalé. R : L'erreur par caractère est généralement de l'ordre de quelques dizaines de millisecondes ; si tout le morceau est décalé d'une valeur fixe, c'est probablement un passage de silence au début de l'audio : coupez-le et réessayez.

Q : La séparation fonctionnait il y a un instant, et maintenant elle dit « piste de voix indisponible ». R : Les résultats de séparation sont des adresses temporaires de courte durée (mesuré : expiration au bout d'une demi-heure environ). Le point d'accès tente alors de reséparer automatiquement ; si cela échoue encore, c'est remboursement intégral. Donc « séparer maintenant, calibrer plus tard » n'est pas fiable : faites les deux dans le même flux.

Q : Dois-je séparer moi-même un morceau de la plateforme ? R : Non. Avec vocal_separate: true, nous vérifions si le morceau a déjà une piste de voix ; s'il n'y en a pas d'utilisable, nous renvoyons une erreur et remboursons plutôt que de faire passer le mixage complet.

Q : Peut-on faire des lots ? R : Un morceau par requête. Pour des lots, bouclez ; chaque appel est facturé normalement, il est donc conseillé de mettre les résultats en cache.

Q : Le résultat est-il conservé ? R : Ce point d'accès ne persiste rien ; conservez vous-même la valeur renvoyée (les horodatages par ligne et par caractère sont dans la réponse).