API Documentation

Everything you need to integrate the AI Humanizer API

Complete guide to our powerful API endpoints, authentication methods, and code examples in your preferred language.

Quick Start

Get up and running with the AI Humanizer API in just a few minutes.

1

Get Your API Key

Sign up for an account at aihumanizerapi.com and generate your API key from the dashboard.

Your API key: Keep it safe and never share it publicly.

2

Install the SDK (Optional)

Choose your preferred SDK or use cURL. We provide official SDKs for Python, Node.js, PHP, and more.

pip install aihumanizer

Or use cURL directly without any SDK installation.

3

Make Your First Request

Send your first API request to humanize AI-generated text:

curl -X POST https://api.aihumanizerapi.com/v1/humanize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is an example of artificial intelligence generated content that needs to be humanized for better readability.",
    "language": "en",
    "intensity": "medium"
  }'

Authentication

All API requests require authentication using your API key. API keys are managed through your dashboard account.

How API Keys Work

Your API key is a unique token that identifies your application to our API. Each request must include your key in the Authorization header using the Bearer scheme.

Header Format

Include the following header in all API requests:

Authorization: Bearer YOUR_API_KEY

Key Management

  • Generate: Create new keys in your account dashboard
  • Rotate: Regenerate existing keys to invalidate old ones
  • Scope: Each key can be restricted to specific endpoints
  • Security: Store keys securely, use environment variables in production

Security Best Practices

  • Never hardcode API keys in your source code
  • Use environment variables or secure vaults
  • Rotate keys regularly
  • Use separate keys for development and production
  • Monitor key usage in your dashboard

Endpoints Reference

The AI Humanizer API provides several endpoints for different use cases.

POST /v1/humanize

Humanize a single text input. Convert AI-generated content into more natural, human-like text.

Request Example

{
  "text": "The rapid advancement of artificial intelligence has revolutionized numerous industries worldwide.",
  "language": "en",
  "intensity": "medium",
  "preserve_formatting": true,
  "tone": "professional"
}

Response Example (Success)

{
  "success": true,
  "original_text": "The rapid advancement of artificial intelligence has revolutionized numerous industries worldwide.",
  "humanized_text": "Over recent years, artificial intelligence has rapidly transformed a wide range of industries across the globe.",
  "language": "en",
  "intensity": "medium",
  "processing_time_ms": 245,
  "tokens_used": 18,
  "request_id": "req_1a2b3c4d5e6f7g8h"
}
POST /v1/humanize/batch

Process multiple texts in a single request. Ideal for bulk humanization tasks.

Request Example

{
  "items": [
    {
      "id": "doc_1",
      "text": "The system implements machine learning algorithms for text processing."
    },
    {
      "id": "doc_2",
      "text": "Advanced computational methods enable efficient data analysis."
    }
  ],
  "language": "en",
  "intensity": "high"
}

Response Example

{
  "success": true,
  "batch_id": "batch_5f6g7h8i9j0k1l2m",
  "status": "processing",
  "total_items": 2,
  "processed_items": 0,
  "pending_items": 2,
  "results": [
    {
      "id": "doc_1",
      "original_text": "The system implements machine learning algorithms for text processing.",
      "humanized_text": "This system uses machine learning algorithms to process text efficiently.",
      "status": "completed"
    },
    {
      "id": "doc_2",
      "original_text": "Advanced computational methods enable efficient data analysis.",
      "humanized_text": "With advanced computational techniques, data analysis becomes much more efficient.",
      "status": "completed"
    }
  ]
}
GET /v1/languages

Get a list of supported languages for humanization.

Response Example

