Undetector API Documentation - Complete Developer Guide

Contents

API Documentation

Welcome to Undetector API

Undetector provides a powerful text humanization API to help developers transform AI-generated content into more natural, human-like text. Our API uses an asynchronous processing model, supports high concurrency, and offers 99.9% service availability.

99.9%
Service Availability
<500ms
Average Response Time
20K+
Max Character Limit

Basic Information

  • Base URL: https://api.undetector.com/v1
  • Authentication: Bearer Token (API Key)
  • Request Format: JSON
  • Response Format: JSON

Quick Start

  1. 1. Register an account to get your API Key
  2. 2. Read the Authentication section to learn how to use it
  3. 3. Check out the code examples to start integrating
  4. 4. Test your API calls

Authentication

All API requests require an API Key in the request header. You can create and manage your API Keys in the user dashboard.

Request Headers

http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Security Tip: Keep your API Key safe and never expose it in client-side code. It is recommended to use your API Key on the server side.

Humanize API

Submit a Humanization Task

POST /humanize

Submit a text humanization task. Since processing may take some time, the API uses an asynchronous model and immediately returns a task ID. You can use the task ID to query the processing status and result.

Request Parameters

json
{
  "text": "This is AI-generated content that needs to be humanized...",
  "model": "humanize-pro",
  "options": {
    "rewrite_level": "Complete",
    "readability": "Broad audience",
    "purpose": "General writing",
    "output_language": "English"
  },
  "callback_url": "https://your-domain.com/webhook/humanize"
}
ParameterTypeRequiredDescription
textstringYesText to be humanized, up to 20,000 characters
modelstringNoModel name: humanize-pro(default) or humanize-lite
optionsobjectNoProcessing options (see detailed options below)
callback_urlstringNoCallback URL after task completion

Options Parameter Details

The options object allows you to fine-tune the humanization process. All options are optional and have sensible defaults.

Complete Options Example
json
{
  "text": "Your AI-generated content here...",
  "model": "humanize-pro",
  "options": {
    "rewrite_level": "Complete",
    "readability": "Broad audience",
    "purpose": "General writing",
    "output_language": "English"
  }
}
OptionTypeDefaultValuesDescription
rewrite_levelstringCompleteMinor(30%), Partial(60%), Complete(90%)How much the text should be rewritten
readabilitystringBroad audienceBroad audience、College Student、Professional、MarketingTarget reading level for the output
purposestringGeneral writingGeneral writing、Essays、Blog Article、Report、Email、Resume、Holiday Wishes、Tiktok Post、Marketing Email、Ecommerce、Cover Letter、Proposals、Medical reports、Legal contracts、Sales pitchesThe intended purpose or context of the text
output_languagestringEnglishEnglish, Spanish, French, German, Chinese, Japanese, etc.Language for the humanized output
✨ Tips for Better Results
  • • Use Complete rewrite level for heavily AI-generated content
  • • Match the readability level to your target audience
  • • Choose purpose based on your content type

Response Example

json
{
    "success": true,
    "data": {
        "status": "pending",
        "task_id": "taskid_abcdefg"
    },
    "meta": {
        "created_at": "2025-09-15T08:49:50.277Z",
        "request_id": "requestid_abcdefg"
    }
}

Query Task Status

GET /tasks/{task_id}

Use the task ID to query the processing status and result. Task statuses include: pending, processing, completed, and failed.

Response Example

json
{
    "success": true,
    "data": {
        "completed_at": "2025-09-15T08:49:52Z",
        "created_at": "2025-09-15T08:49:50Z",
        "model": "humanize-pro",
        "output_text": "output text here...",
        "processing_time_ms": 2176,
        "status": "completed",
        "token_cost": 350,
        "word_cost": 262
    }
}

Options Reference

The options parameter allows you to customize how your text is humanized. Use these settings to achieve the best results for your specific use case.

🎯 Content Purpose Options

General writing: For everyday content and mixed purposes (Default)
Essays: For academic essays and formal writing
Blog Article: For blog posts and online content
Report: For business and research reports
Email: For professional and personal emails
Resume: For CV and resume content
Marketing Email: For promotional communications
Ecommerce: For product descriptions and sales content
Cover Letter: For job application letters
Proposals: For business proposals and plans
Medical reports: For healthcare documentation
Legal contracts: For legal documents
Sales pitches: For sales presentations
Holiday Wishes: For festive greetings
Tiktok Post: For social media content

📚 Readability Levels

Broad audience: Accessible to most readers (Default)
College Student: University-level vocabulary and complexity
Professional: Business and industry-specific language
Marketing: Engaging, persuasive writing style

