Combine Keyterms Prompting with Prompts

Our Universal-3-Pro model supports natural language and keyterms prompting, allowing you to fine-tune transcription results to your specific use case. Check out this section of our docs to learn more. By default, these two parameters, prompt and keyterms_prompt, cannot be used in the same request, but this guide will show you how they can be used together in a single transcription request if desired.

We recommend using either prompt OR keyterms_prompt individually, not both together. Combining both parameters can result in overprompting, leading to unpredictable or degraded results, so if you do attempt to use both together, be conscious of the length of your prompt and how many terms you are passing.

Quickstart

1import requests
2import time
3
4base_url = "https://api.assemblyai.com"
5headers = {"authorization": "<YOUR_API_KEY>"}
6
7# Define your base prompt and keyterms
8base_prompt = "This is a YouTube video describing common sports injuries."
9keyterms = ["Sprained ankle", "ACL tear", "Hamstring strain", "Rotator cuff injury", "Tennis elbow", "Shin splints", "Concussion", "Groin pull", "Achilles tendonitis", "Meniscus tear"]
10
11# Append context with keyterms to the prompt
12prompt_with_context = f"{base_prompt}\n\nContext: {', '.join(keyterms)}"
13
14data = {
15 "audio_url": "https://assembly.ai/sports_injuries.mp3",
16 "speech_models": ["universal-3-pro"],
17 "language_detection": True,
18 "prompt": prompt_with_context
19}
20
21response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
22
23if response.status_code != 200:
24 print(f"Error: {response.status_code}, Response: {response.text}")
25 response.raise_for_status()
26
27transcript_response = response.json()
28transcript_id = transcript_response["id"]
29polling_endpoint = f"{base_url}/v2/transcript/{transcript_id}"
30
31while True:
32 transcript = requests.get(polling_endpoint, headers=headers).json()
33 if transcript["status"] == "completed":
34 print(transcript["text"])
35 break
36 elif transcript["status"] == "error":
37 raise RuntimeError(f"Transcription failed: {transcript['error']}")
38 else:
39 time.sleep(3)

Get Started

Before you begin, make sure you have:

  • An AssemblyAI account with an API key
  • Python 3.7+ or Node.js 14+ installed

Understanding the Two Features

Keyterms Prompting (keyterms_prompt)

Use keyterms_prompt to provide up to 1,000 specific words or phrases (maximum 6 words per phrase) to improve transcription accuracy for those exact terms. This is ideal for:

  • Names with unusual spellings (e.g., “Kelly Byrne-Donoghue”)
  • Brand names and product names
  • Technical terminology
  • Acronyms and abbreviations

Prompting (prompt)

Use prompt to provide up to 1,500 words of general context and instructions in plain language. This helps the model:

  • Apply formatting conventions
  • Understand domain context
  • Handle code-switching between languages
  • Interpret ambiguous speech

For best results, keep prompts concise (3-5 instructions, 50-80 words). Overly long prompts can cause the model to degrade in transcription quality as it tries to process conflicting instructions.

Conclusion

While you can use both keyterms_prompt and prompt together, we recommend using the prompt parameter with your keyterms included as context. This approach provides both domain context and term accuracy in a single parameter.

For more details on each feature: