From 9f788b962e0245da354e48edaa272e00dcd40e94 Mon Sep 17 00:00:00 2001 From: Dylan Duan Date: Thu, 5 Feb 2026 12:31:23 -0500 Subject: [PATCH] Add combine keyterms and prompt cookbook --- fern/docs.yml | 3 + .../combine-keyterms-and-prompt.mdx | 147 ++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 fern/pages/05-guides/cookbooks/core-transcription/combine-keyterms-and-prompt.mdx diff --git a/fern/docs.yml b/fern/docs.yml index ea5568f7..526f2af5 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -505,6 +505,9 @@ navigation: - page: Select The EU Region for EU Data Residency path: pages/05-guides/cookbooks/core-transcription/how_to_use_the_eu_endpoint.mdx slug: how_to_use_the_eu_endpoint + - page: Combine Keyterms and Prompts + path: pages/05-guides/cookbooks/core-transcription/combine-keyterms-and-prompt.mdx + slug: combine-keyterms-and-prompt - section: Batch transcription skip-slug: true contents: diff --git a/fern/pages/05-guides/cookbooks/core-transcription/combine-keyterms-and-prompt.mdx b/fern/pages/05-guides/cookbooks/core-transcription/combine-keyterms-and-prompt.mdx new file mode 100644 index 00000000..4e2275fc --- /dev/null +++ b/fern/pages/05-guides/cookbooks/core-transcription/combine-keyterms-and-prompt.mdx @@ -0,0 +1,147 @@ +--- +title: "Combine Keyterms Prompting with Prompts" +--- + +Learn how to use both `keyterms_prompt` and `prompt` parameters together in a single transcription request. + + +**We recommend using `keyterms_prompt` OR `prompt` individually, not both together.** Combining both parameters can overload the model, especially with longer prompts or many keyterms, leading to unpredictable or degraded results. Instead, use the `prompt` parameter with your keyterms included as context. + + +## Quickstart + + + + +```python +import requests +import time + +base_url = "https://api.assemblyai.com" +headers = {"authorization": ""} + +# Define your base prompt and keyterms +base_prompt = "This is a YouTube video describing common sports injuries." +keyterms = ["Sprained ankle", "ACL tear", "Hamstring strain", "Rotator cuff injury", "Tennis elbow", "Shin splints", "Concussion", "Groin pull", "Achilles tendonitis", "Meniscus tear"] + +# Append context with keyterms to the prompt +prompt_with_context = f"{base_prompt}\n\nContext: {','.join(keyterms)}" + +data = { + "audio_url": "https://assembly.ai/sports_injuries.mp3", + "speech_models": ["universal-3-pro"], + "language_detection": True, + "prompt": prompt_with_context +} + +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) +``` + + + + +```javascript +import axios from "axios"; + +const baseUrl = "https://api.assemblyai.com"; +const headers = { + authorization: "", +}; + +// Define your base prompt and keyterms +const basePrompt = "This is a YouTube video describing common sports injuries."; +const keyterms = ["Sprained ankle", "ACL tear", "Hamstring strain", "Rotator cuff injury", "Tennis elbow", "Shin splints", "Concussion", "Groin pull", "Achilles tendonitis", "Meniscus tear"]; + +// Append context with keyterms to the prompt +const promptWithContext = `${basePrompt}\n\nContext: ${keyterms.join(",")}`; + +const data = { + audio_url: "https://assembly.ai/sports_injuries.mp3", + speech_models: ["universal-3-pro"], + language_detection: true, + prompt: promptWithContext, +}; + +const url = `${baseUrl}/v2/transcript`; +const response = await axios.post(url, data, { headers: headers }); + +const transcriptId = response.data.id; +const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`; + +while (true) { + const pollingResponse = await axios.get(pollingEndpoint, { + headers: headers, + }); + const transcriptionResult = pollingResponse.data; + + 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)); + } +} +``` + + + + +## 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: +- [Keyterms Prompting](/docs/getting-started/universal-3-pro#keyterms-prompting) +- [Prompting](/docs/getting-started/universal-3-pro#prompting) +- [Prompting Best Practices](/docs/speech-to-text/pre-recorded-audio/prompting-best-practices)