# Create Alignment

`POST https://api.vultrinference.com/v1/audio/alignments`

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.

## Body (multipart/form-data)

- `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 lyrics, lyrics, speech]
- `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

- `200`: OK (alignment-response-payload)
- `400`: A field is missing or not allowed (the message names it), the audio could not be decoded, or the text holds no word the model can spell (error-payload)
- `401`: The API key is missing, unknown or not active. Send it as Authorization: Bearer <key>. (error-payload)
- `404`: The model is not an alignment model, or is not served (error-payload)
- `413`: The audio or the text is over the model's limit, or the audio is longer than it takes (error-payload)
- `429`: Rate limit exceeded (error-payload)
- `502`: The model could not be reached or returned an unusable response (error-payload)
- `503`: The model is not ready (error-payload)
- `504`: The model timed out (error-payload)

## Example

```bash
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"
```

```python
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())
```

```javascript
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());
```


Guides: [Time lyrics and speech to their audio](/docs/workflows/audio-alignment)