Humanize

Humanize is an API that rewrites AI-generated text to sound more natural and human. Submit text and get back targeted modifications that remove telltale AI patterns -- overly formal vocabulary, repetitive transitions, rigid structure -- while preserving the original meaning, tone, and factual content.

Key Benefits

• Targeted modifications: Surgical changes to specific phrases, not wholesale rewrites
• Style preservation: Matches the original tone, formality, and voice
• Transparent changes: Every modification includes reasoning and exact text locations
• Style guide support: Optional parameter to direct the rewriting toward a specific voice
• Iterative refinement: AI agent reviews and refines across multiple passes
• Two-step completion: Agent reviews the full rewritten text before confirming

Quick Example

# Submit text for humanization
curl -X POST https://api.feeds.onhelix.ai/humanize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "It is worth mentioning that leveraging robust strategies can optimize outcomes."
  }'

# Retrieve results (after polling status to completion)
curl "https://api.feeds.onhelix.ai/humanize/{jobId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

See the Quickstart Guide for a complete walkthrough.

How Humanization Works

When you submit a humanize request, an AI agent analyzes your text and makes targeted modifications across multiple iterations.

Text Analysis

The agent identifies common signals of AI-generated writing:

• Vocabulary: Overuse of formal verbs ("utilize", "facilitate", "leverage"), generic adjectives ("robust", "comprehensive", "seamless"), and hedging phrases ("It is important to note that")
• Structure: Uniform sentence length, rigid paragraph patterns, excessive parallelism
• Transitions: Repetitive formal connectives ("Furthermore", "Moreover", "Additionally")
• Tone: Unnaturally balanced perspectives, excessive qualification, lack of contractions where natural

Iterative Modification

The agent submits modifications in batches. Each batch contains targeted replacements applied simultaneously against the current text state. After each batch:

1. The text is updated with all modifications from the batch
2. The agent sees a snapshot of the changed sections with surrounding context
3. The agent decides whether to submit another batch or mark the text as complete

Fragment Addressing

Each modification uses a text fragment to locate the exact text to replace:

• prefix: A few words immediately before the target text
• match: The exact text being replaced
• suffix: A few words immediately after the target text

The combination of prefix + match + suffix must appear exactly once in the current text, ensuring precise targeting even in documents with repeated phrases.

Force Completion

The system includes safeguards to ensure jobs complete:

• Max iterations: After reaching the configured maximum (default 10), the agent's output is returned as-is
• Consecutive failures: After 3 failed modification attempts in a row, the job completes with whatever modifications have been applied so far

Two-Step Completion

When the agent believes the text is fully humanized, it signals completion. The system then shows the agent the full rewritten text for a final review. The agent can either confirm completion or submit additional modifications if it spots remaining issues.

Style Guide

The optional styleGuide parameter lets you direct the humanizer toward a specific voice or tone. This is useful when the rewritten text needs to match brand guidelines or publication standards.

{
  "text": "Your AI-generated text here...",
  "styleGuide": "Write in a conversational, first-person tone. Use contractions. Keep sentences short and punchy."
}

The style guide is provided to the AI agent as additional context. It does not override the core behavior of removing AI patterns -- it influences how the replacements are written.

Processing Time

Typical processing times depend on text length and the number of iterations needed:

Text Length	Max Iterations	Expected Time
Short (< 500 chars)	10 (default)	30-90 seconds
Medium (500-2000 chars)	10 (default)	1-3 minutes
Long (> 2000 chars)	10 (default)	2-5 minutes

Factors affecting time:

• Number of AI patterns detected
• Text complexity and length
• Number of iterations before the agent is satisfied
• maxIterations setting (fewer iterations = faster, but potentially less thorough)

Limits and Considerations

Limit	Value
Max text length	100,000 characters
Max style guide	2,000 characters
Max jobId length	256 characters
jobId format	Alphanumeric, hyphens, underscores
Max iterations	1-20 (default 10)
Workflow timeout	10 minutes

Idempotency

The jobId parameter supports idempotent requests:

• Submitting the same jobId reconnects to the existing workflow rather than starting a new one
• If the previous job with that jobId failed, the API returns an error asking you to retry with a new jobId
• Without a jobId, a random UUID is generated for each request

Text Normalization

All input text and style guides are normalized using Unicode NFC normalization before processing. This ensures consistent handling of characters that can be represented in multiple ways (e.g., accented characters).

Next Steps

• Quickstart: Get started in under 5 minutes
• API Reference: Complete endpoint documentation
• Authentication: API key best practices