For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see For full documentation content, see For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at

Keyterms Prompting

For the complete documentation index, see llms.txt

Supported models: Universal-3 Pro (universal-3-pro), Universal-2 (universal-2). Key parameter: keyterms_prompt (array of strings, up to 1,000 words/phrases for U3 Pro, up to 200 for U2). Improves transcription accuracy for specific words and phrases. Start with no keyterms and add terms as needed.

cURL quickstart:

curl  \
  --header "Authorization: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "audio_url": "",
    "speech_models": ["universal-3-pro", "universal-2"],
    "keyterms_prompt": ["Kelly Byrne-Donoghue"]
  }'

Keyterms prompting allows you to provide up to 1,000 words or phrases (maximum 6 words per phrase) using the keyterms_prompt parameter to improve transcription accuracy for those terms and related variations or contextually similar phrases.

We strongly recommend starting with no keyterms_prompt and then adding terms as needed based on important words for your use case that you are consistently seeing the model struggle with.

Including a large number of terms or common terms that are well represented in the training data could lead to overcorrections and hallucinations.

Using Universal-3 Pro (Recommended)

Here is an example showing how you can use keyterms prompting to improve transcription accuracy for a name with distinctive spelling and formatting.

Without keyterms prompting:

Hi, this is Kelly Byrne Donahue

With keyterms prompting:

Hi, this is Kelly Byrne-Donoghue

import requests
import time

base_url = ""
headers = {"authorization": "<YOUR_API_KEY>"}

data = {
    "audio_url": "",
    "language_detection": True,
    "speech_models": ["universal-3-pro", "universal-2"],
    "keyterms_prompt": ["Kelly Byrne-Donoghue"]
}

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)

const baseUrl = "";
const headers = {
  authorization: "<YOUR_API_KEY>",
};

const data = {
  audio_url: "",
  language_detection: true,
  speech_models: ["universal-3-pro", "universal-2"],
  keyterms_prompt: ["Kelly Byrne-Donoghue"],
};

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));
  }
}

While we support up to 1000 key words and phrases, actual capacity may be lower due to internal tokenization and implementation constraints. Key points to remember:

• Each word in a multi-word phrase counts towards the 1000 keyword limit
• Capitalization affects capacity (uppercase tokens consume more than lowercase)
• Longer words consume more capacity than shorter words

For optimal results, use shorter phrases when possible and be mindful of your total token count when approaching the keyword limit.

Using Universal-2 (Beta)

keyterms_prompt for Universal-2 is currently available at no additional cost while we gather feedback and refine functionality. Pricing may be introduced as the feature moves out of beta. We'll notify all users well in advance of any pricing changes.

As we continue to develop this feature, functionality may evolve. For the latest updates and code examples, please check back on this page.

If you're currently using our universal-2 model, the keyterms_prompt parameter is in Beta for English files.

The maximum number of keyterms with Universal-2 is 200. Keyterms shorter than 5 characters or longer than 50 characters are ignored.

import requests
import time

base_url = ""
headers = {"authorization": "<YOUR_API_KEY>"}

data = {
    "audio_url": "",
    "speech_models": ["universal-2"],
    "language_detection": True,
    "keyterms_prompt": ['differential diagnosis', 'hypertension', 'Wellbutrin XL 150mg']
}

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)

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

audio_file = ""

config = aai.TranscriptionConfig(
    speech_models=["universal-2"],
    language_detection=True,
    keyterms_prompt=['differential diagnosis', 'hypertension', 'Wellbutrin XL 150mg']
)

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

print(transcript.text)

const baseUrl = ''

const headers = {
  authorization: '<YOUR_API_KEY>'
}

const data = {
  audio_url: '',
  speech_models: ['universal-2'],
  language_detection: true,
  keyterms_prompt: ['differential diagnosis', 'hypertension', 'Wellbutrin XL 150mg']
}

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 pollingResponse = await res.json();
  const transcriptionResult = pollingResponse

  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))
  }
}

import { AssemblyAI } from "assemblyai";

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

const audioFile = "";

const params = {
  audio: audioFile,
  speech_models: ["universal-2"],
  language_detection: true,
  keyterms_prompt: ['differential diagnosis', 'hypertension', 'Wellbutrin XL 150mg']
};

const transcript = await client.transcripts.transcribe(params);

console.log(transcript.text);