Add combine keyterms and prompt cookbook

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:

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.
+
+<Warning>
+**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.
+</Warning>
+
+## Quickstart
+
+<Tabs groupId="language">
+<Tab language="python" title="Python" default>
+
+```python
+import requests
+import time
+
+base_url = "https://api.assemblyai.com"
+headers = {"authorization": "<YOUR_API_KEY>"}
+
+# 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)
+```
+
+</Tab>
+<Tab language="javascript" title="JavaScript">
+
+```javascript
+import axios from "axios";
+
+const baseUrl = "https://api.assemblyai.com";
+const headers = {
+  authorization: "<YOUR_API_KEY>",
+};
+
+// 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));
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
+## 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
+
+<Note>
+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.
+</Note>
+
+## 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)