AI Humanizer API: Humanize Text Programmatically With ClearPen

Some writing never touches a browser tab. It lives in a CMS, a content pipeline, a spreadsheet of product descriptions or an internal tool. ClearPen's Humanize API brings the same humanizer that powers the web app to those workflows — with one difference from most humanizer APIs: every response tells you the AI score before and after.

What the ClearPen API Does

The API exposes a single operation: humanize a piece of text. It runs ClearPen's full block-based pipeline — the same one described in how ClearPen's humanizer works — and returns structured JSON.

Because the response includes the before and after scores, your own systems can make decisions with them: flag items that started high, log the improvement, or route anything that is still amber to a human editor.

Quick Start

1. Create an API key

In the ClearPen dashboard, open Settings → API & Developers and create a key. The full secret, beginning cp_live_, is shown once — store it in your secrets manager. Keys can be revoked from the same screen at any time.

2. Send a request

curl https://www.clearpen.ai/api/v1/humanize \
  -H "Authorization: Bearer cp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our platform leverages cutting-edge technology to streamline workflows and drive meaningful outcomes for teams of every size."
  }'

3. Read the response

{
  "id": "9f1c…",
  "text": "Our platform takes the busywork out of your team's day…",
  "aiScoreBefore": 96,
  "aiScoreAfter": 4,
  "wordCount": 142,
  "processingTimeMs": 18450,
  "usage": {
    "wordsUsed": 12842,
    "wordsLimit": 80000,
    "wordsRemaining": 67158
  }
}

(Values are illustrative.)

Request and Response Reference

Errors

Errors return a non-2xx status and a JSON body of the form { "error": "...", "code": "..." }.

Integration Tips

• Keep keys server-side. Never ship a key in browser code or a public repository.
• Use a generous timeout. Most requests finish in well under a minute, but long documents are processed block by block, so allow a few minutes before timing out.
• Retry with backoff on 429 rate_limited and 500 pipeline_error.
• Use the scores. Store aiScoreBefore and aiScoreAfter alongside each item so you can report on improvement and route anything still above your threshold to an editor.
• Split very long content into sections under your plan's per-request limit, ideally at heading boundaries.

Common Use Cases

• Content operations: humanize AI-assisted drafts as they move from draft to review in a CMS.
• Product and catalog copy: refine large batches of descriptions so they read naturally and consistently.
• Internal tools: add a "refine and score" step to an in-house writing assistant.
• Quality reporting: track before-and-after scores across a content library over time.

Use the API to refine writing you or your team are responsible for, within your organization's policies on AI use. It is not intended for mass-producing content.

Plans and Usage

The Humanize API is included on Pro and Power plans. There is no separate API subscription: words processed through the API come out of the same monthly allowance as the web app, and one-time word packs top up both. See pricing for current limits.

Related Reading

• Humanize API documentation
• What is ClearPen?
• Why ClearPen shows a before-and-after AI score