Word timestamps - AssemblyAI

The timestamps field controls whether each word in the response carries start and end times (in milliseconds, relative to the start of the audio).

Value: a boolean, default false
false (default): no timestamps are computed, and start/end are omitted from the words objects — there is no extra processing cost
true: exact timings are computed for each word, at an additional latency cost

Timings are exact or absent, never approximate: any word that can’t be aligned has start/end omitted rather than estimated. Timestamp accuracy is best for English audio.

Python
JavaScript
cURL

import json
import requests

with open("sample.wav", "rb") as f:
    audio = f.read()

config = {"timestamps": True}

response = requests.post(
    "https://sync.assemblyai.com/transcribe",
    headers={
        "Authorization": "<YOUR_API_KEY>",
        "X-AAI-Model": "universal-3-5-pro",
    },
    files={
        "audio": ("sample.wav", audio, "audio/wav"),
        "config": (None, json.dumps(config), "application/json"),
    },
    timeout=60,
)
response.raise_for_status()
for word in response.json()["words"]:
    print(f'{word["start"]:>6} - {word["end"]:>6}  {word["text"]}')

import { readFileSync } from "fs";

const audio = readFileSync("sample.wav");
const config = { timestamps: true };

const form = new FormData();
form.append("audio", new Blob([audio], { type: "audio/wav" }), "sample.wav");
form.append(
  "config",
  new Blob([JSON.stringify(config)], { type: "application/json" })
);

const response = await fetch("https://sync.assemblyai.com/transcribe", {
  method: "POST",
  headers: {
    Authorization: "<YOUR_API_KEY>",
    "X-AAI-Model": "universal-3-5-pro",
  },
  body: form,
});

const result = await response.json();
for (const word of result.words) {
  console.log(`${word.start} - ${word.end}  ${word.text}`);
}

curl -X POST https://sync.assemblyai.com/transcribe \
  -H 'Authorization: <YOUR_API_KEY>' \
  -H 'X-AAI-Model: universal-3-5-pro' \
  -F 'audio=@sample.wav;type=audio/wav' \
  -F 'config={"timestamps":true};type=application/json'

With timestamps enabled, each entry in words includes its timing:

{
  "text": "Hi, I'm calling about my Best Buy order...",
  "words": [
    { "text": "Hi",  "start": 0,   "end": 200, "confidence": 0.91 },
    { "text": "I'm", "start": 220, "end": 320, "confidence": 0.88 }
  ],
  "confidence": 0.87,
  "audio_duration_ms": 101567,
  "session_id": "eb92c4ff-4bbb-429f-9b99-7279d7fe738f"
}

Combining with other features

timestamps composes with the other config fields — prompting and keyterms, conversation context, and language selection — in the same request.

​Combining with other features

Combining with other features