API Reference

Complete reference for all UndetectedGPT API endpoints, parameters, and response formats.

POST/api/v1/humanize

Humanize AI-generated text. Accepts text and returns a rewritten version that passes AI detection tools. Requests run on Ghost-2, our newest and most capable model, by default; pass model: "ghost-1" to use the previous generation model instead.

Request body

text

requiredstring

The text to humanize. Maximum 1,000 words by default; your key's actual limit is returned by GET /status as max_words_per_request. Inputs under 5 words are returned unchanged with words_used: 0. Words are counted as word-like segments (so Chinese and Japanese text is counted correctly, not per whitespace).

model

optionalstring

"ghost-2" (default) or "ghost-1". Omit to use Ghost-2, our newest and most capable model. Pass "ghost-1" to keep the previous generation model.

tone

optionalstring

"academic", "balanced", "conversational", "formal", or "creative". Omit (or use "balanced", which is equivalent) for the default style with no tone rewrite. Values are case-insensitive, and "casual" is accepted as an alias of "conversational".

ultra_stealth

optionalboolean

Restructures input before humanization for maximum stealth. Default false. Ignored when a rewrite tone (conversational, formal or creative) is set; the tone wins.

markdown

optionalboolean

Format the output as Markdown. Default true. Set to false to receive raw, unformatted plain text.

spelling

optionalstring

"us" (default), "uk", "uk-oxford", "ca" or "au". Rewrites the output into that variant (colour, centre, organise) and changes nothing but spelling. "uk-oxford" is British with -ize endings (organize, but still analyse). With "us" (or the field omitted) the output comes back in American English. English text only. Values are case-insensitive.

Response

{
  "output": "The humanized text...",
  "words_used": 142,
  "words_remaining": 249858
}

GET/api/v1/status

Check your API key status, remaining word balance, and configuration.

Response

{
  "name": "My App",
  "words_remaining": 249858,
  "max_words_per_request": 1000,
  "rate_limit_per_minute": 50,
  "created_at": "2026-03-18T12:00:00Z",
  "last_used_at": "2026-03-21T15:30:00Z"
}

Parameters & options

The humanization endpoint supports several options to control the output.

Option	Values	Effect
`model`	`ghost-2` (default), `ghost-1`	Which humanizer model processes the text
`tone`	`academic`, `balanced`, `conversational`, `formal`, `creative`	Adjusts writing style while preserving meaning
`ultra_stealth`	`true` / `false`	Extra restructuring pass for harder-to-detect output
`markdown`	`true` / `false`	Markdown formatting (default) vs. raw plain text
`spelling`	`us` (default), `uk`, `uk-oxford`, `ca`, `au`	Spelling variant of the output (English text only)

For most use cases, omitting tone and ultra_stealth produces the best results. Use them when you need specific control over the output.

Rate limits

Rate limits protect the API from abuse and ensure fair access. Exceeding a limit returns 429 Too Many Requests with code: "RATE_LIMITED"; wait briefly before retrying. Per-key values are defaults and configurable per key (check yours via GET /status).

Requests per minute (per key)

50 / min default

Requests per minute (per IP)

60 / min

Max input per request

1,000 words default

Auth failures (per IP)

5 / min

Need higher limits? Contact us for enterprise plans.

Error handling

The API uses standard HTTP status codes. Errors return a JSON body with an error message; most also include a code field.

Status	Code	Description
400	`INVALID_INPUT`	Missing text, or an invalid tone, model, markdown or spelling value
400	`WORD_LIMIT_EXCEEDED`	Text exceeds your key's word limit; the body includes max_words and current_words
400	`INVALID_JSON`	Body could not be parsed as JSON; stringify properly or send Content-Type: text/plain
401	—	Invalid, missing, or revoked API key
403	`INSUFFICIENT_WORDS`	Not enough words in your account balance
413	`BODY_TOO_LARGE`	Request body exceeds 50KB
422	`INPUT_REFUSED`	Input could not be processed (usually malformed or markup-heavy text). Words auto-refunded.
429	`RATE_LIMITED`	Too many requests. Wait and retry.
500	`PROCESSING_ERROR`	Humanization failed. Words auto-refunded.

Response

{
  "error": "Insufficient word balance. You have 12 words remaining, but this request requires 150.",
  "code": "INSUFFICIENT_WORDS",
  "words_remaining": 12,
  "words_required": 150
}

If a request fails after words were deducted (a 500 or 422), they are automatically refunded to your account balance.

Response format

All responses are JSON. Successful responses include output, words_used, and words_remaining. Error responses include error and code.

Success

{
  "output": "The humanized text...",
  "words_used": 142,
  "words_remaining": 249858
}

Error

{
  "error": "Text exceeds word limit. Maximum 1000 words allowed for your API key.",
  "code": "WORD_LIMIT_EXCEEDED",
  "max_words": 1000,
  "current_words": 612
}

Versioning

The current API version is v1. All endpoints are prefixed with /api/v1/.

Breaking changes will be released under a new version prefix. Existing versions continue to work with advance deprecation notice. Non-breaking additions may be added to v1 without a version bump.

SDKs & libraries

No official SDKs at this time. The API uses standard REST conventions and works with any HTTP client.

Language	Recommended client
Python	`requests`
Node.js	`fetch (built-in)`
Go	`net/http (built-in)`
Ruby	`net/http or httparty`
PHP	`guzzlehttp/guzzle`

Next steps

Getting Started

Set up your account and make your first request.

Authentication

API key management and security best practices.

Changelog

See the latest updates and improvements.

Was this page helpful?