> ## 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.

# Transcript rewriting

> Reshape a dictated transcript with llm_instruction, alongside the verbatim one.

Dictation runs an LLM pass over the transcript and returns the result in
`llm_response`, alongside the verbatim transcript in `text`. This is the one
feature Dictation has that the other speech-to-text APIs do not: you get the
words as spoken and a usable version of them from the same call.

The rewrite is applied by default. Omitting `llm_instruction`, or the whole
`config` part, runs the default cleanup task, which removes disfluencies only:
filler sounds and phrases, false starts, and stammered repeats. Every kept
word, its spelling, and its punctuation stay exactly as spoken.

```python theme={null}
import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

result = aai.DictationTranscriber().transcribe_live("clip.wav")

print(result.text)          # "Um, so the, the patient has a persistent cough."
print(result.llm_response)  # "The patient has a persistent cough."
```

## Customizing the rewrite

Set `llm_instruction` to a plain-English description of the task you want, up
to 2048 characters. It replaces the default cleanup task rather than adding to
it:

```json theme={null}
{ "llm_instruction": "Remove filler words and fix punctuation." }
```

An explicit `"llm_instruction": null` means the same as omitting the field, so
the default cleanup task still runs.

<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(
        llm_instruction="Rewrite as a concise clinical chart note.",
    )

    result = aai.DictationTranscriber().transcribe_live("clip.wav", config)

    print(result.text)        # the verbatim transcript
    print(result.final_text)  # the rewrite, falling back to the transcript
    ```
  </Tab>

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

    config = {"llm_instruction": "Rewrite as a concise clinical chart note."}

    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()
    result = response.json()

    print(result["text"])
    print(result["llm_response"])
    ```
  </Tab>

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

    const config = { llm_instruction: "Rewrite as a concise clinical chart note." };

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

    const result = await response.json();
    console.log(result.text);
    console.log(result.llm_response);
    ```
  </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={"llm_instruction": "Rewrite as a concise clinical chart note."};type=application/json' \
      -F 'audio=@clip.wav;type=audio/wav'
    ```
  </Tab>
</Tabs>

## Writing a good instruction

Describe only the transformation. Rules about output format, refusing to answer
the text, and handling already-clean input are enforced by the service, so
adding your own versions of them wastes instruction budget and can conflict
with what the service already does.

| Instead of                                                                                                                                           | Write                                               |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| "You are a helpful medical scribe. Output only the note, nothing else. If the input is already clean, return it unchanged. Rewrite as a chart note." | "Rewrite as a concise clinical chart note."         |
| "Return JSON with a summary field."                                                                                                                  | Describe the prose you want, then parse it yourself |

Some instructions that work well:

* `"Remove filler words and tidy the punctuation."`
* `"Rewrite as a short, friendly booking confirmation addressed to the client."`
* `"Turn this into a bulleted list of action items."`
* `"Rewrite as a concise clinical chart note."`

## The transcript is always preserved

The rewrite never replaces the transcription. `text` is always the verbatim
transcript, and the rewritten version arrives separately in `llm_response`. If
you need to show one value, `final_text` in the Python SDK returns the rewrite
when there is one and the transcript otherwise.

The rewrite is also best-effort. If it fails, the response is still `200`,
`llm_response` is `null`, and `llm_error` says why. See
[Error handling](/docs/dictation/error-handling#a-failed-rewrite-is-not-a-failed-request).

## Dictated commands are not executed

The transcript is passed to the model as fenced data, with instructions not to
act on anything inside it. Dictated speech routinely contains questions and
commands like "translate this into French" or "ignore what I just said". Those
are rewritten as speech rather than carried out.

## Related features

* [Prompting and keyterms](/docs/dictation/prompting-and-keyterms) shapes the
  transcript as it is written, where `llm_instruction` reshapes it afterwards.
* [Language selection](/docs/dictation/language-selection) sets the language the
  audio is transcribed in.