{
  "success": true,
  "languages": [
    {
      "code": "en",
      "name": "English",
      "native_name": "English"
    },
    {
      "code": "es",
      "name": "Spanish",
      "native_name": "Español"
    },
    {
      "code": "fr",
      "name": "French",
      "native_name": "Français"
    },
    {
      "code": "de",
      "name": "German",
      "native_name": "Deutsch"
    },
    {
      "code": "it",
      "name": "Italian",
      "native_name": "Italiano"
    },
    {
      "code": "pt",
      "name": "Portuguese",
      "native_name": "Português"
    },
    {
      "code": "ja",
      "name": "Japanese",
      "native_name": "日本語"
    },
    {
      "code": "zh",
      "name": "Chinese",
      "native_name": "中文"
    }
  ],
  "total_languages": 8
}
GET /v1/usage

Retrieve your current usage statistics and quota information.

Response Example

{
  "success": true,
  "plan": "professional",
  "period": {
    "start": "2024-02-01",
    "end": "2024-02-28"
  },
  "usage": {
    "requests": 5234,
    "tokens": 1254890
  },
  "limits": {
    "requests_per_month": 100000,
    "tokens_per_month": 10000000
  },
  "remaining": {
    "requests": 94766,
    "tokens": 8745110
  },
  "percentage_used": 5.2
}

Code Examples

Complete working examples in your preferred programming language.

Python Example

import requests
import os

# Initialize API client
api_key = os.getenv('AIHUMANIZER_API_KEY')
base_url = 'https://api.aihumanizerapi.com'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Single text humanization
def humanize_text(text, language='en', intensity='medium'):
    endpoint = f'{base_url}/v1/humanize'

    payload = {
        'text': text,
        'language': language,
        'intensity': intensity,
        'preserve_formatting': True,
        'tone': 'professional'
    }

    response = requests.post(endpoint, headers=headers, json=payload)

    if response.status_code == 200:
        result = response.json()
        return result['humanized_text']
    else:
        print(f'Error: {response.status_code}')
        print(response.json())
        return None

# Batch humanization
def humanize_batch(items, language='en', intensity='medium'):
    endpoint = f'{base_url}/v1/humanize/batch'

    payload = {
        'items': items,
        'language': language,
        'intensity': intensity
    }

    response = requests.post(endpoint, headers=headers, json=payload)

    if response.status_code == 200:
        return response.json()
    else:
        print(f'Error: {response.status_code}')
        return None

# Get usage statistics
def get_usage():
    endpoint = f'{base_url}/v1/usage'
    response = requests.get(endpoint, headers=headers)

    if response.status_code == 200:
        return response.json()
    else:
        return None

# Example usage
if __name__ == '__main__':
    # Single text example
    original_text = "The artificial intelligence system processes data using advanced algorithms."
    humanized = humanize_text(original_text)
    print(f"Original: {original_text}")
    print(f"Humanized: {humanized}")

    # Batch example
    batch_items = [
        {'id': '1', 'text': 'Machine learning models require substantial computational resources.'},
        {'id': '2', 'text': 'Neural networks have demonstrated remarkable performance across diverse tasks.'}
    ]
    batch_result = humanize_batch(batch_items)
    print(f"\nBatch Results: {batch_result}")

    # Check usage
    usage = get_usage()
    print(f"\nUsage: {usage}")

Node.js Example

const axios = require('axios');

// Initialize API client
const apiKey = process.env.AIHUMANIZER_API_KEY;
const baseUrl = 'https://api.aihumanizerapi.com';

const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
};

// Single text humanization
async function humanizeText(text, language = 'en', intensity = 'medium') {
    try {
        const response = await axios.post(`${baseUrl}/v1/humanize`, {
            text: text,
            language: language,
            intensity: intensity,
            preserve_formatting: true,
            tone: 'professional'
        }, { headers });

        return response.data.humanized_text;
    } catch (error) {
        console.error('Error:', error.response?.status, error.response?.data);
        return null;
    }
}

// Batch humanization
async function humanizeBatch(items, language = 'en', intensity = 'medium') {
    try {
        const response = await axios.post(`${baseUrl}/v1/humanize/batch`, {
            items: items,
            language: language,
            intensity: intensity
        }, { headers });

        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.status, error.response?.data);
        return null;
    }
}

