> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompting and keyterms

> Contextual prompting and keyterms biasing for dictated transcription.

Two config fields steer the transcript as it is written:

| Field             | Job                                          | Limit                            |
| ----------------- | -------------------------------------------- | -------------------------------- |
| `stt_prompt`      | Describes the situation the audio comes from | 6000 characters                  |
| `keyterms_prompt` | Lists exact terms to expect                  | 100 terms, 8000 characters total |

Both act on the transcription itself, before any LLM pass. They are a different
lever from [`llm_instruction`](/docs/dictation/transcript-rewriting), which reshapes
the transcript after it has been written.

## Contextual prompting

`stt_prompt` describes what the audio is about. It gives the decoder situational
context, which helps it resolve ambiguous audio toward words that make sense in
that setting:

```json theme={null}
{ "stt_prompt": "A doctor dictating a patient visit note." }
```

Describe the situation rather than instructing the model. `stt_prompt` is
prepended to the base transcription prompt, which always applies, so you are
adding context rather than replacing behaviour.

| Instead of                                       | Write                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| "Transcribe this accurately and fix any errors." | "A doctor dictating a patient visit note."                                                  |
| "Output medical terminology."                    | "A cardiologist dictating notes after a stress test, referring to medications and dosages." |

The field is also accepted as `prompt`. Send one or the other; sending both is
rejected with `400`.

## Keyterms prompting

`keyterms_prompt` lists the exact strings you expect to appear: names, drug
names, product SKUs, internal jargon. It biases the decoder toward those
spellings.

```json theme={null}
{ "keyterms_prompt": ["amoxicillin", "lisinopril", "metoprolol"] }
```

This is the same parameter name as the Streaming and Pre-recorded APIs. The
legacy names `keyterms` and `word_boost` are also accepted; send only one of
the three, or the request is rejected with `400`.

Keep the list to terms that are genuinely hard to transcribe. Common words do
not need boosting and dilute the list.

## Using both together

The two fields do different jobs and work well in combination. `stt_prompt`
tells the model what kind of audio this is; `keyterms_prompt` pins the exact
spellings it should expect.

<Tabs groupId="language">
  <Tab language="python-sdk" title="Python SDK" default>
    ```python theme={null}
    import assemblyai as aai

    aai.settings.api_key = "<YOUR_API_KEY>"

    config = aai.DictationConfig(
        stt_prompt="A doctor dictating a patient visit note.",
        keyterms_prompt=["amoxicillin", "lisinopril", "metoprolol"],
    )

    result = aai.DictationTranscriber().transcribe_live("clip.wav", config)
    print(result.text)
    ```
  </Tab>

  <Tab language="python" title="Python">
    ```python theme={null}
    import json
    import requests

    config = {
        "stt_prompt": "A doctor dictating a patient visit note.",
        "keyterms_prompt": ["amoxicillin", "lisinopril", "metoprolol"],
    }

    with open("clip.wav", "rb") as f:
        audio = f.read()

    response = requests.post(
        "https://dictation.assemblyai.com/v1/transcribe/live",
        headers={"Authorization": "<YOUR_API_KEY>"},
        files={
            "config": (None, json.dumps(config), "application/json"),
            "audio": ("clip.wav", audio, "audio/wav"),
        },
        timeout=90,
    )
    response.raise_for_status()
    print(response.json()["text"])
    ```
  </Tab>

  <Tab language="javascript" title="JavaScript">
    ```javascript theme={null}
    import { readFileSync } from "fs";

    const config = {
      stt_prompt: "A doctor dictating a patient visit note.",
      keyterms_prompt: ["amoxicillin", "lisinopril", "metoprolol"],
    };

    const audio = readFileSync("clip.wav");
    const form = new FormData();
    form.append(
      "config",
      new Blob([JSON.stringify(config)], { type: "application/json" })
    );
    form.append("audio", new Blob([audio], { type: "audio/wav" }), "clip.wav");

    const response = await fetch(
      "https://dictation.assemblyai.com/v1/transcribe/live",
      { method: "POST", headers: { Authorization: "<YOUR_API_KEY>" }, body: form }
    );
    console.log((await response.json()).text);
    ```
  </Tab>

  <Tab language="bash" title="cURL">
    ```bash theme={null}
    curl -X POST https://dictation.assemblyai.com/v1/transcribe/live \
      -H 'Authorization: <YOUR_API_KEY>' \
      -F 'config={"stt_prompt": "A doctor dictating a patient visit note.", "keyterms_prompt": ["amoxicillin", "lisinopril", "metoprolol"]};type=application/json' \
      -F 'audio=@clip.wav;type=audio/wav'
    ```
  </Tab>
</Tabs>

Add `llm_instruction` on top when you also want the transcript reshaped. The
three fields compose: `stt_prompt` and `keyterms_prompt` decide what the
transcript says, `llm_instruction` decides what `llm_response` looks like. See
[Transcript rewriting](/docs/dictation/transcript-rewriting).

## Limits

Exceeding a limit is rejected with `400`:

| Field             | Limit                                       |
| ----------------- | ------------------------------------------- |
| `stt_prompt`      | 6000 characters                             |
| `keyterms_prompt` | 100 terms, 8000 characters across all terms |

`DictationConfig` in the Python SDK validates both client-side at the same
values, so an over-long prompt raises before the request goes out. It also
strips whitespace from each keyterm and drops empty ones.

## Related features

* [Transcript rewriting](/docs/dictation/transcript-rewriting) reshapes the
  transcript after it is written.
* [Language selection](/docs/dictation/language-selection) sets the language of the
  audio.