Create Alignment

POST /v1/audio/alignments Models: Alignment View .md

Time words you already have against the audio they are in. Send the audio and its words; the answer gives a start and an end for every word and every line, each with the aligner's confidence. Nothing is transcribed or guessed: every word that comes back is one you wrote, in the order you wrote it. Use it for karaoke and lyric display, subtitles and captions, and finding a phrase in a recording.

The request is multipart/form-data. Any common audio format works (wav, mp3, flac, m4a, ogg, webm, aac). provider is accepted and ignored.

Text: One line per line of the audio. A line in square brackets ([Chorus], [Verse - Singer A]) is a section label: it names the lines under it and is never aligned. Text with labels and text without both work. A line with nothing the model can spell (a row of punctuation, a word in another alphabet) comes back in unaligned instead of in lines.

Mode: lyrics (the default) separates the vocal from the music first, which is what a song needs. speech skips that step, which is faster and right for a voice recording with little else in it.

Languages: The aligner spells the Latin alphabet, so language takes the codes listed in the model's supported_languages; accented letters are matched without their accents. English, French, German and Spanish are the languages it has been measured on, with 92 to 98 percent of words placed within 0.3 seconds of where a person marked them. A text with no letter the model can spell (Cyrillic, Chinese, Japanese, Korean, Arabic) is a 400.

Limits: The model's catalog entry gives the audio and text limits: at most 25 MiB and 15 minutes of audio and 12,000 characters of text for aligner-1.

Reading the result: certain is the aligner's own judgement that a line is placed right. It is not a guarantee: a line can be wrong and still marked certain. score is the median confidence of a line's words, or of one word. A low score means an indistinct voice more often than a wrong line.

Billing: Per second of the audio's own duration, rounded up to a whole second, at the model's price. Nothing is billed for a request that fails. usage.cost is the cost of the whole seconds billed.

Guides: Time lyrics and speech to their audio

Body

multipart/form-data

An audio file and the words it holds.

model string required

The alignment model to use, e.g. aligner-1.
file string (binary) required

The audio file. Its size and length are limited by the model (aligner-1 takes 25 MiB and 15 minutes).
text string required

The words in the audio, one line per line. A line in square brackets ([Chorus]) labels the lines under it and is not aligned. At most 12,000 characters for aligner-1.

at least 1 characters
mode string

lyrics separates the vocal from the music before aligning; speech does not.

default lyricslyricsspeech
language string

ISO 639-1 code of the language the text is written in, one of the model's supported_languages. Optional; any other code is a 400.

Responses

application/json · alignment-response-payload

6 fields

duration number required

Length of the audio in seconds.
separated boolean required

Whether the vocal was separated from the music first (mode lyrics).
lines array of objects required

The lines that were placed in the audio, in order.
8 fields
- index integer required
  
  Which line of text this is, counting from 0 and skipping section labels and blank lines.
- section integer required
  
  Which section the line is in, counting from 0, so a chorus that repeats stays two sections.
- tag string or null required
  
  The label of the section (Chorus for [Chorus]), or null for lines before the first label or in text with none.
- text string required
  
  The line as you wrote it.
- start number required
  
  Seconds from the start of the audio to the first word.
- end number required
  
  Seconds from the start of the audio to the end of the last word.
- score number required
  
  Median confidence of the line's words. Higher is better; use it to judge by, not to filter on.
- certain boolean required
  
  The aligner's judgement that the line is placed right. False where a word was held so long that the search plainly parked it across a gap. True is not a guarantee.
words array of objects required

Every word of the lines above, in order.
5 fields
- line integer required
  
  The index of the line the word is in.
- text string required
  
  The word as you wrote it.
- start number required
  
  Seconds from the start of the audio.
- end number required
  
  Seconds from the start of the audio.
- score number required
  
  The aligner's confidence in this word.
unaligned array of objects required

Lines the model could not place, listed instead of left out.
3 fields
- line integer required
  
  The index of the line.
- text string required
- reason string required
  
  Why the line was not placed.
usage object required
3 fields
- type string required
  
  Always duration.
- seconds number required
  
  The audio's duration in seconds, the same as duration. Billed rounded up to a whole second.
- cost number required
  
  Dollars for the whole seconds billed, at the model's price.

curl https://api.vultrinference.com/v1/audio/alignments \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -F "model=string" \
  -F "file=@file.pdf" \
  -F "text=string"

import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/audio/alignments",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    files={"file": open("file.pdf", "rb")},
    data={
    "model": "string",
    "text": "string",
},
)
print(response.json())

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("model", "string");
form.append("file", await openAsBlob("file.pdf"), "file.pdf");
form.append("text", "string");

const response = await fetch("https://api.vultrinference.com/v1/audio/alignments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
  },
  body: form,
});
console.log(await response.json());

Response · 200

{
    "duration": 0.0,
    "separated": false,
    "lines": [
        {
            "index": 0,
            "section": 0,
            "tag": "string",
            "text": "string",
            "start": 0.0,
            "end": 0.0,
            "score": 0.0,
            "certain": false
        }
    ],
    "words": [
        {
            "line": 0,
            "text": "string",
            "start": 0.0,
            "end": 0.0,
            "score": 0.0
        }
    ],
    "unaligned": [
        {
            "line": 0,
            "text": "string",
            "reason": "string"
        }
    ],
    "usage": {
        "type": "string",
        "seconds": 0.0,
        "cost": 0.0
    }
}