// Get usage statistics
async function getUsage() {
    try {
        const response = await axios.get(`${baseUrl}/v1/usage`, { headers });
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.status, error.response?.data);
        return null;
    }
}

// Example usage
(async () => {
    // Single text example
    const originalText = 'The artificial intelligence system processes data using advanced algorithms.';
    const humanized = await humanizeText(originalText);
    console.log(`Original: ${originalText}`);
    console.log(`Humanized: ${humanized}`);

    // Batch example
    const batchItems = [
        { id: '1', text: 'Machine learning models require substantial computational resources.' },
        { id: '2', text: 'Neural networks have demonstrated remarkable performance across diverse tasks.' }
    ];
    const batchResult = await humanizeBatch(batchItems);
    console.log(`\nBatch Results:`, batchResult);

    // Check usage
    const usage = await getUsage();
    console.log(`\nUsage:`, usage);
})();

PHP Example

<?php

class AIHumanizerAPI {
    private $apiKey;
    private $baseUrl = 'https://api.aihumanizerapi.com';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    private function makeRequest($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;

        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ];

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        if ($data !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return [
            'status' => $httpCode,
            'data' => json_decode($response, true)
        ];
    }

    public function humanizeText($text, $language = 'en', $intensity = 'medium') {
        $data = [
            'text' => $text,
            'language' => $language,
            'intensity' => $intensity,
            'preserve_formatting' => true,
            'tone' => 'professional'
        ];

        $response = $this->makeRequest('POST', '/v1/humanize', $data);

        if ($response['status'] === 200) {
            return $response['data']['humanized_text'];
        }

        throw new Exception('API Error: ' . $response['status']);
    }

    public function humanizeBatch($items, $language = 'en', $intensity = 'medium') {
        $data = [
            'items' => $items,
            'language' => $language,
            'intensity' => $intensity
        ];

        $response = $this->makeRequest('POST', '/v1/humanize/batch', $data);

        if ($response['status'] === 200) {
            return $response['data'];
        }

        throw new Exception('API Error: ' . $response['status']);
    }

    public function getUsage() {
        $response = $this->makeRequest('GET', '/v1/usage');

        if ($response['status'] === 200) {
            return $response['data'];
        }

        throw new Exception('API Error: ' . $response['status']);
    }
}

// Example usage
try {
    $apiKey = getenv('AIHUMANIZER_API_KEY');
    $client = new AIHumanizerAPI($apiKey);

    // Single text example
    $originalText = 'The artificial intelligence system processes data using advanced algorithms.';
    $humanized = $client->humanizeText($originalText);
    echo "Original: $originalText\n";
    echo "Humanized: $humanized\n\n";

    // Batch example
    $batchItems = [
        ['id' => '1', 'text' => 'Machine learning models require substantial computational resources.'],
        ['id' => '2', 'text' => 'Neural networks have demonstrated remarkable performance across diverse tasks.']
    ];
    $batchResult = $client->humanizeBatch($batchItems);
    echo "Batch Results:\n";
    echo json_encode($batchResult, JSON_PRETTY_PRINT) . "\n\n";

    // Check usage
    $usage = $client->getUsage();
    echo "Usage:\n";
    echo json_encode($usage, JSON_PRETTY_PRINT) . "\n";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

?>

cURL Example

# Set your API key
API_KEY="your-api-key-here"
BASE_URL="https://api.aihumanizerapi.com"

# Single text humanization
curl -X POST $BASE_URL/v1/humanize \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The artificial intelligence system processes data using advanced algorithms.",
    "language": "en",
    "intensity": "medium",
    "preserve_formatting": true,
    "tone": "professional"
  }'

# Batch humanization
curl -X POST $BASE_URL/v1/humanize/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "1",
        "text": "Machine learning models require substantial computational resources."
      },
      {
        "id": "2",
        "text": "Neural networks have demonstrated remarkable performance across diverse tasks."
      }
    ],
    "language": "en",
    "intensity": "medium"
  }'

