Humanizations

Humanizations are the core resource of the ToHuman API. Each humanization takes AI-generated text and transforms it into natural, human-sounding writing that bypasses AI detectors.

The humanization model

The humanization model contains all the information about a humanization job, including the input content, output result, status, and processing metadata.

Properties

string

Unique identifier for the humanization.

status

string

One of pending, processing, completed, or failed.

intensity

string

Humanization intensity. One of minimal, subtle, medium (default), or heavy.

output_content

string or null

The humanized text. null until the job completes.

processing_time

float or null

Time taken to process in seconds.

error_message

string or null

Error details if the job failed.

created_at

timestamp

When the humanization was created.

completed_at

timestamp or null

When the humanization completed.

scores

object (only when available)

Quality metrics for the humanized text, measured at generation time. Omitted on humanizations processed before scoring existed. See Quality scores.

Quality scores

For every request, the model generates several candidate rewrites, scores each against an AI detector, and returns the strongest one. The scores object tells you how that winning text measures up:

detectability

float, 0–1

How likely the output is to be flagged as AI-written, as scored by a state-of-the-art detector. Lower is better — 0.05 reads as human, values above 0.5 may be flagged. Averaged across paragraphs.

change_ratio

float, 0–1

How much of your text was reworked, as a normalized edit distance from the input. 0.40 means roughly 40% of the characters changed. Higher intensities produce higher ratios.

quality_fallbacks

integer

Number of paragraphs where no candidate met our quality bar, so the best available one was used instead. Usually 0. If it's higher, re-running those sections — or raising the intensity — typically resolves it.

Create a humanization (sync) POST /v1/humanizations/sync

Create a humanization and receive the result immediately. Best for short content (under 2,000 words) when you need real-time results.

Required attributes

content

string

The AI-generated text to humanize. Must be under 2,000 words — use the async endpoint for longer content.

Optional attributes

title

string

A title for the document (for your reference).

intensity

string

Humanization intensity. Defaults to medium. Options: minimal, subtle, medium, heavy.

POST /v1/humanizations/sync

curl -X POST https://tohuman.io/api/v1/humanizations/sync \
  -H "Authorization: Bearer $TOHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The utilization of artificial intelligence...",
    "intensity": "medium"
  }'

Response

{
  "id": 42,
  "document_id": 15,
  "status": "completed",
  "output_content": "Using AI in everyday work...",
  "processing_time": 5.42,
  "scores": {
    "detectability": 0.06,
    "change_ratio": 0.41,
    "quality_fallbacks": 0
  }
}

Create a humanization (async) POST /v1/humanizations

Create a humanization job that processes in the background. Use this for longer documents or when you don't need immediate results. Optionally provide a webhook_url to be notified when processing completes.

Additional attributes

webhook_url

string (optional)

URL to receive a POST request when the humanization completes or fails.

POST /v1/humanizations

curl -X POST https://tohuman.io/api/v1/humanizations \
  -H "Authorization: Bearer $TOHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your long-form AI-generated content...",
    "intensity": "heavy",
    "webhook_url": "https://yourapp.com/webhooks/tohuman"
  }'

Response (202 Accepted)

{
  "id": 43,
  "document_id": 16,
  "status": "pending",
  "message": "Humanization enqueued"
}

Retrieve a humanization GET /v1/humanizations/:id

Retrieve the current state of a humanization by its ID. Use this to poll for the result of an async humanization job.

GET /v1/humanizations/43

curl https://tohuman.io/api/v1/humanizations/43 \
  -H "Authorization: Bearer $TOHUMAN_API_KEY"

Response

{
  "id": 43,
  "document_id": 16,
  "status": "completed",
  "intensity": "heavy",
  "output_content": "The fully humanized content...",
  "processing_time": 7.87,
  "error_message": null,
  "created_at": "2026-03-21T12:00:00Z",
  "completed_at": "2026-03-21T12:00:08Z",
  "scores": {
    "detectability": 0.04,
    "change_ratio": 0.47,
    "quality_fallbacks": 0
  }
}