Medical Mode

Medical Mode is an add-on that enhances transcription accuracy for medical terminology — including medication names, procedures, conditions, and dosages. It is optimized for medical entity recognition to correct terms that other models frequently get wrong. Medical Mode can be used with all of our Pre-recorded STT models. Enable Medical Mode by setting the domain parameter to "medical-v1". No changes to your existing pipeline are required.

Quickstart

Python
Python SDK
JavaScript
JavaScript SDK

To enable Medical Mode, set domain to "medical-v1" in the POST request body:

import requests
import time

base_url = "https://api.assemblyai.com"
headers = {"authorization": "<YOUR_API_KEY>"}

data = {
    "audio_url": "https://assembly.ai/lispro",
    "language_detection": True,
    "domain": "medical-v1"
}

response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)

if response.status_code != 200:
    print(f"Error: {response.status_code}, Response: {response.text}")
    response.raise_for_status()

transcript_response = response.json()
transcript_id = transcript_response["id"]
polling_endpoint = f"{base_url}/v2/transcript/{transcript_id}"

while True:
    transcript = requests.get(polling_endpoint, headers=headers).json()
    if transcript["status"] == "completed":
        print(transcript["text"])
        break
    elif transcript["status"] == "error":
        raise RuntimeError(f"Transcription failed: {transcript['error']}")
    else:
        time.sleep(3)

To enable Medical Mode, set domain to "medical-v1" in the transcription config.

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

# You can use a local filepath:
# audio_file = "./example.mp3"

# Or use a publicly-accessible URL:
audio_file = "https://assembly.ai/lispro"

config = aai.TranscriptionConfig(
    language_detection=True,
    domain="medical-v1",
)

transcript = aai.Transcriber().transcribe(audio_file, config)

print(transcript.text)

To enable Medical Mode, set domain to "medical-v1" in the POST request body:

const baseUrl = "https://api.assemblyai.com";
const headers = {
  authorization: "<YOUR_API_KEY>",
};

const data = {
  audio_url: "https://assembly.ai/lispro",
  language_detection: true,
  domain: "medical-v1",
};

const url = `${baseUrl}/v2/transcript`;
let res = await fetch(url, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(data),
});
if (!res.ok) throw new Error(`Error: ${res.status}`);
const response = await res.json();

const transcriptId = response.id;
const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

while (true) {
  res = await fetch(pollingEndpoint, { headers });
  if (!res.ok) throw new Error(`Error: ${res.status}`);
  const transcriptionResult = await res.json();

  if (transcriptionResult.status === "completed") {
    console.log(transcriptionResult.text);
    break;
  } else if (transcriptionResult.status === "error") {
    throw new Error(`Transcription failed: ${transcriptionResult.error}`);
  } else {
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

To enable Medical Mode, set domain to "medical-v1" in the transcription config.

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>",
});

// You can use a local filepath:
// const audioFile = "./example.mp3"

// Or use a publicly-accessible URL:
const audioFile = "https://assembly.ai/lispro";

const params = {
  audio: audioFile,
  language_detection: true,
  domain: "medical-v1",
};

const run = async () => {
  const transcript = await client.transcripts.transcribe(params);
  console.log(transcript.text);
};

run();

Example output

Without Medical Mode:

I have here insulin to be used for both prandial mealtime and sliding scale is
insulin lisprohumalog subcutaneously.

With Medical Mode, lisprohumalog is updated to Lispro (Humalog) - following the standard medical convention of writing the generic name first, with the brand name in parentheses.

I have here insulin to be used for both prandial mealtime and sliding scale is
insulin Lispro (Humalog) subcutaneously.

Use cases

Medical Mode is designed for healthcare AI applications where accurate medical terminology is critical:

Ambient clinical documentation — Capture medication names, dosages, and clinical terms correctly in real-time scribing workflows.
AI-powered clinical notes — Generate clean transcripts for downstream LLMs producing SOAP notes, discharge summaries, and referral letters.
Front-office automation — Handle drug names, provider names, and clinic-specific terminology in scheduling calls, insurance verification, and voice agents.
Multi-speaker clinical conversations — Combine with Speaker Diarization for provider/patient separation in telehealth, therapy documentation, and clinical settings.

Combine with other features

Medical Mode works alongside other transcription features. You can combine it with:

Speaker Diarization to identify who said what in clinical conversations
Keyterms Prompting to further boost accuracy for specific medical terms unique to your use case
PII Redaction to redact sensitive patient information from transcripts

Python
Python SDK
JavaScript
JavaScript SDK

data = {
    "audio_url": "<YOUR_AUDIO_URL>",
    "language_detection": True,
    "domain": "medical-v1",
    "speaker_labels": True,
    "keyterms_prompt": ["Lisinopril", "Metformin", "Humalog"]
}

config = aai.TranscriptionConfig(
    language_detection=True,
    domain="medical-v1",
    speaker_labels=True,
    keyterms_prompt=["Lisinopril", "Metformin", "Humalog"],
)

const data = {
  audio_url: "<YOUR_AUDIO_URL>",
  language_detection: true,
  domain: "medical-v1",
  speaker_labels: true,
  keyterms_prompt: ["Lisinopril", "Metformin", "Humalog"],
};

const params = {
  audio: audioFile,
  language_detection: true,
  domain: "medical-v1",
  speaker_labels: true,
  keyterms_prompt: ["Lisinopril", "Metformin", "Humalog"],
};

Medical Mode supports English, Spanish, German, and French. If you use Medical Mode with an unsupported language, the API ignores the domain parameter and returns a warning indicating that Medical Mode was not applied: "Skipped medical-v1 domain correction because the language is not supported"Your transcript is still returned using standard transcription, and you will not be charged for Medical Mode.

HIPAA compliance

AssemblyAI offers a Business Associate Agreement (BAA) for customers who need to process Protected Health Information (PHI). AssemblyAI is SOC 2 Type 2, ISO 27001:2022, and PCI DSS v4.0 certified. Medical Mode does not change existing data handling or retention policies. Paid customers can review and sign our standard online BAA self-serve, at no additional cost, from the Data Controls page in the dashboard. You must have an upgraded (paid) account to see the BAA option. See Data Controls for details, or contact sales for enterprise pricing.

Getting started

Features

API reference

Advanced

Guides

Quickstart

Example output

Use cases

Combine with other features

HIPAA compliance

​Quickstart

​Example output

​Use cases

​Combine with other features

​HIPAA compliance

Quickstart

Example output

Use cases

Combine with other features

HIPAA compliance