# Get supported languages
curl -X GET $BASE_URL/v1/languages \
  -H "Authorization: Bearer $API_KEY"

# Check usage statistics
curl -X GET $BASE_URL/v1/usage \
  -H "Authorization: Bearer $API_KEY"

Parameters Reference

Complete reference of all available parameters for the humanization endpoints.

Parameter Type Required Description Default Examples
text String Yes The text content to humanize. Maximum 5,000 characters. "The system implements machine learning..."
language String No Language code for the input text. See GET /v1/languages for supported codes. en en, es, fr, de, it, pt, ja, zh
intensity String No How much to humanize the text. Low intensity makes minimal changes, high intensity transforms more significantly. medium low, medium, high
preserve_formatting Boolean No Preserve the original text structure, paragraphs, and line breaks. false true, false
tone String No Set the desired tone of the output text. neutral professional, casual, academic, creative, formal
preserve_keywords Array No List of keywords that should not be modified during humanization. [] ["API", "machine learning"]
domain String No Specify domain for context-aware humanization. general technology, medical, legal, finance, education
webhook_url String No URL to send webhook notification when processing completes (batch requests only). null "https://yourdomain.com/webhook"

Response Codes

Standard HTTP status codes and error responses from the API.

Status Code Meaning Description Example Response
200 OK Request completed successfully. { "success": true, "humanized_text": "..." }
202 Accepted Batch request accepted and queued for processing. { "success": true, "status": "processing", "batch_id": "..." }
400 Bad Request Invalid request parameters or missing required fields. { "success": false, "error": "Missing required parameter: text" }
401 Unauthorized Invalid or missing API key. { "success": false, "error": "Invalid API key" }
403 Forbidden API key does not have permission for this endpoint. { "success": false, "error": "Permission denied" }
429 Too Many Requests Rate limit exceeded. Check Retry-After header for wait time. { "success": false, "error": "Rate limit exceeded" }
500 Internal Server Error Server encountered an unexpected error. Try again later. { "success": false, "error": "Internal server error" }
503 Service Unavailable Server is temporarily unavailable or undergoing maintenance. { "success": false, "error": "Service temporarily unavailable" }

Error Response Format

All error responses follow this standard format:

{
  "success": false,
  "error": "Error message",
  "error_code": "INVALID_PARAMETER",
  "status_code": 400,
  "details": {
    "parameter": "text",
    "issue": "Text length exceeds maximum of 5000 characters"
  }
}

Rate Limits

API rate limits vary by subscription plan. Rate limits are applied per API key.

Plan Requests/Month Tokens/Month Requests/Minute Price
Free 1,000 100,000 10 Free
Starter 10,000 1,000,000 50 $29/month
Professional 100,000 10,000,000 500 $99/month
Enterprise Unlimited Unlimited Unlimited Custom

Rate Limit Headers

Every API response includes headers that show your current rate limit status:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1645348800
X-RateLimit-Retry-After: 60

Handling Rate Limits

  • X-RateLimit-Remaining: Number of requests remaining in current period
  • X-RateLimit-Reset: Unix timestamp when the rate limit window resets
  • X-RateLimit-Retry-After: Seconds to wait before retrying (on 429 response)
  • Implement exponential backoff: Wait before retrying on rate limit errors

Best Practices

  • Monitor X-RateLimit-Remaining header in your requests
  • Use batch endpoints for processing large volumes of text
  • Implement queue systems for high-volume processing
  • Cache results to avoid redundant API calls
  • Upgrade to a higher plan as your usage grows

SDKs & Libraries

Official SDKs and libraries for popular programming languages.

Python

Official Python SDK with full API support.

pip install aihumanizer

GitHub Repository →

PyPI Package →

Node.js

TypeScript-enabled Node.js SDK with async/await support.

