Filler word removal

Remove filler words and overlong silences from a finished video with the HeyGen Filler Word Removal API — submit a video, get back one cleaned cut with removal statistics.

Submit a video and get back a cleaned version with the “um”s, “uh”s, and overlong silences cut out. The job transcribes the audio, detects filler words, removes them along with dead air, and renders one finished video — no review step, no edit decisions to make. It’s built for recordings where a human spoke off the cuff: webinars, screen recordings, interviews, all-hands.

Create a Removal Job

• Endpoint: POST /v3/filler-word-removals
• Purpose: Start a removal job for a source video. Returns a filler_word_removal_id to poll.

Quick Example

curl -X POST "https://api.heygen.com/v3/filler-word-removals" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/webinar.mp4" },
    "title": "Q3 webinar — cleaned"
  }'

Response

{
  "data": {
    "filler_word_removal_id": "b4f0c2a91de843f6a2d07c5e8a913f27"
  }
}

The endpoint returns 202 Accepted immediately; the job runs asynchronously.

Request Body

Parameter	Type	Required	Default	Description
video	object	Yes	—	Source video with a speech audio track. Provide as { "type": "url", "url": "https://..." } or { "type": "asset_id", "asset_id": "..." } (from POST /v3/assets — see Upload Assets). Sources up to 2 hours long are supported.
title	string	No	Filler Removal	Display title for the job.
callback_url	string	No	—	Webhook URL — receives a POST when the job completes or fails (filler_word_removal.success / filler_word_removal.fail).
callback_id	string	No	—	Arbitrary ID echoed back in the webhook payload.

Idempotency

Pass an Idempotency-Key header to make retries safe — replaying the same key returns the original job instead of creating a duplicate.

Get a Removal Job

• Endpoint: GET /v3/filler-word-removals/{filler_word_removal_id}
• Purpose: Fetch a job’s live status and, once it completes, the cleaned video plus removal statistics.

Quick Example

curl -X GET "https://api.heygen.com/v3/filler-word-removals/b4f0c2a91de843f6a2d07c5e8a913f27" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Path Parameters

Parameter	Type	Required	Description
filler_word_removal_id	string	Yes	Unique job identifier returned by POST /v3/filler-word-removals.

Response

{
  "data": {
    "id": "b4f0c2a91de843f6a2d07c5e8a913f27",
    "title": "Q3 webinar — cleaned",
    "status": "completed",
    "progress": 100,
    "video_url": "https://files2.heygen.ai/filler-removal/.../output.mp4?Expires=...",
    "thumbnail_url": "https://resource2.heygen.ai/video/thumbnail/....webp",
    "original_duration": 512.6,
    "output_duration": 471.9,
    "num_cuts": 23,
    "reduction_pct": 7.9,
    "created_at": 1785650000
  }
}

Response Fields

Field	Type	Description
id	string	Unique job identifier.
title	string or null	Display title for the job.
status	string	Job lifecycle status: pending, running, completed, or failed.
progress	integer	Approximate progress (0–100). 100 when completed.
video_url	string or null	Pre-signed MP4 download URL of the cleaned video. Present when status is completed.
thumbnail_url	string or null	Pre-signed thumbnail URL, when a thumbnail was generated.
original_duration	number or null	Duration of the source video in seconds.
output_duration	number or null	Duration of the cleaned video in seconds.
num_cuts	integer or null	Number of filler segments removed. Counts filler cuts only — a job that trimmed silences alone reports num_cuts: 0 with a positive reduction_pct.
reduction_pct	number or null	Percentage of the source duration removed.
callback_id	string or null	Client-provided callback ID echoed from the create request. Only present when you supplied one.
created_at	integer	Unix timestamp (seconds) of job creation.
failure_message	string or null	Error description. Only present when status is failed.

video_url is a pre-signed link with a limited lifetime. Download the file soon after the job completes, or re-fetch this endpoint for a fresh link.

A completed job always carries a video_url — when the run finds nothing to cut, the output is a copy of the original video and the charge is automatically refunded, so your polling code never needs a special no-change branch.

Polling Pattern

Removal jobs are processed asynchronously. Poll until status reaches completed or failed.

Status transitions: pending → running → completed | failed

while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/filler-word-removals/$JOB_ID" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

For long recordings, prefer a callback_url over tight polling — HeyGen will POST you the finished job instead (filler_word_removal.success / filler_word_removal.fail webhook events). Treat the webhook as a completion signal and fetch the authoritative result from GET /v3/filler-word-removals/{filler_word_removal_id}.

Asset Inputs

The video field accepts two input formats:

By URL — any publicly accessible HTTPS link:

{ "type": "url", "url": "https://example.com/recording.mp4" }

By asset ID — reference a file previously uploaded via POST /v3/assets (see Upload Assets):

{ "type": "asset_id", "asset_id": "asset_xyz789" }

Either way, the source needs a speech audio track to transcribe and can be up to 2 hours long.

Full Example

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def remove_fillers(video_url, title=None):
    """Start a removal job, wait for it, and return the finished job."""
    body = {"video": {"type": "url", "url": video_url}}
    if title:
        body["title"] = title

    job_id = requests.post(
        f"{BASE}/v3/filler-word-removals", headers=HEADERS, json=body
    ).json()["data"]["filler_word_removal_id"]

    while True:
        job = requests.get(
            f"{BASE}/v3/filler-word-removals/{job_id}", headers=HEADERS
        ).json()["data"]
        if job["status"] in ("completed", "failed"):
            break
        time.sleep(10)

    if job["status"] == "failed":
        raise RuntimeError(job.get("failure_message") or "removal job failed")
    return job


job = remove_fillers("https://example.com/webinar.mp4", title="Q3 webinar — cleaned")
print(f"{job['num_cuts']} cuts, {job['reduction_pct']}% shorter -> {job['video_url']}")

Cleaning a recording before repurposing it? Run filler removal first, then hand the cleaned video to AI clipping for highlights — and score the cuts with background music and sound effects from the same Tools suite.