> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/interpreting-results/detecting-profanities-in-responses.md).

# Detecting Profanities in Responses

{% hint style="info" %}
This feature requires a Premium Subscription. There is no additional per request cost to use it.
{% endhint %}

Set `include_profanity_filter=1` on a request and Speechace checks the recognized text for profanity and marks the text spans of where it is. Use it to keep your app from showing a learner's profanity back to them, or to flag a response for review.

The feature only reports. It does not change anything else in the response, and it does not return a masked copy of the text. Your application decides whether to mask, hide, or reveal the flagged words.

### How it works

* **Detect and flag.** The response tells you whether profanity was found, how many profane words there are, and exactly where they sit in the text.
* **No impact on scoring or structure.** Every score and every existing field is the same as in a request made without the flag. The flag only adds information.
* **You control redaction.** The recognized text comes back unchanged. Your application applies whatever redaction it wants.

The flag is optional and off by default. When it is not set, the response is unchanged.

### What the flag adds

With `include_profanity_filter=1`, the response gains a `profanity` object next to the recognized text:

<table><thead><tr><th width="150">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>found</code></td><td>Boolean</td><td><code>true</code> if any profanity was detected.</td></tr><tr><td><code>count</code></td><td>Integer</td><td>The number of profane <strong>words</strong>. This can be larger than the number of spans, because adjacent profane words are merged into one span.</td></tr><tr><td><code>redactions</code></td><td>Array</td><td>One <code>{"span": [start, end]}</code> entry per profane word or run of adjacent profane words. Offsets are zero-based character positions, both <strong>inclusive</strong>, into the original recognized text. Empty when nothing is found.</td></tr></tbody></table>

On the audio endpoints, each profane entry in `word_score_list` also gets `"profanity": true`. The word and all of its scores are unchanged.

A span marks the profane word. If the word is wrapped in extra characters, for example `*word*` or `-word-`, the span can include those characters too.

### Endpoints

<table><thead><tr><th width="190">Endpoint</th><th>Recognized text (spans index into this)</th><th>profanity object</th><th>Word-level flag</th></tr></thead><tbody><tr><td><a href="https://api-docs.speechace.com/api-reference/score-speech.md">Score Speech</a></td><td><code>speech_score.transcript</code></td><td><code>speech_score.profanity</code></td><td><code>speech_score.word_score_list[].profanity</code></td></tr><tr><td><a href="https://api-docs.speechace.com/api-reference/score-task.md">Score Task</a></td><td><code>task_score.transcript</code></td><td><code>task_score.profanity</code></td><td><code>speech_score.word_score_list[].profanity</code></td></tr><tr><td><a href="https://api-docs.speechace.com/api-reference/score-writing.md">Score Writing</a></td><td><code>answer</code> (top level)</td><td><code>profanity</code> (top level)</td><td>None (no word list)</td></tr></tbody></table>

A Score Task response carries both a `task_score` and a `speech_score` block. The per-word `word_score_list` lives under `speech_score`, so the word flags are set there. Both blocks share the same transcript.

### Request Format