npm install @aihumanizer/node

GitHub Repository →

npm Package →

PHP

Composer package for PHP applications.

composer require aihumanizer/php-sdk

GitHub Repository →

Packagist →

Ruby

Ruby gem for seamless integration.

gem install aihumanizer

GitHub Repository →

RubyGems →

Java

Maven package for Java developers.

<dependency>
  <groupId>com.aihumanizer</groupId>
  <artifactId>java-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

GitHub Repository →

Maven Central →

Go

Go package for high-performance applications.

go get github.com/aihumanizerapi/go-sdk

GitHub Repository →

pkg.go.dev →

Webhooks

Set up webhooks to receive notifications when batch processing completes. Webhooks allow your application to be notified of events without polling the API.

Setting Up Webhooks

Include the webhook_url parameter in your batch request:

{
  "items": [...],
  "language": "en",
  "webhook_url": "https://yourdomain.com/webhooks/humanize-complete"
}

Webhook Payload

When processing completes, we'll send a POST request to your webhook URL with the following payload:

{
  "event": "batch_completed",
  "batch_id": "batch_5f6g7h8i9j0k1l2m",
  "status": "completed",
  "timestamp": "2024-02-07T15:30:45Z",
  "total_items": 2,
  "completed_items": 2,
  "failed_items": 0,
  "results": [
    {
      "id": "doc_1",
      "original_text": "The system implements machine learning algorithms for text processing.",
      "humanized_text": "This system uses machine learning algorithms to process text efficiently.",
      "status": "completed",
      "processing_time_ms": 245
    },
    {
      "id": "doc_2",
      "original_text": "Advanced computational methods enable efficient data analysis.",
      "humanized_text": "With advanced computational techniques, data analysis becomes much more efficient.",
      "status": "completed",
      "processing_time_ms": 198
    }
  ],
  "summary": {
    "average_processing_time_ms": 221.5,
    "total_tokens_used": 48,
    "success_rate": 100.0
  }
}

Webhook Events

Event Description When It Occurs
batch_completed Batch processing finished successfully All items processed
batch_failed Batch processing encountered critical errors Fatal error or max retries exceeded
batch_partial Batch processing completed with some failures Some items failed, others succeeded

Webhook Security

All webhooks include a signature header for verification:

X-Webhook-Signature: sha256=5f8c31d18e0c8f8f8e8e8e8e8e8e8e8e8e8e8e8e

Verifying Webhook Signatures

Verify the signature using your webhook secret:

import hmac
import hashlib

def verify_webhook_signature(payload_str, signature, webhook_secret):
    expected_signature = hmac.new(
        webhook_secret.encode(),
        payload_str.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        signature.split('=')[1],
        expected_signature
    )

# In your webhook handler
@app.route('/webhooks/humanize-complete', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data(as_text=True)
    webhook_secret = os.getenv('WEBHOOK_SECRET')

    if not verify_webhook_signature(payload, signature, webhook_secret):
        return {'error': 'Invalid signature'}, 401

    data = request.get_json()
    # Process the webhook data
    return {'success': True}, 200

Webhook Best Practices

  • Idempotency: Handle duplicate webhook deliveries gracefully
  • Timeouts: Respond to webhooks within 5 seconds
  • Retry Logic: We retry failed webhooks up to 5 times with exponential backoff
  • Verification: Always verify the signature before processing
  • HTTPS: Use HTTPS URLs for webhook endpoints
  • Logging: Log all webhook events for debugging
  • Error Handling: Return appropriate HTTP status codes (2xx for success)

Managing Webhooks

View and manage your webhooks in the webhook settings.

Support & Resources

Documentation

Explore comprehensive guides and tutorials for implementing the API.

View Documentation →

GitHub Examples

Full working examples and sample projects in multiple languages.

Browse Examples →

Community Forum

Connect with other developers and share solutions.

Join Community →

Email Support

Get help from our support team for technical issues.

Contact Support →