Content filter

Pass content_filter on a Lightning TTS request to have the text checked against a profanity word list before synthesis. Off by default.

Three actions: reject the whole request, let it through and record the match, or remove the matched term and speak the rest.

Request

POST https://api.smallest.ai/waves/v1/tts?model=lightning_v3.1_pro
{
  "text": "...",
  "voice_id": "kaitlyn",
  "content_filter": {
    "enabled": true,
    "action": "reject"   // or "flag", or "redact"
  }
}

Omitting content_filter is the same as disabling it. There is no account-level default that switches it on.

Actions

reject returns HTTP 400 and synthesizes nothing:

{
  "status": "error",
  "error_code": "CONTENT_FILTER_BLOCKED",
  "message": "The submitted text contains content blocked by the profanity filter.",
  "language": "hi",
  "match_count": 1
}

The response reports the number of matches and the locale checked. The matched terms are never returned or logged.

flag synthesizes normally and records the match, so you can measure the false-positive rate on your own traffic before enforcing.

redact removes the matched term and synthesizes the rest. Use it when the surrounding sentence still needs to be spoken — a dynamic field carrying an insult should not take the whole utterance down with it:

// text:  "Hello fucker, your payment of 500 rupees is due."
// spoken: "Hello, your payment of five hundred rupees is due."

The term is deleted, not masked. A placeholder such as *** would itself be read aloud, which defeats the purpose. Punctuation left stranded by the removal is tidied up; the grammar around it is not, so the sentence can still read oddly (see the note below).

If the text contains nothing but matched terms there is nothing left to speak, and the request is rejected like reject — HTTP 400, CONTENT_FILTER_BLOCKED, with redacted_to_empty: true so you can tell it apart from a refusal. Trailing punctuation does not keep such text alive. Check for this if you pass short, fully user-supplied strings.

A redacted request that does produce audio looks exactly like a clean one on the wire — there is no response field saying a term was dropped. If you need to measure that, run flag alongside your own check.

On the WebSocket endpoints a blocked request arrives as a JSON frame carrying the same error_code and match_count.

Endpoint support

On the WebSocket continuation path (context_id) the filter sees one streamed fragment at a time, so a term split across a fragment boundary is not matched. Send whole utterances if you depend on the filter.

A fragment that is only a matched term is rejected on its own: you get a mid-stream status: "error" frame carrying CONTENT_FILTER_BLOCKED and redacted_to_empty: true, while the context stays open and later fragments keep speaking. Clients that treat any error frame as fatal will drop the rest of the stream, so handle this code specifically.

Supported on lightning_v3.1, lightning_v3.1_pro and lightning_v3.1_pro_10_26 (preview).

Matching

Matching is whole-word, not substring, so Scunthorpe, assess and cocktail pass. The lists consulted are the one for the request’s locale plus English, which is always checked because English profanity is common in code-mixed text.

Mild expletives are out of scope by design, and terms whose whole-word form has an everyday sense are deliberately not listed, so the filter favours precision over recall.

A rejected request never reaches the worker, so it costs no synthesis time.

Behaviour during an outage

If no verdict is returned, the request fails open and the audio is synthesized unfiltered rather than the request failing. The event is logged.

This applies to redact too: during such an outage the text is spoken unredacted. If your compliance posture cannot accept that, pair the filter with your own check rather than relying on it alone.

Example

curl -X POST "https://api.smallest.ai/waves/v1/tts?model=lightning_v3.1_pro" \
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your order has been confirmed.",
    "voice_id": "kaitlyn",
    "language": "en",
    "content_filter": { "enabled": true, "action": "reject" },
    "output_format": "mp3"
  }' \
  --output out.mp3

Clean text synthesizes exactly as it would without the parameter. With action: "reject" as above, matching text returns 400 with CONTENT_FILTER_BLOCKED and produces no audio; with flag or redact it returns audio.

Note

• Input only. The filter inspects the text you submit, not the generated audio.
• No custom lists. The lists are server-side and not configurable per account today.
• redact removes only the listed term, not the clause around it. "You are a fucker." becomes "You are a." — no abuse is spoken, but the remaining sentence may read oddly. A pronunciation dictionary is an alternative to redact, not a refinement of it: redaction runs first, so a dictionary entry for a listed term never fires.

Related

• Pronunciation Dictionaries replace specific tokens before synthesis, which is the right tool when you want a chosen replacement rather than removal.
• Math notation is another opt-in normalization flag on the same request.