⚡ Rewrite Intensity

Minor (30%): Light editing with minimal structural changes
Partial (60%): Moderate rewriting with balanced improvements
Complete (90%): Comprehensive rewriting (Default, Recommended)

🌍 Language Support

English: Default output language
Spanish: Español translation and humanization
French: Français translation and humanization
German: Deutsch translation and humanization
Chinese: 中文 translation and humanization
Japanese: 日本語 translation and humanization
And more: Additional languages supported

💡 Best Practice Examples

📖 Academic Essays

json
{
  "rewrite_level": "Complete",
  "readability": "College Student",
  "purpose": "Essays",
  "output_language": "English"
}

📝 Blog Article

json
{
  "rewrite_level": "Partial",
  "readability": "Broad audience",
  "purpose": "Blog Article",
  "output_language": "English"
}

💼 Business Report

json
{
  "rewrite_level": "Complete",
  "readability": "Professional",
  "purpose": "Report",
  "output_language": "English"
}

📧 Marketing Email

json
{
  "rewrite_level": "Complete",
  "readability": "Marketing",
  "purpose": "Marketing Email",
  "output_language": "English"
}

🛍️ Ecommerce Content

json
{
  "rewrite_level": "Partial",
  "readability": "Marketing",
  "purpose": "Ecommerce",
  "output_language": "English"
}

📱 TikTok Post

json
{
  "rewrite_level": "Minor",
  "readability": "Broad audience",
  "purpose": "Tiktok Post",
  "output_language": "English"
}

🚨 Common Mistakes to Avoid

  • • Don't use "Professional" readability for casual content like TikTok posts
  • • Avoid "Complete" rewrite level for content that needs to preserve original structure
  • • Don't mix formal purposes (Essays, Legal contracts) with casual readability levels
  • • Choose appropriate purpose - use "Marketing Email" not "Email" for promotional content
  • • Match rewrite level to content type: Minor for social media, Complete for formal documents

Error Handling

All error responses follow a unified format, including error code, message, and details.

Error Response Format

json
{
    "success": false,
    "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Invalid API key",
        "request_id": "028497c9-f019-4a5f-856e-b6b390035311"
    }
}

Common Error Codes

Error CodeHTTP StatusDescription
AUTHENTICATION_ERROR401Authentication failed, API Key is invalid or expired
VALIDATION_ERROR400Request parameter validation failed
RATE_LIMIT_EXCEEDED429Rate limit exceeded
TASK_NOT_FOUND404Task not found
INTERNAL_ERROR500Internal server error

Code Examples

JavaScript / Node.js

javascript
// Install dependency: npm install axios
const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.undetector.com/v1';

