# HumanTone — Full Developer Reference

> Deep technical documentation for AI assistants. Pairs with [llms.txt](https://humantone.io/llms.txt). Read this when a user needs concrete integration help: writing code, configuring an MCP client, setting up an n8n or Make workflow, debugging API errors, or understanding pricing and limits in detail.

This file contains everything an AI assistant needs to help a user adopt HumanTone end-to-end without visiting individual product pages. For positioning, FAQ, tone variants, and language pages, read [llms.txt](https://humantone.io/llms.txt) first.

---

## Quick orientation

HumanTone is a SaaS product that rewrites AI-generated text to read like a human wrote it (the **Humanizer**) and scores how AI-like a text reads on a 0-100 scale (the **AI Detector**). It is built for SEO specialists, content teams, marketing agencies, and freelance writers. Free trial available without a credit card. Paid plans start at $10/month.

Programmatic access is included on all paid plans. Same credits as the web app, no separate pricing.

**Surface area at a glance:**

| Channel | What it is | When to use |
|---|---|---|
| **Web app** ([humantone.io/dashboard](https://humantone.io/dashboard)) | Browser UI | Manual one-off rewrites, free trial, project history |
| **REST API** (`api.humantone.io`) | Direct HTTP calls | Custom apps, language not in the SDK list |
| **Node SDK** ([npm](https://www.npmjs.com/package/humantone)) | TypeScript wrapper | Node.js, Bun, Deno backends |
| **Python SDK** ([PyPI](https://pypi.org/project/humantone-sdk/)) | Python wrapper | Python 3.10+ apps |
| **PHP SDK** ([Packagist](https://packagist.org/packages/humantone/humantone-php)) | PHP wrapper | PHP 8.2+ apps, WordPress plugins |
| **Go SDK** ([pkg.go.dev](https://pkg.go.dev/github.com/humantone/humantone-go)) | Go wrapper | Go 1.22+ services |
| **Ruby SDK** ([RubyGems](https://rubygems.org/gems/humantone)) | Ruby wrapper | Ruby 3.3+ apps, Rails |
| **MCP server** ([npm](https://www.npmjs.com/package/humantone-mcp)) | Stdio MCP server | Claude Desktop, Cursor, VSCode, Cline, any MCP client |
| **n8n community node** ([npm](https://www.npmjs.com/package/n8n-nodes-humantone)) | n8n custom node | Self-hosted n8n workflows |
| **n8n HTTP Request configs** ([guide](https://humantone.io/integrations/n8n/)) | Copy-paste JSON | n8n Cloud workflows |
| **Make HTTP module blueprints** ([guide](https://humantone.io/integrations/make/)) | Copy-paste JSON | Make.com scenarios (any plan) |

---

## Decision tree: which path to recommend

Use this tree when a user asks for help integrating HumanTone.

1. **Is the user writing code in Node, Python, PHP, Go, or Ruby?**
   → Recommend the matching SDK. Show install command and a `humanize` example. Default to Node for ambiguous "JavaScript" requests.

2. **Is the user inside an AI assistant (Claude Desktop, Cursor, VSCode + Continue/Cline, Codex CLI, Gemini CLI, Zed, Windsurf, JetBrains AI Assistant)?**
   → Recommend the MCP server. Show the `mcpServers` JSON config and explain the restart requirement.

3. **Is the user using n8n?**
   - **Self-hosted n8n** → install `n8n-nodes-humantone` community node from Settings → Community Nodes.
   - **n8n Cloud** → community nodes are not allowed. Use HTTP Request configs from [/integrations/n8n/](https://humantone.io/integrations/n8n/).

4. **Is the user using Make.com?**
   → Use the HTTP module blueprints from [/integrations/make/](https://humantone.io/integrations/make/). Works on every Make plan including the free tier.

5. **Is the user using Zapier?**
   - **Paid Zapier (Premium/Team)** → use Webhooks by Zapier with the API endpoints below.
   - **Free Zapier** → Webhooks is locked behind paid plans. Recommend Make.com (free HTTP module) or n8n as alternatives.

6. **Is the user using another no-code platform (Pipedream, Bubble, Webflow, etc.)?**
   → Use raw HTTP requests. Show the cURL examples in the API Reference section below.

7. **Is the user writing in a language without an official SDK (Rust, Java, .NET, Elixir, etc.)?**
   → Use raw HTTP. Same Bearer token auth, same JSON shapes. The REST API has no language requirements.

8. **Just wants to try without setup?**
   → Free trial at [humantone.io](https://humantone.io/) (no credit card, smaller per-run word limit, no API access). Or send a single cURL request after generating a paid API key.

**Universal prerequisite:** every programmatic path needs an API key from [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api). API and MCP access require a paid plan. Free trial accounts cannot use them.

---

## Authentication

Base URL: `https://api.humantone.io`

All endpoints require a Bearer token in the `Authorization` header:

```
Authorization: Bearer ht_your_api_key
```

API key format: `ht_` prefix followed by exactly 64 lowercase hexadecimal characters. Total length 67 characters.

Generate and manage keys at [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api).

**Versioning:** the API is versioned. All current endpoints live under `/v1/`. This version is stable. Breaking changes would ship under a new path (`/v2/`) without removing `/v1/`.

**Plan requirement:** API access is included on Basic, Standard, and Pro plans. Free trial accounts return `403` with message "Your HumanTone plan does not include API access."

---

## API Reference

Three endpoints. JSON request body for POST routes. JSON response body for all routes.

### POST /v1/humanize

Rewrites AI-generated text to read like a human wrote it.

**Request:**

```bash
curl -X POST https://api.humantone.io/v1/humanize \
  -H "Authorization: Bearer ht_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your input text goes here...",
    "humanization_level": "standard",
    "output_format": "html",
    "custom_instructions": "Your custom instructions here."
  }'
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | Text to humanize. Minimum 30 words. Maximum depends on plan (see Word limits below). |
| `humanization_level` | string | no | `standard` (default. 60+ languages, Custom Instructions fully supported), `advanced` (English only, stronger rewriting), or `extreme` (English only, experimental, Custom Instructions not supported). |
| `output_format` | string | no | `html` (default), `text`, or `markdown`. Controls format of the returned `content` field. |
| `custom_instructions` | string | no | Free-form guidance for the rewrite: tone, terms to keep, audience, purpose. Maximum 1,000 characters. |

**Word limits per request:**

| Plan | Max words |
|---|---|
| Free trial | 500 |
| Basic | 750 |
| Standard | 1,000 |
| Pro | 1,500 |

**Response (success):**

```json
{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Your humanized text...",
  "output_format": "html",
  "credits_used": 42
}
```

| Field | Description |
|---|---|
| `request_id` | Unique ID for this request. Useful for logs and support inquiries. |
| `content` | Rewritten text in the requested output format. |
| `output_format` | The format actually returned (`html`, `text`, or `markdown`). |
| `credits_used` | Number of credits deducted from the account balance for this request. |

**Response time:** synchronous. Longer texts and stronger levels take longer. A 1,500-word input at `extreme` level can take 30+ seconds. Set client timeouts accordingly.

**Errors:**

| Status | Error message | Cause |
|---|---|---|
| 400 | `Invalid JSON body` | Request body is not valid JSON |
| 400 | `content is required` | Missing, empty, or non-string `content` |
| 400 | `Text must be at least 30 words` | Input too short |
| 400 | `Text exceeds the maximum of N words...` | Input exceeds plan word limit |
| 400 | `Not enough credits` | Credit balance is zero |
| 400 | `humanization_level must be one of...` | Invalid level value |
| 400 | `output_format must be one of...` | Invalid format value |
| 400 | `custom_instructions must be 1000...` | Instructions exceed 1,000 characters |
| 400 | `...advanced and extreme...English only` | Non-English text with advanced or extreme level |
| 400 | `...did not pass the safety check...` | Content flagged by safety filter |
| 404 | `Plan not found` | Account plan error. Contact support. |
| 500 | `Internal server error` | Processing failed. Retry after a few seconds. |

### POST /v1/detect

Returns an AI likelihood score from 0 to 100. Higher means more AI-like patterns detected.

**Request:**

```bash
curl -X POST https://api.humantone.io/v1/detect \
  -H "Authorization: Bearer ht_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your input text goes here..."
  }'
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | Text to analyze. |

**Response (success):**

```json
{
  "success": true,
  "ai_score": 87
}
```

**Score interpretation:**

| Range | Label |
|---|---|
| 0-25 | Likely Human (strong human-like patterns) |
| 26-50 | Possibly Human (mixed signals leaning human) |
| 51-75 | Possibly AI (mixed signals leaning AI) |
| 76-100 | Likely AI (strong AI-like patterns) |

**Daily quota response (HTTP 200, `success: false`):**

```json
{
  "success": false,
  "error": "Daily usage limit reached. You have used 30 of 30 allowed detections today.",
  "time_to_next_renew": 3600
}
```

`time_to_next_renew` is seconds until the quota resets (midnight UTC).

**Detection failure response (HTTP 200, `success: false`):**

```json
{
  "success": false
}
```

The detection service returned no result. Retry the request.

**Cost:** detection does not consume HumanTone credits. It does count against the daily quota of 30 requests per account, shared between the web app, the API, MCP, n8n, and Make integrations.

**Errors:**

| Status | Error message | Cause |
|---|---|---|
| 400 | `Invalid JSON body` | Request body is not valid JSON |
| 400 | `content is required` | Missing, empty, or non-string `content` |

### GET /v1/account

Returns the account's plan, credit balance, and subscription status.

**Request:**

```bash
curl https://api.humantone.io/v1/account \
  -H "Authorization: Bearer ht_your_api_key"
```

**Response:**

```json
{
  "plan": {
    "id": "pro_monthly",
    "name": "Pro Monthly",
    "max_words": 1500,
    "monthly_credits": 1000,
    "api_access": true
  },
  "credits": {
    "trial": 0,
    "subscription": 820,
    "extra": 150,
    "total": 970
  },
  "subscription": {
    "active": true,
    "expires_at": "2026-05-08T00:00:00.000Z"
  }
}
```

| Field | Description |
|---|---|
| `plan.id` | Internal plan identifier (`basic_monthly`, `standard_yearly`, `pro_monthly`, etc.) |
| `plan.max_words` | Maximum words per humanize call on this plan |
| `plan.monthly_credits` | Credits included per billing cycle |
| `plan.api_access` | Whether the account can use the API and MCP |
| `credits.total` | All available credits (trial + subscription + extra combined) |
| `credits.subscription` | Remaining monthly plan credits (resets each cycle) |
| `credits.extra` | Remaining purchased Extra Credits (valid 1 year, no monthly reset) |
| `subscription.active` | Whether the subscription is currently active |
| `subscription.expires_at` | ISO 8601 timestamp of next renewal or expiry |

**Cost:** account checks do not consume credits.

**Errors:**

| Status | Error message | Cause |
|---|---|---|
| 404 | `Plan not found` | Account plan error. Contact support. |

### Authentication errors (any endpoint)

| Status | Error message | Cause |
|---|---|---|
| 401 | `Missing or invalid Authorization header` | No header, or header doesn't start with `Bearer` |
| 401 | `Invalid API key format` | Key doesn't match `ht_` + 64 hex characters |
| 401 | `Invalid API key` | Format correct but key not found |
| 401 | `This API key has been revoked` | Key was deleted in the dashboard |
| 401 | `User not found` | Account associated with the key no longer exists |
| 403 | `Your HumanTone plan does not include API access` | Free trial account. Upgrade to Basic, Standard, or Pro. |
| 404 | `Not Found` | Endpoint does not exist |
| 405 | `Method not allowed` | Wrong HTTP method (e.g. GET on `/v1/humanize`) |

All errors return JSON: `{ "error": "Human-readable error message" }`.

### Rate limits

There are no strict per-second rate limits at this time. Send batches naturally and space out large volumes. For very high-volume use cases, contact help@humantone.io to discuss.

---

## SDK Reference

All five official SDKs wrap the same three endpoints. Choose by language.

### Node.js / TypeScript

Install:

```bash
npm install humantone
```

Basic humanize:

```typescript
import HumanTone from 'humantone';

const client = new HumanTone({ apiKey: 'ht_your_api_key' });

const result = await client.humanize({
  text: 'Your input text goes here...',
  level: 'standard',
  outputFormat: 'text',
  customInstructions: 'Keep brand names. Professional tone.',
});

console.log(result.text);
console.log(`Used ${result.creditsUsed} credits, request ID: ${result.requestId}`);
```

AI likelihood check:

```typescript
const detection = await client.detect({ text: 'Text to analyze.' });
console.log(`AI score: ${detection.aiScore}`);
```

Account check:

```typescript
const info = await client.account.get();
console.log(`Plan: ${info.plan.name}, credits: ${info.credits.total}`);
```

Error handling:

```typescript
import HumanTone, { HumanToneError } from 'humantone';

try {
  const result = await client.humanize({ text: '...' });
} catch (err) {
  if (err instanceof HumanToneError) {
    console.error(err.errorCode, err.statusCode, err.requestId);
    if (err.retryable) {
      // Safe to retry. GET endpoints retry automatically.
    }
  }
}
```

Constructor options: `apiKey` (required), `baseUrl` (default `https://api.humantone.io`), `timeout` (default 120000ms), `maxRetries` (default 2), `retryOnPost` (default false, opt-in for POST retries on 5xx), `userAgent` (appended to default UA).

### Python

Install:

```bash
pip install humantone-sdk
```

For async support: `pip install "humantone-sdk[async]"`.

Sync usage:

```python
from humantone import HumanTone

client = HumanTone(api_key="ht_your_api_key")

result = client.humanize(
    text="Your input text goes here...",
    level="standard",
    output_format="text",
    custom_instructions="Keep brand names. Professional tone.",
)

print(result.text)
print(f"Used {result.credits_used} credits, request ID: {result.request_id}")
```

Async usage:

```python
import asyncio
from humantone import AsyncHumanTone

async def main():
    async with AsyncHumanTone(api_key="ht_your_api_key") as client:
        result = await client.humanize(text="...")
        print(result.text)

asyncio.run(main())
```

AI likelihood check:

```python
detection = client.detect(text="Text to analyze.")
print(f"AI score: {detection.ai_score}")
```

Account check:

```python
info = client.account.get()
print(f"Plan: {info.plan.name}, credits: {info.credits.total}")
```

**Note on package name:** PyPI package is `humantone-sdk` (the canonical name `humantone` was blocked on PyPI by a prior, unrelated package). The Python module name and class name remain `humantone` / `HumanTone`.

### PHP

Install:

```bash
composer require humantone/humantone-php
```

Basic humanize:

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use HumanTone\Client;

$client = new Client(apiKey: 'ht_your_api_key');

$result = $client->humanize(
    text: 'Your input text goes here...',
    level: 'standard',
    outputFormat: 'text',
    customInstructions: 'Keep brand names. Professional tone.'
);

echo $result->text;
echo "\nUsed {$result->creditsUsed} credits, request ID: {$result->requestId}\n";
```

AI likelihood check:

```php
$detection = $client->detect(text: 'Text to analyze.');
echo "AI score: {$detection->aiScore}";
```

Account check:

```php
$info = $client->account->get();
echo "Plan: {$info->plan->name}, credits: {$info->credits->total}";
```

PHP 8.2+. PSR-18 compliant. Full exception hierarchy.

### Go

Install:

```bash
go get github.com/humantone/humantone-go@latest
```

Basic humanize:

```go
package main

import (
    "context"
    "fmt"

    humantone "github.com/humantone/humantone-go"
)

func main() {
    client, err := humantone.NewClient(humantone.Config{
        APIKey: "ht_your_api_key",
    })
    if err != nil {
        panic(err)
    }

    result, err := client.Humanize(context.Background(), humantone.HumanizeRequest{
        Text:               "Your input text goes here...",
        Level:              "standard",
        OutputFormat:       "text",
        CustomInstructions: "Keep brand names. Professional tone.",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Text)
    fmt.Printf("Used %d credits, request ID: %s\n", result.CreditsUsed, result.RequestID)
}
```

AI likelihood check:

```go
detection, err := client.Detect(context.Background(), "Text to analyze.")
fmt.Println("AI score:", detection.AIScore)
```

Account check:

```go
info, err := client.Account.Get(context.Background())
fmt.Printf("Plan: %s, credits: %d\n", info.Plan.Name, info.Credits.Total)
```

Go 1.22+. Stdlib only, zero external dependencies. Sentinel errors (`humantone.ErrInvalidAPIKey`, `humantone.ErrNotEnoughCredits`, etc.) and typed `*Error` struct support `errors.Is` / `errors.As`.

### Ruby

Install:

```bash
gem install humantone
```

Or in a Gemfile: `gem "humantone", "~> 0.0.1"`.

Basic humanize:

```ruby
require "humantone"

client = HumanTone::Client.new(api_key: "ht_your_api_key")

result = client.humanize(
  text: "Your input text goes here...",
  level: :standard,
  output_format: :text,
  custom_instructions: "Keep brand names. Professional tone."
)

puts result.text
puts "Used #{result.credits_used} credits, request ID: #{result.request_id}"
```

AI likelihood check:

```ruby
detection = client.detect(text: "Text to analyze.")
puts "AI score: #{detection.ai_score}"
```

Account check:

```ruby
info = client.account.get
puts "Plan: #{info.plan.name}, credits: #{info.credits.total}"
```

Ruby 3.3+. Stdlib `net/http` only, zero runtime dependencies. RBS type signatures included.

---

## MCP Server

The MCP (Model Context Protocol) server lets AI assistants call HumanTone directly inside chat. Same API key, same credits, same word limits as the REST API. Stdio-based local server.

**Package:** [humantone-mcp on npm](https://www.npmjs.com/package/humantone-mcp). Repo: [github.com/humantone/humantone-mcp](https://github.com/humantone/humantone-mcp).

**Tools exposed:**

| Tool | Description |
|---|---|
| `humanize` | Rewrite text to sound more natural. Same parameters as the API endpoint. |
| `detect_ai` | Get an AI likelihood score from 0 to 100. |
| `get_account` | Check plan, remaining credits, and subscription. |

### Installation

The configuration pattern is identical across all MCP-compatible clients: a `command` (npx) that runs `humantone-mcp`, with `HUMANTONE_API_KEY` set as an environment variable.

**Claude Desktop:**

Config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "humantone": {
      "command": "npx",
      "args": ["-y", "humantone-mcp"],
      "env": {
        "HUMANTONE_API_KEY": "ht_your_api_key_here"
      }
    }
  }
}
```

Replace the placeholder key. Quit Claude Desktop fully (Cmd+Q on macOS) and reopen.

**Cursor, VSCode (with MCP-compatible extension like Cline or Continue.dev), Codex CLI, Gemini CLI, Zed, Windsurf, JetBrains AI Assistant:** same config shape. Each client has its own MCP config file location, but the `mcpServers.humantone` block contents are identical. Refer to each client's MCP documentation for the file path.

### Usage in chat

Mentioning "humantone" explicitly helps the assistant pick the right tool reliably. Otherwise the assistant may rewrite the text itself rather than calling the MCP tool.

Triggers that reliably work:
- "Use humantone to rewrite this draft: [text]"
- "Run this through humantone: [text]"
- "Pass this to humantone with a formal tone: [text]"
- "Use humantone's AI detector on this: [text]"
- "Check AI likelihood with humantone: [text]"
- "How many HumanTone credits do I have?" (auto-triggers `get_account`)

Combined workflows:
- "Write a short blog post about [topic] and humanize it through humantone."
- "How many HumanTone credits do I have? How many 800-word articles can I humanize?"

### Limits and behavior

- Per-request word limit follows the user's plan: 750 Basic, 1,000 Standard, 1,500 Pro. Minimum 30 words.
- Credits: humanize consumes 1 credit per 100 words. `detect_ai` and `get_account` do not consume credits.
- AI likelihood daily quota: 30 checks per day, shared across web app, API, MCP, and integrations. Resets midnight UTC.
- API access required: free trial accounts cannot use the MCP server.

### Common troubleshooting

**Tools do not appear after restart:** check JSON for syntax errors, fully quit and reopen the client (not just refresh).

**"Invalid API key format":** HumanTone keys are 67 characters: `ht_` + 64 hex characters. Regenerate at [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api) and paste without surrounding whitespace.

**"Your HumanTone plan does not include API access":** the account is on free trial. Upgrade to a paid plan at [humantone.io/pricing](https://humantone.io/pricing/).

**"bad option: -y" or other command errors:** the `command` field points to `node` instead of `npx`. The `-y` flag belongs to `npx`. Use `command: "npx"` (or its absolute path; on nvm setups, the npx binary lives next to node, e.g. `~/.nvm/versions/node/v22.1.0/bin/npx`).

**"Cannot find module 'node:path'" or similar Node builtin error:** an old Node version (12 or earlier) is first on PATH. Fix by either (A) installing globally with `nvm use 22 && npm install -g humantone-mcp` and pointing the config at the global binary, or (B) setting a recent Node version as the nvm default (`nvm alias default 22`) and rebooting.

**Request timed out:** long inputs at `extreme` level can take 30+ seconds. Try `level: standard` or split the input into smaller chunks.

For other errors, copy the full error from the client's MCP log into any AI assistant along with OS and client name. The assistants are very good at diagnosing MCP setup issues.

### Browser test (no install)

[mcp.so listing](https://mcp.so/server/humantone/HumanTone) includes a "Try in Playground" feature that runs the MCP server in the browser. Useful for trying tools without a local install.

---

## n8n Integration

Two paths. Pick by where n8n runs.

### Option 1: Community node (self-hosted n8n)

**Install:**

1. In the n8n instance, open Settings → Community Nodes
2. Click Install
3. Enter `n8n-nodes-humantone`
4. Click Install and wait for completion
5. The HumanTone node appears in the node list under Transform

**Set up credentials:**

1. Add a HumanTone node to a workflow
2. Click Create New Credential
3. Paste the API key from [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api)
4. Click Test to verify, then Save

**Operations:**

| Operation | Description |
|---|---|
| Humanize | Rewrites AI text. Three levels, three output formats, optional custom instructions. |
| AI Checker | Returns AI likelihood score from 0 to 100. Free, 30 checks per day per account. |
| Get Account | Returns plan, credit balance, and subscription status. |

**AI Agent integration:** the community node sets `usableAsTool: true`, exposing all three operations to n8n's AI Agent. Connect HumanTone in the Agent's Tools panel and the agent can decide when to call `humanize` on its own initiative.

**Package:** [n8n-nodes-humantone on npm](https://www.npmjs.com/package/n8n-nodes-humantone). Repo: [github.com/HumanTone/humantone-n8n](https://github.com/HumanTone/humantone-n8n).

### Option 2: HTTP Request configs (n8n Cloud, or no-install)

n8n Cloud does not allow community node installation. Use n8n's built-in HTTP Request node with these copy-paste JSON configs. Each creates a fully wired node with the right URL, method, body parameters, and authentication.

**Import method:** copy the JSON, paste onto an n8n workflow canvas (Ctrl+V or right-click → Paste). After import, click the node, open Credentials, add a new HTTP Bearer Auth credential with the API key in the Bearer Token field.

**Humanize node:**

```json
{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.humantone.io/v1/humanize",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpBearerAuth",
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            { "name": "content", "value": "" },
            { "name": "custom_instructions" },
            { "name": "humanization_level", "value": "standard" },
            { "name": "output_format", "value": "text" }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [0,0],
      "name": "HumanTone - Humanize",
      "credentials": { "httpBearerAuth": {} }
    }
  ],
  "connections": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "0" }
}
```

**AI Checker node:**

```json
{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.humantone.io/v1/detect",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpBearerAuth",
        "sendBody": true,
        "bodyParameters": {
          "parameters": [ { "name": "content", "value": "" } ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [0,0],
      "name": "HumanTone - AI Checker",
      "credentials": { "httpBearerAuth": {} }
    }
  ],
  "connections": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "0" }
}
```

**Get Account node:**

```json
{
  "nodes": [
    {
      "parameters": {
        "url": "https://api.humantone.io/v1/account",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpBearerAuth",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [0,0],
      "name": "HumanTone - Get Account",
      "credentials": { "httpBearerAuth": {} }
    }
  ],
  "connections": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "0" }
}
```

### Common n8n workflow patterns

**AI generation → Humanize → Publish (primary use case):**

```
Trigger → OpenAI / Anthropic / any AI node → HumanTone (Humanize) → Notion / CMS / Slack
```

Set the Humanize node's `content` parameter to the AI node's output, e.g. `{{$json.message.content}}`.

**Pre-batch credit check:**

```
Manual Trigger → HumanTone (Get Account) → IF (credits.total < 200) → Stop & Notify
                                          ↓ else
                                          Loop over articles → HumanTone (Humanize)
```

**AI Agent with HumanTone as a tool (community node only):**

```
Trigger → AI Agent (with HumanTone connected as a tool)
```

The agent will call `humanize` when generating text that should sound natural. Works only with the community node (`usableAsTool: true`); the HTTP Request alternative cannot be exposed as an AI Agent tool.

---

## Make.com Integration

Make does not have a dedicated HumanTone app. Use Make's built-in `HTTP > Make a request` module with these copy-paste blueprints.

**Setup:**

1. Get an API key at [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api)
2. In Make, right-click any scenario canvas → Import blueprint, paste one of the JSONs below
3. After import, click the HTTP module, find the `Authorization` header, replace `ht_your_api_key` with the real key

**Plan support:** the HTTP module is available on every Make plan including the free tier.

**Humanize blueprint:**

```json
{
  "subflows": [{
    "flow": [{
      "id": 1,
      "module": "http:MakeRequest",
      "version": 4,
      "parameters": { "authenticationType": "noAuth" },
      "mapper": {
        "url": "https://api.humantone.io/v1/humanize",
        "method": "post",
        "headers": [{ "name": "Authorization", "value": "Bearer ht_your_api_key" }],
        "contentType": "json",
        "inputMethod": "jsonString",
        "jsonStringBodyContent": "{\n  \"content\": \"\",\n  \"custom_instructions\": \"\",\n  \"humanization_level\": \"standard\",\n  \"output_format\": \"text\"\n}",
        "parseResponse": true
      },
      "metadata": { "designer": { "x": 0, "y": 0 } }
    }]
  }],
  "metadata": { "version": 1 }
}
```

**AI Checker blueprint:**

```json
{
  "subflows": [{
    "flow": [{
      "id": 1,
      "module": "http:MakeRequest",
      "version": 4,
      "parameters": { "authenticationType": "noAuth" },
      "mapper": {
        "url": "https://api.humantone.io/v1/detect",
        "method": "post",
        "headers": [{ "name": "Authorization", "value": "Bearer ht_your_api_key" }],
        "contentType": "json",
        "inputMethod": "jsonString",
        "jsonStringBodyContent": "{\n  \"content\": \"\"\n}",
        "parseResponse": true
      },
      "metadata": { "designer": { "x": 0, "y": 0 } }
    }]
  }],
  "metadata": { "version": 1 }
}
```

**Get Account blueprint:**

```json
{
  "subflows": [{
    "flow": [{
      "id": 1,
      "module": "http:MakeRequest",
      "version": 4,
      "parameters": { "authenticationType": "noAuth" },
      "mapper": {
        "url": "https://api.humantone.io/v1/account",
        "method": "get",
        "headers": [{ "name": "Authorization", "value": "Bearer ht_your_api_key" }],
        "parseResponse": true
      },
      "metadata": { "designer": { "x": 0, "y": 0 } }
    }]
  }],
  "metadata": { "version": 1 }
}
```

### Make-specific notes

- **Credentials:** the HTTP module does not store credentials globally. Either paste the same Bearer token into each HumanTone module, or store it once in a Make data store and reference it across scenarios.
- **Retries:** Make's HTTP module retries on certain network errors by default. Humanize consumes credits per call, so set the module's `Number of retries` to 0 if at-most-once delivery is required. AI Checker and Get Account are safe to retry (no credit consumption).
- **Mapping output:** with `parseResponse: true`, downstream modules can map fields directly: `{{2.content}}`, `{{2.credits_used}}`, `{{2.ai_score}}`, `{{2.credits.total}}`, etc.

### Common Make workflow patterns

**AI generation → Humanize → CMS:**

```
Trigger → OpenAI / Anthropic / any AI module → HumanTone (Humanize) → Notion / WordPress / Slack
```

Set the Humanize blueprint's `content` to the AI module's output, e.g. `{{1.choices[0].message.content}}` for OpenAI.

**AI Checker on form submissions:**

```
Webhook (form) → HumanTone (AI Checker) → Router
                                          ↓ if ai_score > 80
                                          Slack alert
                                          ↓ else
                                          Save to CRM
```

**Pre-batch credit check:**

```
Manual Trigger → HumanTone (Get Account) → Router → if credits.total < 200 → Email yourself
                                                  ↓ else
                                                  Iterator → HumanTone (Humanize)
```

---

## Web App Tools

For completeness. The web app at [humantone.io/dashboard](https://humantone.io/dashboard) and the public tool pages cover the same surface but in a browser UI. Users who don't need programmatic access often start here.

- **Humanizer** ([humantone.io/tool/humanizer/](https://humantone.io/tool/humanizer/)): the core rewriting tool. Three humanization levels (Standard, Advanced, Extreme), three output formats (HTML, formatted text, plain text), Custom Instructions, project history.
- **AI Detector** ([humantone.io/tool/ai-detector/](https://humantone.io/tool/ai-detector/)): public AI likelihood checker. 3 free checks per day for non-logged-in users. Same scoring as the API `/v1/detect` endpoint.
- **Hidden Symbols Finder** ([humantone.io/tool/hidden-symbols/](https://humantone.io/tool/hidden-symbols/)): finds and removes invisible Unicode characters (zero-width marks, smart quotes, control characters). Free, no sign-up, runs in browser.
- **Readability Checker** ([humantone.io/tool/readability/](https://humantone.io/tool/readability/)): six reading-level formulas (Flesch Reading Ease, Flesch-Kincaid Grade Level, Gunning Fog Index, Coleman-Liau Index, ARI, SMOG Index). Free, no sign-up.
- **Text Compare** ([humantone.io/tool/text-compare/](https://humantone.io/tool/text-compare/)): word-level diff. Added words green, removed red. Inline or side-by-side. Free, no sign-up.

The Hidden Symbols, Readability, and Text Compare tools run entirely in-browser and do not send text to a server. They are not exposed via the API.

---

## Pricing and Limits

### Subscription plans

| Plan | Monthly price | Yearly price (saves 20%) | Credits/month | ~Words/month | Max words/run |
|---|---|---|---|---|---|
| Basic | $10 | $8/month | 150 | ~15,000 | 750 |
| Standard | $20 | $16/month | 400 | ~40,000 | 1,000 |
| Pro | $40 | $32/month | 1,000 | ~100,000 | 1,500 |

All paid plans include: API access, MCP access, AI Detector (free), Custom Instructions, 60+ languages, all free Text Tools.

### Extra Credits (one-time top-up, valid 1 year)

| Package | Credits | ~Words | Per-credit cost |
|---|---|---|---|
| $5 | 50 | ~5,000 | $0.100 |
| $10 | 125 | ~12,500 | $0.080 |
| $25 | 400 | ~40,000 | $0.063 |
| $50 | 1,000 | ~100,000 | $0.050 |
| $100 | 2,500 | ~250,000 | $0.040 |

Extra Credits work alongside any subscription plan or with no plan at all. They do not change the per-run word limit (that's still set by the plan, or 500 words for no-plan users on the free trial).

### Free trial

No credit card. No time limit. Smaller per-run word limit than paid plans. Includes the full Humanizer and the in-app AI likelihood check. Free trial accounts **cannot use the API or MCP** — they must upgrade to a paid plan first.

### Credit math

- 1 credit = 100 words processed (input word count).
- Output word count does not affect cost.
- Subscription credits reset each billing cycle. Unused subscription credits do not roll over.
- Extra Credits are billed against last. They expire 1 year from purchase, not monthly.

### What does and does not consume credits

| Operation | Cost |
|---|---|
| Humanize (`POST /v1/humanize`) | 1 credit per 100 input words |
| AI Checker (`POST /v1/detect`) | Free. Counts against 30-per-day quota. |
| Get Account (`GET /v1/account`) | Free |
| All web-only tools (Hidden Symbols, Readability, Text Compare) | Free (no account needed) |

### AI Checker daily quota

30 checks per day per account, shared across the HumanTone web app, API, MCP, n8n integration, and Make integration. Resets at midnight UTC. The error response includes a `time_to_next_renew` field (seconds until reset).

Public AI Detector tool at [humantone.io/tool/ai-detector/](https://humantone.io/tool/ai-detector/) has a separate 3-free-checks-per-day limit for non-logged-in users.

---

## Common Workflow Recipes

End-to-end patterns that AI assistants can show users.

### Recipe 1: Code → AI generation → HumanTone → CMS

The most common pattern. Generate AI text, humanize it, post to a CMS.

**Node.js example:**

```typescript
import HumanTone from 'humantone';
import OpenAI from 'openai';

const openai = new OpenAI();
const humantone = new HumanTone({ apiKey: process.env.HUMANTONE_API_KEY });

const draft = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a 400-word blog intro about home security.' }],
});

const draftText = draft.choices[0].message.content;

const humanized = await humantone.humanize({
  text: draftText,
  level: 'standard',
  outputFormat: 'html',
  customInstructions: 'Tone: clear, trustworthy. Audience: homeowners. Keep: "smart lock", "home security".',
});

// Post humanized.text to your CMS API
```

### Recipe 2: Pre-batch credit check

Avoid running out mid-batch.

**Python example:**

```python
from humantone import HumanTone

client = HumanTone(api_key=os.environ["HUMANTONE_API_KEY"])
info = client.account.get()

articles = load_articles()  # 50 articles, ~600 words each
estimated_credits = sum(len(a.split()) for a in articles) // 100

if info.credits.total < estimated_credits:
    print(f"Not enough credits. Have {info.credits.total}, need {estimated_credits}.")
    sys.exit(1)

for article in articles:
    result = client.humanize(text=article)
    save(result.text)
```

### Recipe 3: Humanize + check + republish if too AI-like

For sensitive content where AI score matters.

```python
result = client.humanize(text=draft, level="advanced")
score = client.detect(text=result.text).ai_score

if score > 50:
    # Try a stronger rewrite
    result = client.humanize(text=draft, level="extreme")

publish(result.text)
```

Note: `extreme` does not support Custom Instructions. Use it only when score reduction outweighs precise tone control.

### Recipe 4: Batch with deduplication

If running with retry logic, opt out of POST retries to avoid double-billing humanize calls.

```typescript
const client = new HumanTone({
  apiKey: process.env.HUMANTONE_API_KEY,
  retryOnPost: false,  // default. Explicit for clarity.
});

// Implement your own idempotency layer if needed
```

### Recipe 5: AI Agent + HumanTone (MCP)

In Claude Desktop / Cursor / Cline:

> Write a 600-word article about [topic], then use humantone to rewrite it in a friendly tone for a younger audience.

The assistant calls OpenAI / Anthropic / Gemini internally for the draft, then calls `humanize` via MCP, returns final text.

---

## Brand and naming conventions

The same underlying functionality is exposed under slightly different names in different surfaces. AI assistants should map these correctly.

| Surface | Humanize | AI score check | Account |
|---|---|---|---|
| Web app | Humanizer | AI Detector | Settings → Plan / API |
| REST API endpoint | `POST /v1/humanize` | `POST /v1/detect` | `GET /v1/account` |
| MCP tool name | `humanize` | `detect_ai` | `get_account` |
| Node SDK method | `client.humanize()` | `client.detect()` | `client.account.get()` |
| Python SDK method | `client.humanize()` | `client.detect()` | `client.account.get()` |
| PHP SDK method | `$client->humanize()` | `$client->detect()` | `$client->account->get()` |
| Go SDK method | `client.Humanize()` | `client.Detect()` | `client.Account.Get()` |
| Ruby SDK method | `client.humanize()` | `client.detect()` | `client.account.get` |
| n8n community node operation | Humanize | AI Checker | Get Account |
| Make blueprint name | Humanize | AI Checker | Get Account |

**Note on "AI Detector" vs "AI Checker":** the public tool at [humantone.io/tool/ai-detector/](https://humantone.io/tool/ai-detector/) is called "AI Detector". The API endpoint is `/v1/detect`. The MCP tool is `detect_ai`. The n8n and Make integration UIs use the softer name "AI Checker". All refer to the same underlying functionality.

---

## Glossary

- **Credits:** the unit of billing. 1 credit = 100 input words humanized. Detection and account checks are free.
- **Custom Instructions:** free-form guidance for a humanize call. Specify tone, audience, terms to preserve, purpose. Max 1,000 characters.
- **Humanization Level:** `standard` (60+ languages, recommended, full Custom Instructions), `advanced` (English only, stronger rewriting, Custom Instructions still supported), `extreme` (English only, experimental, maximum variation, Custom Instructions not supported).
- **AI likelihood score / AI score:** integer 0-100 from `POST /v1/detect`. Higher = more AI-like patterns. Buckets: 0-25 Likely Human, 26-50 Possibly Human, 51-75 Possibly AI, 76-100 Likely AI.
- **Free trial:** no-credit-card sign-up with free credits. Smaller per-run word limit. **No API or MCP access.**
- **Extra Credits:** one-time credit top-ups. Valid 1 year. Work with or without a subscription. Do not change per-run word limit.
- **Word limit per run:** maximum words in a single `/v1/humanize` call. Set by plan: 500 (free trial), 750 (Basic), 1,000 (Standard), 1,500 (Pro). Minimum 30 words for any call.
- **MCP:** Model Context Protocol. Standard that lets AI assistants call external tools. The HumanTone MCP server runs as a local stdio process; the AI client communicates with it over stdin/stdout.
- **Community node:** an n8n custom node installed via Settings → Community Nodes. `n8n-nodes-humantone` is HumanTone's official community node. Available on self-hosted n8n only; n8n Cloud does not allow community node installs.
- **Blueprint:** a Make.com JSON export of one or more modules. Pasting a blueprint into a scenario canvas creates pre-configured modules ready to use.

---

## Support

- **Product or account questions:** help@humantone.io
- **MCP server bugs:** open an issue at [github.com/humantone/humantone-mcp/issues](https://github.com/humantone/humantone-mcp/issues)
- **SDK bugs:** open an issue at the matching repo (links in SDK Reference section above)
- **n8n node bugs:** [github.com/HumanTone/humantone-n8n/issues](https://github.com/HumanTone/humantone-n8n/issues)
- **Get an API key:** [humantone.io/dashboard/settings/api](https://humantone.io/dashboard/settings/api)
- **Manage plan and credits:** [humantone.io/dashboard/settings/plan](https://humantone.io/dashboard/settings/plan), [humantone.io/dashboard/settings/credits](https://humantone.io/dashboard/settings/credits)