Send the request to the endpoint you already use, with one extra body parameter. The endpoint depends on the [region](https://api-docs.speechace.com/getting-started/api-regions-and-endpoints.md) of your subscription. For US West the base URL is <https://api.speechace.co>.

`POST` [`https://api.speechace.co/api/scoring/speech/v9/json`](https://api.speechace.co/api/scoring/speech/v9/json)

`POST` [`https://api.speechace.co/api/scoring/task/v9/json`](https://api.speechace.co/api/scoring/task/v9/json)

`POST` [`https://api.speechace.co/api/scoring/writing/v9/json`](https://api.speechace.co/api/scoring/writing/v9/json)

`key`, `dialect` and the other query parameters stay as documented on each endpoint's page. The only addition is a form body field:

<table><thead><tr><th width="215">Parameter</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td>include_profanity_filter</td><td>String</td><td><code>0</code> | <code>1</code><br><em><strong>Optional</strong>: Set to <code>1</code> to detect profanity in the recognized text. Default <code>0</code>.</em></td></tr></tbody></table>

### Request Examples

<table><thead><tr><th width="190">Example</th><th width="330">Request Parameters</th><th>When to use</th></tr></thead><tbody><tr><td>A. Score Speech</td><td><code>user_audio_file=answer.wav</code><br><code>include_profanity_filter="1"</code></td><td><em>Check a spoken answer. Spans index into the transcript and profane words are marked in <code>word_score_list</code>.</em></td></tr><tr><td>B. Score Writing</td><td>Query: <code>task_type=essay-writing</code><br><code>prompt="Describe a recent experience you had with online shopping."</code><br><code>answer="Online shopping is convenient, but the return process is bullshit and the customer support was shit when my order arrived broken."</code><br><code>include_profanity_filter="1"</code></td><td><em>Check written text. Spans index into <code>answer</code>.</em></td></tr></tbody></table>

### Response Examples

The examples below were generated by the live API. Each endpoint is shown with profanity found and with a clean response.

{% tabs %}
{% tab title="A. Speech, profanity found" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "quota_remaining": -1,
  "speech_score": {
    "transcript": "I think the customer service was shit and the whole process was bullshit.",
    "word_score_list": [
      "... (6 more)",
      {
        "word": "shit",
        "quality_score": 100,
        "quality_class": "pass",
        "phone_score_list": [...],
        "syllable_score_list": [...],
        "profanity": true
      },
      "... (5 more)",
      {
        "word": "bullshit",
        "quality_score": 97,
        "quality_class": "pass",
        "phone_score_list": [...],
        "ending_punctuation": ".",
        "syllable_score_list": [...],
        "profanity": true
      }
    ],
    ...,
    "profanity": {
      "found": true,
      "count": 2,
      "redactions": [
        {
          "span": [
            33,
            36
          ]
        },
        {
          "span": [
            64,
            71
          ]
        }
      ]
    }
  },
  "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="B. Speech, clean" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "speech_score": {
    "transcript": "I think the customer service was great and the whole process was smooth.",
    "word_score_list": [...],
    ...,
    "profanity": {
      "found": false,
      "count": 0,
      "redactions": []
    },
    "asr_version": "0.17"
  },
  "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="C. Writing, profanity found" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "essay-writing",
  "task_version": "0.1",
  "answer": "Online shopping is convenient, but the return process is bullshit and the customer support was shit when my order arrived broken.",
  "char_count": 129,
  "writing_score": {...}
  },
  "profanity": {
    "found": true,
    "count": 2,
    "redactions": [
      {
        "span": [
          57,
          64
        ]
      },
      {
        "span": [
          95,
          98
        ]
      }
    ]
  },
  "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="D. Writing, clean" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "essay-writing",
  "task_version": "0.1",
  "answer": "Online shopping is convenient, and the return process was smooth when my order arrived broken. The customer support was very helpful.",
  "char_count": 133,
  "writing_score": {...},
  "profanity": {
    "found": false,
    "count": 0,
    "redactions": []
  },
  "version": "9.17"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

The profane Score Speech response shows the two flagged entries in `word_score_list`. In the transcript, span `[33, 36]` is `shit` and span `[64, 71]` is `bullshit`. A clean response still includes the `profanity` object, with `found: false`, `count: 0` and an empty `redactions` array.

### Processing the response

Score Speech:

{% code overflow="wrap" lineNumbers="true" %}

```python
import requests

url = "https://api.speechace.co/api/scoring/speech/v9/json"
params = {"key": API_KEY, "dialect": "en-us"}
data = {"include_profanity_filter": "1"}

with open("answer.wav", "rb") as f:
    resp = requests.post(url, params=params, data=data,
                         files={"user_audio_file": f}).json()

speech = resp["speech_score"]
prof = speech["profanity"]            # {found, count, redactions}
transcript = speech["transcript"]     # original text, unchanged

def redact(text, redactions, mask="****"):
    # apply spans back to front so earlier offsets stay valid
    for r in sorted(redactions, key=lambda r: r["span"][0], reverse=True):
        start, end = r["span"]        # zero-based, both inclusive
        text = text[:start] + mask + text[end + 1:]
    return text

if prof["found"]:
    print(redact(transcript, prof["redactions"]))
    # "I think the customer service was **** and the whole process was ****."

    # or skip the flagged words when walking word_score_list
    words = [w["word"] for w in speech["word_score_list"] if not w.get("profanity")]
```

{% endcode %}

Score Writing returns the `profanity` object and the original text at the top level, and has no word list:

{% code overflow="wrap" lineNumbers="true" %}

```python
params = {"key": API_KEY, "task_type": "essay-writing"}
data = {
    "prompt": "Describe a recent experience you had with online shopping.",
    "answer": answer_text,
    "include_profanity_filter": "1",
}
resp = requests.post("https://api.speechace.co/api/scoring/writing/v9/json",
                     params=params, data=data).json()

prof = resp["profanity"]              # top level for Score Writing
if prof["found"]:
    print(redact(resp["answer"], prof["redactions"]))
    # "Online shopping is convenient, but the return process is **** and the customer support was **** when my order arrived broken."
```

{% endcode %}

### Notes

* **Language.** Profanity detection is for English. Other languages are not covered yet.
* **What is flagged.** The list targets profanity and common slurs. Mild words such as `damn`, `hell` or `crap` are not flagged.
* **Obfuscation.** Common disguises such as `**1*` or `*-*-*-*` are detected. Stretched letters (`*iiii*`) and letters separated by spaces (`* * * *`) are not guaranteed to be caught, and a spaced-out word can raise `count` above the number of words.
* **Feedback text.** Text that Speechace generates itself, such as `score_explanation` in a Score Task response, comes back with profanity already masked as `****`. These masks are not included in `redactions` or `count`, which describe the recognized text only.