// Submit a humanization task with options
async function humanizeText(text, model = 'humanize-pro', options = {}) {
  try {
    const defaultOptions = {
      rewrite_level: 'Complete',
      readability: 'Broad audience',
      purpose: 'General writing',
      output_language: 'English'
    };

    const response = await axios.post(`${BASE_URL}/humanize`, {
      text: text,
      model: model,
      options: { ...defaultOptions, ...options }
    }, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });

    console.log('Task submitted:', response.data.data.task_id);
    return response.data.data.task_id;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

// Query task status
async function getTaskStatus(taskId) {
  try {
    const response = await axios.get(`${BASE_URL}/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });

    return response.data.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

// Full example: submit task and wait for completion
async function humanizeAndWait(text) {
  const taskId = await humanizeText(text);

  console.log('Waiting for processing...');
  while (true) {
    const task = await getTaskStatus(taskId);

    if (task.status === 'completed') {
      console.log('Processing complete!');
      return task.output_text;
    } else if (task.status === 'failed') {
      throw new Error('Task failed: ' + task.error_message);
    }

    // Wait 5 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

// Usage examples
(async () => {
  try {
    // Basic usage
    const result1 = await humanizeAndWait(
      'This is some AI-generated content that needs humanization.'
    );
    console.log('Humanized result:', result1);

    // With custom options for academic essay
    const result2 = await humanizeText(
      'Academic paper content here...',
      'humanize-pro',
      {
        purpose: 'Essays',
        readability: 'College Student',
        rewrite_level: 'Complete'
      }
    );
    console.log('Academic task submitted:', result2);

    // For blog content
    const result3 = await humanizeText(
      'Blog post content here...',
      'humanize-lite',
      {
        purpose: 'Blog Article',
        readability: 'Broad audience',
        rewrite_level: 'Partial'
      }
    );
    console.log('Blog task submitted:', result3);

    // For marketing email
    const result4 = await humanizeText(
      'Marketing email content here...',
      'humanize-pro',
      {
        purpose: 'Marketing Email',
        readability: 'Marketing',
        rewrite_level: 'Complete'
      }
    );
    console.log('Marketing task submitted:', result4);

  } catch (error) {
    console.error('Failed:', error.message);
  }
})();

Python

python
# Install dependency: pip install requests
import requests
import time
import json

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.undetector.com/v1'

def humanize_text(text, model='humanize-pro', options=None):
    """Submit a humanization task with customizable options"""
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    default_options = {
        'rewrite_level': 'Complete',
        'readability': 'Broad audience',
        'purpose': 'General writing',
        'output_language': 'English'
    }

    # Merge with custom options if provided
    if options:
        default_options.update(options)

    data = {
        'text': text,
        'model': model,
        'options': default_options
    }

    response = requests.post(f'{BASE_URL}/humanize',
                           headers=headers,
                           json=data)

    if response.status_code == 200:
        result = response.json()
        print(f"Task submitted: {result['data']['task_id']}")
        return result['data']['task_id']
    else:
        raise Exception(f"Request failed: {response.text}")

def get_task_status(task_id):
    """Query task status"""
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }

    response = requests.get(f'{BASE_URL}/tasks/{task_id}',
                          headers=headers)

    if response.status_code == 200:
        return response.json()['data']
    else:
        raise Exception(f"Query failed: {response.text}")

def humanize_and_wait(text):
    """Submit task and wait for completion"""
    task_id = humanize_text(text)

    print("Waiting for processing...")
    while True:
        task = get_task_status(task_id)

        if task['status'] == 'completed':
            print("Processing complete!")
            return task['output_text']
        elif task['status'] == 'failed':
            raise Exception(f"Task failed: {task['error_message']}")

        # Wait 5 seconds before checking again
        time.sleep(5)

# Usage examples
if __name__ == "__main__":
    try:
        # Basic usage
        result1 = humanize_and_wait(
            "This is some AI-generated content that needs humanization."
        )
        print("Humanized result:", result1)

        # Academic essay with custom options
        academic_options = {
            'purpose': 'Essays',
            'readability': 'College Student',
            'rewrite_level': 'Complete'
        }
        task_id1 = humanize_text(
            "Research findings indicate significant correlations...",
            'humanize-pro',
            academic_options
        )
        print("Academic task submitted:", task_id1)

        # Blog article
        blog_options = {
            'purpose': 'Blog Article',
            'readability': 'Broad audience',
            'rewrite_level': 'Partial'
        }
        task_id2 = humanize_text(
            "Hey everyone! Today I want to talk about...",
            'humanize-lite',
            blog_options
        )
        print("Blog task submitted:", task_id2)

        # Business report
        business_options = {
            'purpose': 'Report',
            'readability': 'Professional',
            'rewrite_level': 'Complete'
        }
        task_id3 = humanize_text(
            "The quarterly analysis shows...",
            'humanize-pro',
            business_options
        )
        print("Business task submitted:", task_id3)

        # TikTok post
        tiktok_options = {
            'purpose': 'Tiktok Post',
            'readability': 'Broad audience',
            'rewrite_level': 'Minor'
        }
        task_id4 = humanize_text(
            "Check out this amazing life hack!",
            'humanize-lite',
            tiktok_options
        )
        print("TikTok task submitted:", task_id4)

    except Exception as e:
        print("Failed:", str(e))

cURL

bash
# Basic humanization task
curl -X POST "https://api.undetector.com/v1/humanize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is some AI-generated content that needs humanization.",
    "model": "humanize-pro",
    "options": {
      "rewrite_level": "Complete",
      "readability": "Broad audience",
      "purpose": "General writing"
    }
  }'

# Academic essay example
curl -X POST "https://api.undetector.com/v1/humanize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Research methodology involves systematic approaches...",
    "model": "humanize-pro",
    "options": {
      "rewrite_level": "Complete",
      "readability": "College Student",
      "purpose": "Essays",
      "output_language": "English"
    }
  }'

# Blog article example
curl -X POST "https://api.undetector.com/v1/humanize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Today I want to share some tips about productivity...",
    "model": "humanize-lite",
    "options": {
      "rewrite_level": "Partial",
      "readability": "Broad audience",
      "purpose": "Blog Article",
      "output_language": "English"
    }
  }'

# Response example:
# {"success":true,"data":{"task_id":"task_abc123def456","status":"pending",...}}

# Query task status
curl -X GET "https://api.undetector.com/v1/tasks/task_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Started with Undetector API

Register for a free account, get your API Key, and start integrating our text humanization service.

Get Started