Connection pre-warming

A request that opens its connection on demand pays the full DNS lookup, TCP handshake, and TLS handshake before the first audio byte can leave. For a distant client that is a network round trip or more, and on a dictation of a few seconds it is a noticeable share of the total wait. The GET /warm endpoint takes that setup off the critical path. Call it as soon as you know audio is coming, typically the moment the user reaches for the record button, and the connection is established in the background while they are still getting ready to speak. The transcription request then starts uploading audio immediately.

How `/warm` works

GET /warm is an unauthenticated no-op:

curl https://dictation.assemblyai.com/warm

{ "warm": "toasty" }

No API key is required, and the response body carries no information. The value of the call is the open connection it leaves in your HTTP client’s pool.

Python SDK
Python
JavaScript

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

with aai.DictationTranscriber() as transcriber:
    # Call as soon as you know audio is coming (e.g. the user taps record).
    transcriber.warm()

    # Same transcriber, so this reuses the warmed connection.
    result = transcriber.transcribe_live("clip.wav")
    print(result.text)

warm() returns True once the connection is open and False if it could not be opened, and never raises. AsyncDictationTranscriber.warm() is the coroutine equivalent, which pairs well with asyncio.create_task(transcriber.warm()) so the handshake overlaps whatever your app is doing next.

import requests

session = requests.Session()

# Call as soon as you know audio is coming (e.g. the user taps record).
session.get("https://dictation.assemblyai.com/warm", timeout=10)

# Same session, so this reuses the warmed connection.
with open("clip.wav", "rb") as f:
    response = session.post(
        "https://dictation.assemblyai.com/v1/transcribe/live",
        headers={"Authorization": "<YOUR_API_KEY>"},
        files={
            "config": (None, "{}", "application/json"),
            "audio": ("clip.wav", f, "audio/wav"),
        },
        timeout=90,
    )
print(response.json()["text"])

import { readFileSync } from "fs";

// Call as soon as you know audio is coming (e.g. the user taps record).
// Node's fetch keeps the connection alive in its pool by default.
await fetch("https://dictation.assemblyai.com/warm");

// Same process, so this reuses the warmed connection.
const audio = readFileSync("clip.wav");
const form = new FormData();
form.append("config", new Blob(["{}"], { type: "application/json" }));
form.append("audio", new Blob([audio], { type: "audio/wav" }), "clip.wav");

const response = await fetch(
  "https://dictation.assemblyai.com/v1/transcribe/live",
  { method: "POST", headers: { Authorization: "<YOUR_API_KEY>" }, body: form }
);
console.log((await response.json()).text);

When to call it

A warmed connection only helps if it is still in the pool when the transcription request goes out, and if that request travels through the same HTTP client and the same host.

Same client. The warm call and the transcription must share a connection pool. A fresh requests.Session, httpx.Client, or AssemblyAI instance for the transcription gets a fresh connection and pays the handshake anyway.
Same host. Pre-warming is per host, so a connection warmed against dictation.assemblyai.com is no use to a request aimed at dictation.eu.assemblyai.com. Warm the host you are about to call. See Cloud endpoints & data residency.
Not too early. Idle connections are evicted after a short window. In the Python SDK that window is settings.keepalive_expiry, which inherits httpx’s 5-second default unless you raise it. Warm shortly before the request rather than at application startup, or raise keepalive_expiry so one call covers a longer pause.

If the connection has been evicted or closed by the time you transcribe, the request silently opens a fresh one and pays the full handshake. The warm-up bought nothing, but nothing breaks either. The ideal moment is when you know audio is coming but do not have it yet. In a dictation app that is the moment the user starts recording: the handshake then runs concurrently with the recording, and by the time they stop speaking the connection is open and fresh. /warm is idempotent and cheap, so calling it again to refresh an aging connection is fine.

Getting started

Features

API reference

Advanced

Connection pre-warming

How `/warm` works

When to call it

​How /warm works

​When to call it

How `/warm` works

When to call it