# Text Polishing Text Polishing removes spoken-language artifacts from a Scribe transcript and returns clear written text. It is optional and is available for `en-US` speech in Fast, Batch, and Live modes. Text Polishing can: - Remove filler words, false starts, and repetition - Improve grammar, punctuation, capitalization, and readability - Condense unnecessarily verbose speech - Reorganize spoken thoughts for clarity - Preserve names, facts, terminology, and intended meaning Text Polishing can't be combined with `config.language_detection`, even when `config.language` is `en-US`. Set `config.language` to `en-US` and omit `language_detection`. Text Polishing does not summarize the transcript or turn spoken instructions into a numbered or bulleted procedure. | Transcript | Polished text | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Hey, Mike, how you? How you doing? | Hey Mike, how are you doing? | | we're supposed to leave yesterday. And then, because of the winds, they canceled our flight | We were supposed to leave yesterday, but because of the winds they canceled our flight. | | patient is a forty two year old um forty two year old female | The patient is a 42-year-old female. | | okay so um after that I think we should go | After that, I think we should go. | ## Enable Text Polishing Add `outputs.text_polishing` as a top-level field alongside `config`. ```json { "file": "https://example.com/audio.mp3", "config": { "language": "en-US", "diarization": true }, "outputs": { "text_polishing": { "enabled": true } } } ``` If `outputs.text_polishing` is omitted or `enabled` is `false`, Scribe returns only the transcript. ## Fast and Batch responses In Fast and Batch modes, each transcription returns one polished result. The original transcript remains under `result` and is never overwritten, and the complete polished text is returned under `outputs.text_polishing.text`. In Fast mode, the response is returned after both transcription and polishing are complete. ```json { "request_id": "3f2b8c1e-7a4d-4e9b-b6f0-1c5d8a2e9b47", "duration_sec": 27.4, "result": { "text_display": "Um, welcome everyone, uh, let's get started.", "segments": [ { "id": "utt_0000", "start": 0.0, "end": 0.9, "channel": 0, "speaker": "Speaker 1", "text": "um, welcome" }, { "id": "utt_0001", "start": 1.0, "end": 2.1, "channel": 0, "speaker": "Speaker 1", "text": "everyone," }, { "id": "utt_0002", "start": 3.5, "end": 6.2, "channel": 0, "speaker": "Speaker 2", "text": "uh, let's get started" } ] }, "outputs": { "text_polishing": { "text": "[Speaker 1] Welcome everyone. [Speaker 2] Let's get started." } } } ``` Batch uses the same `outputs` field. Each completed output file includes its own `outputs.text_polishing.text` value. ## Live responses Enable Text Polishing in `session.update`. ```json { "type": "session.update", "config": { "language": "en-US", "diarization": true }, "audio": { "format": "pcm16" }, "outputs": { "text_polishing": { "enabled": true, "include_transcript": true } } } ``` In Live mode, polished results are delivered in `transcription.completed` events. One polished event can cover several speech items: it uses the first item's `item_id`, its `audio_start_ms` and `audio_end_ms` span all of the covered items, and the later items don't receive their own `transcription.completed` event. Don't wait for a `transcription.completed` event for every `item_id` from `speech_started`. `outputs.text_polishing.text` contains the polished text for the items that event covers, so append each result to your document; a later event does not replace earlier text. ```json { "type": "transcription.completed", "item_id": "a1b2c3d4e5f6", "transcript": "[Speaker 1] um, welcome everyone, glad you could make it", "audio_start_ms": 0, "audio_end_ms": 4200, "transcription_latency_ms": 240, "outputs": { "text_polishing": { "text": "[Speaker 1] Welcome everyone. Glad you could make it." } } } ``` With diarization enabled, Live polishing returns speaker labels as inline `[Speaker N]` tags in both `transcript` and the polished text, rather than in a separate `speaker` field. `include_transcript` is specific to Live and defaults to `false`. When it is `false`, a completed event contains polished text without the original `transcript`. Polishing adds latency: Scribe sends `transcription.completed` only after polishing finishes. ## Speaker and channel tags Polished text keeps speaker and channel labels as inline prefixes: | Configuration | Polished text | | ---------------------------- | --------------------------------------------------------------------------- | | `diarization` enabled | `[Speaker 1] Welcome everyone. [Speaker 2] Let's get started.` | | `channel_separation` enabled | `[channel0] I think we should ship Friday. [channel1] Friday works for me.` | | Both enabled | `[channel0] [Speaker 1L] … [channel1] [Speaker 1R] …` | Consecutive sentences from the same speaker share one tag. A new tag starts when the speaker changes. ## Handle polishing failures Transcription succeeds even when polishing fails. In that case, `outputs.text_polishing.text` contains only a failure marker. Fast still returns HTTP `200`, a Batch file still completes as `FILE_SUCCEEDED`, and a Live session stays open. | Marker | Cause | | ----------------------------------- | ------------------------------------------------------------- | | `[polishing_failed: no_asr_result]` | The transcript was empty or contained only indistinct speech. | | `[polishing_failed: timeout]` | Polishing timed out. | | `[polishing_failed: partial]` | Only part of the text could be polished. | | `[polishing_failed: server_error]` | The polishing service failed. | | `[polishing_failed: error]` | An unknown failure occurred. | Do not display a value that starts with `[polishing_failed:` as polished speech. In Fast and Batch, use `result.text_display` instead. In Live, use `transcript`, which is included only when `include_transcript` is `true`. If the selected locale does not support Text Polishing, Fast and Batch return `400 INVALID_INPUT` without a transcript. Live returns a nonfatal `invalid_config` error and does not apply the session update. ```json { "type": "error", "error": { "code": "invalid_config", "message": "Text polishing is not supported for locale 'zh-CN'", "fatal": false } } ```