AI Humanizer API: Humanizer API v2 and Detector API for Developers

The Academic Humanizer AI humanizer API has two REST endpoints for developers and institutions: POST /api/v2/external/humanize, which returns humanized text with sentence-level changes, and POST /api/v2/external/detector, which returns an AI detection assessment for up to 100,000 characters. Both use a server-side API key and draw on the same credit balance as your account.

This post covers who the API is for, how authentication and access control work, what each endpoint returns, and how credits are counted. The full reference lives at /docs.

Who the AI humanizer API is for

The web editor suits individual researchers. The API suits products and teams that handle academic text at volume or inside their own interface:

• Writing platforms that want to offer a humanize step inside their own editor.
• LMS and courseware tools that need an AI detection signal as one input to a human review process, not as an automatic verdict.
• Editing and proofreading services that run client drafts through a consistent first pass before an editor reads them.
• Research offices that want to check grant text or reports in batches.

If your use touches student work, design it so that people make the final decisions. Detector output is evidence to review, and our post on what to consider before questioning student authorship explains why.

Authentication, IP allow-lists and rate limits

Create a key at /api while signed in. The key is shown once, at creation, and Academic Humanizer stores only a hash of it, so copy it straight into your secret manager or a server environment variable. Never ship it in browser or mobile code.

Send the key in the X-API-Key header. That is the header the docs recommend; the server also accepts the key as a bearer token in the Authorization header.

Each request then passes a few checks before any text is processed.

1. Key checkThe key must exist and be active, and the account behind it must be active.
2. IP allow-listIn restricted mode, only requests from the IPs or CIDR ranges you listed are accepted.
3. Rate limitRequests above the per-second limit for the key are rejected with HTTP 429.
4. ProcessingThe text is humanized or analysed, and credits are checked against your balance.
5. Saved resultThe result is saved to your account and returned as JSON.

IP access has two modes: public, where any IP may call with a valid key, and restricted, where only listed IPs or CIDR blocks may. Restricted mode is worth turning on for any production server with a fixed egress address. The default rate limit is 10 requests per second.

The Humanize endpoint

The request body is JSON with one required field, originalContent, and one optional field, researchField. If you send a research field, it must be one of the supported names: Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences, or Medical and Health Sciences. Leave it out or send null if you do not need it.

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

A successful call returns HTTP 201 with a JSON body containing:

• humanizedText: the full rewritten text.
• changedCount: how many sentences were changed.
• sentences: an array of sentence-level entries, each with its start and end offsets in your original text, the source sentence, the humanized sentence, and a changed flag. The array may be empty.

The saved result ID comes back in the X-Humanizer-Id response header, so you can link a request in your system to the saved result in the user's account. Note that changed tells you whether a sentence was rewritten; it is not an AI detection verdict. For that, use the Detector endpoint.

The sentence offsets make it simple to render a diff in your own interface: highlight the changed spans and let the user accept or edit each one. Users should review every output before use, since AI rewriting can introduce errors or shift meaning.

The Detector endpoint

The Detector endpoint takes a single required field, text, up to 100,000 characters. It returns the analysis status, the character count, the elapsed time, an overall document assessment, the detector results, and creditUsed. Research fields are not used here.

A typical pattern is to call Detector first, show the user which passages raise signals, and call Humanize only on the sections they choose. That keeps both cost and change to a minimum.

How API credits are counted

Both endpoints spend credits from the account that owns the key. The two endpoints count differently.

Humanize costs 1 credit per 500 characters, rounded up per request, and is charged only when a complete result is saved. Detector costs 1 credit per 5,000 characters, rounded up. If the balance is too low, the request fails with an insufficient-credits error rather than returning a partial result. Plans and packs are described in how credits and pricing work, and current prices are on /pricing.

Errors you should handle

Error bodies include a short machine-readable code, so branch on the code rather than the message text.

Frequently asked questions

How do I get an API key?

Sign in and open /api. Create a key, copy it immediately (it is shown only once), and store it on your server.

Can I restrict which servers use my key?

Yes. Switch IP access to restricted mode and list the IPs or CIDR ranges allowed to call the API. Requests from anywhere else are rejected with HTTP 403.

Is there a free tier for the API?

The API uses the same credits as the web app. New accounts receive 10 free credits once, which is enough to test the Humanize endpoint on a few short passages.

Which detectors is the output checked against?

Academic Humanizer is validated against Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling and Originality.ai. As with any tool, results vary by detector and no outcome is guaranteed.

Building with Academic Humanizer

If your product already handles manuscripts, abstracts or coursework, the API lets you add a humanize step or a detection check without sending users elsewhere. Start with a test key, run a few real paragraphs through both endpoints, and read the full reference at /docs before you go to production.