Detect & Humanize Endpoint | Walter Writes API

Combined workflow — detect AI content and automatically humanize if the score exceeds your threshold.

POST /api/detect-and-humanize/

Two-stage pipeline that first detects AI content, then automatically humanizes the text if the AI score exceeds your specified threshold. This is the most efficient option for content quality assurance.

Authentication: X-API-Key header with both humanizer and ai_detector scopes

Request Parameters

Parameter	Type	Required	Description
`content`	string	Yes	Text content to process
`detection_threshold`	float	Yes	AI score threshold (0.0–1.0). Text is humanized only if the AI score exceeds this value
`callback_url`	string	No	URL to receive results asynchronously via webhook
`poll`	boolean	No	Set to `true` to enable polling mode (default: `false`)
`webhook_secret`	string	No	Secret sent in `X-Webhook-Secret` header of webhook POST

How It Works

Detect — The AI score is computed for the full text.
Compare — The score is compared against your detection_threshold.
Humanize (conditional) — If ai_score > detection_threshold, the text is humanized. Otherwise, only the detection result is returned.

Processing Modes

The endpoint supports synchronous and asynchronous processing:

Parameters	Mode	Response
(none)	Sync	`200 OK` — result in response body
`callback_url`	Async + webhook	`202 Accepted` — result POSTed to your URL
`poll: true`	Async + polling	`202 Accepted` — result via `GET /api/jobs/{task_id}/`
`callback_url` + `poll: true`	Async + both	`202 Accepted` — result via webhook AND polling

See Async Jobs for details on asynchronous processing.

Synchronous Example

Request

curl -X POST https://developer-portal.walterwrites.ai/api/detect-and-humanize/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": "Artificial intelligence has revolutionized numerous industries by automating complex tasks and enhancing decision-making processes.",
    "detection_threshold": 0.5
  }'

Response — Humanization Performed (200 OK)

When the AI score exceeds the threshold, the text is humanized:

{
  "status": "success",
  "task_id": null,
  "ai_score": 0.87,
  "detection_threshold": 0.5,
  "needs_humanization": true,
  "humanized": true,
  "original_content": "Artificial intelligence has revolutionized numerous industries by automating complex tasks and enhancing decision-making processes.",
  "humanized_content": "AI has transformed many industries, making complex tasks automatic and improving how decisions are made.",
  "detector_service": "detector_service",
  "humanizer_service": "humanizer_service",
  "detection_time": 1.45,
  "humanization_time": 2.12,
  "total_time": 3.57,
  "word_count": 18,
  "credits_remaining": 1982,
  "message": "Text detected as AI-generated (score: 87.00%) and successfully humanized",
  "user": {
    "id": 12345
  }
}

Response — No Humanization Needed (200 OK)

When the AI score is below the threshold:

{
  "status": "success",
  "task_id": null,
  "ai_score": 0.32,
  "detection_threshold": 0.5,
  "needs_humanization": false,
  "humanized": false,
  "content": "I went to the local farmers market this morning and bought fresh vegetables for dinner.",
  "detection_items": [
    {
      "text": "I went to the local farmers market this morning and bought fresh vegetables for dinner.",
      "prediction": "original",
      "ai_score": 0.32
    }
  ],
  "detection_time": 1.38,
  "word_count": 18,
  "credits_remaining": 1982,
  "message": "Text detected as human-written (score: 32.00%). Below threshold (50.00%), no humanization performed.",
  "user": {
    "id": 12345
  }
}

Asynchronous Example

Request

curl -X POST https://developer-portal.walterwrites.ai/api/detect-and-humanize/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": "Your long text here...",
    "detection_threshold": 0.5,
    "poll": true,
    "callback_url": "https://your-server.com/webhook",
    "webhook_secret": "your_secret_123"
  }'

Response (202 Accepted)

{
  "status": "pending",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ai_score": null,
  "detection_threshold": 0.5,
  "needs_humanization": null,
  "detector_service": null,
  "detection_time": null,
  "word_count": 256,
  "credits_remaining": 1744,
  "user": {
    "id": 12345
  }
}

Use the returned task_id to poll for results, or wait for the webhook delivery to your callback_url. The completed result will have the same structure as the synchronous response (humanized or not, depending on the AI score vs threshold).

Response Fields

Always Present

Field	Type	Description
`status`	string	`"success"` (sync), `"pending"` (async), or `"error"`
`task_id`	string \| null	Job ID for async requests; `null` for sync
`ai_score`	float \| null	AI detection score (0.0–1.0)
`detection_threshold`	float	Your specified threshold
`needs_humanization`	boolean \| null	Whether humanization was needed
`detector_service`	string \| null	Detection service used
`detection_time`	float \| null	Detection processing time (seconds)
`word_count`	integer	Word count of input text
`credits_remaining`	integer	Credit balance after this request
`message`	string	Detailed status message
`user.id`	integer	Your user ID

Present When Humanized (`humanized: true`)

Field	Type	Description
`humanized`	boolean	`true`
`original_content`	string	Original input text
`humanized_content`	string	Humanized output text
`humanizer_service`	string	Humanizer service used
`humanization_time`	float	Humanization processing time (seconds)
`total_time`	float	Total processing time (seconds)

Present When Not Humanized (`humanized: false`)

Field	Type	Description
`humanized`	boolean	`false`
`content`	string	Original input text (unchanged)
`detection_items`	array	Sentence-level analysis (same structure as Detector `items`)
`detection_items[].text`	string	Individual sentence text
`detection_items[].prediction`	string	Classification: `"ai-generated"` or `"original"`
`detection_items[].ai_score`	float	AI probability for this sentence (0.0–1.0)

Webhook Delivery

When using callback_url, the completed result is POSTed to your URL as JSON with the same response structure as the synchronous response. If you provided a webhook_secret, it is sent in the X-Webhook-Secret header so you can verify the request originated from WalterAI.

The callback_url must be a publicly routable URL. Requests to private, internal, or reserved IP addresses are blocked for security reasons.

Use Cases

Content Quality Assurance — Automatically improve AI-generated content only when needed.
Batch Processing — Process multiple texts with consistent quality thresholds.
Cost Optimization — Only humanize when detection indicates it's necessary.

Detect & Humanize

On this page