Build with HumanTone

HumanTone API.

Humanize text, run AI detection, and check your account programmatically. Same credits you already use in the app.

Get Your API Key Available on all paid plans. Uses your existing credit balance.

ENDPOINTS

POST

/v1/humanize

Rewrite AI text to sound human.

POST

/v1/detect

Get an AI likelihood score (0 to 100).

GET

/v1/account

Check your plan, credits, and subscription.

QUICK START

From zero to humanized text in under a minute.

1
Go to Settings → API Keys in your dashboard and generate a key.
2
Copy the example below and replace ht_your_api_key with your key.
3
Run it.

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"
  }'

Response:

json

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Your output text.",
  "output_format": "html",
  "credits_used": 3
}

AUTH

Authentication.

Base URL

https://api.humantone.io

All requests require a Bearer token in the Authorization header:

Authorization: Bearer ht_your_api_key

Keys use the ht_ prefix followed by 64 hex characters. Generate and manage keys at app.humantone.io/settings/api.

Available on all paid plans (Basic, Standard, Pro). Free trial accounts do not have API access.

Your API calls use the same credit balance as the app. No separate API pricing.

Versioning.

The API is versioned. All current endpoints use /v1/. This version is stable.

If breaking changes are introduced in the future, they will ship under a new version (e.g. /v2/). Existing versions will continue to work.

HUMANIZER

POST /v1/humanize

Rewrites AI text to sound human. Same engine as the app.

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

Parameter	Type	Required	Description
content	string	Yes	The text to humanize. Minimum 30 words. Maximum depends on your plan.
humanization_level	string	No	`standard` (default), `advanced`, or `extreme`. Advanced and extreme support English only.
output_format	string	No	`html` (default), `text`, or `markdown`. Controls the format of the returned content field.
custom_instructions	string	No	Instructions for the rewrite: tone, terms to keep, audience, purpose. Max 1,000 characters.

Note: The default output format is html. If you need plain text without markup, set output_format to text explicitly.

Word limits per request

Plan	Max words
Basic	750
Standard	1,000
Pro	1,500

Response

json

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

Field	Type	Description
request_id	string	Unique ID for this request. Use it for logging or support inquiries.
content	string	The humanized text in the requested format.
output_format	string	The format of the returned content: html, text, or markdown.
credits_used	number	Credits deducted from your balance for this request.

Response time: The request is synchronous. Longer texts take longer to process. A 1,500 word input at extreme level may take 30+ seconds. Plan your client timeouts accordingly.

Errors

Status	Error	Cause
400	Invalid JSON body	Request body is not valid JSON
400	content is required	Missing, empty, or non-string content field
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 too long
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.

Code examples

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": "text",
    "custom_instructions": "Your custom instructions here."
  }'

const response = await fetch("https://api.humantone.io/v1/humanize", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Your input text goes here...",
    humanization_level: "standard",
    output_format: "text",
    custom_instructions: "Your custom instructions here."
  })
})

const data = await response.json()
console.log(data.content)

import requests

response = requests.post(
    "https://api.humantone.io/v1/humanize",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "content": "Your input text goes here...",
        "humanization_level": "standard",
        "output_format": "text",
        "custom_instructions": "Your custom instructions here."
    }
)

data = response.json()
print(data["content"])

<?php
$ch = curl_init("https://api.humantone.io/v1/humanize");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer ht_your_api_key",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "content" => "Your input text goes here...",
        "humanization_level" => "standard",
        "output_format" => "text",
        "custom_instructions" => "Your custom instructions here."
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["content"];

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "io"
)

func main() {
  body, _ := json.Marshal(map[string]string{
    "content": "Your input text goes here...",
    "humanization_level": "standard",
    "output_format": "text",
    "custom_instructions": "Your custom instructions here.",
  })

  req, _ := http.NewRequest("POST", "https://api.humantone.io/v1/humanize", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer ht_your_api_key")
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  resBody, _ := io.ReadAll(resp.Body)

  var data map[string]interface{}
  json.Unmarshal(resBody, &data)
  fmt.Println(data["content"])
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.humantone.io/v1/humanize")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer ht_your_api_key"
request["Content-Type"] = "application/json"
request.body = {
  content: "Your input text goes here...",
  humanization_level: "standard",
  output_format: "text",
  custom_instructions: "Your custom instructions here."
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts data["content"]

AI DETECTOR

POST /v1/detect

Returns an AI likelihood score for any text. Same detector as the app.

Detection does not consume credits. It is limited to 30 requests per day, shared between the app and API. The limit resets at midnight UTC.

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

Parameter	Type	Required	Description
content	string	Yes	The text to analyze.

Response

json

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

Field	Type	Description
ai_score	number	Score from 0 to 100. Higher means more AI patterns detected.

When the daily limit is reached

HTTP 200, success: false:

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

Field	Type	Description
time_to_next_renew	number	Seconds until the limit resets (midnight UTC).

When detection fails

HTTP 200, success: false:

{
  "success": false
}

The detection service returned no result. Retry the request.

Errors

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

Code examples

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..."
  }'

const response = await fetch("https://api.humantone.io/v1/detect", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Your input text goes here..."
  })
})

const data = await response.json()
console.log(`AI score: ${data.ai_score}`)

import requests

response = requests.post(
    "https://api.humantone.io/v1/detect",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "content": "Your input text goes here..."
    }
)

data = response.json()
print(f"AI score: {data['ai_score']}")

<?php
$ch = curl_init("https://api.humantone.io/v1/detect");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer ht_your_api_key",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "content" => "Your input text goes here..."
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "AI score: " . $data["ai_score"];

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "io"
)

func main() {
  body, _ := json.Marshal(map[string]string{
    "content": "Your input text goes here...",
  })

  req, _ := http.NewRequest("POST", "https://api.humantone.io/v1/detect", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer ht_your_api_key")
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  resBody, _ := io.ReadAll(resp.Body)

  var data map[string]interface{}
  json.Unmarshal(resBody, &data)
  fmt.Println("AI score:", data["ai_score"])
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.humantone.io/v1/detect")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer ht_your_api_key"
request["Content-Type"] = "application/json"
request.body = {
  content: "Your input text goes here..."
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts "AI score: #{data['ai_score']}"

ACCOUNT

GET /v1/account

Returns your plan, credit balance, and subscription status. Useful for checking remaining credits before sending a humanize request.

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.max_words	Max words per humanize request on your plan
plan.monthly_credits	Credits included per billing cycle
credits.total	All available credits (trial + subscription + extra)
credits.subscription	Remaining monthly plan credits
credits.extra	Remaining purchased extra credits
subscription.expires_at	Subscription expiry date (ISO 8601)

Errors

Status	Error	Cause
404	Plan not found	Account plan error. Contact support.

Code examples

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

const response = await fetch("https://api.humantone.io/v1/account", {
  headers: {
    "Authorization": `Bearer ${apiKey}`
  }
})

const data = await response.json()
console.log(`Credits remaining: ${data.credits.total}`)

import requests

response = requests.get(
    "https://api.humantone.io/v1/account",
    headers={
        "Authorization": f"Bearer {api_key}"
    }
)

data = response.json()
print(f"Credits remaining: {data['credits']['total']}")

<?php
$ch = curl_init("https://api.humantone.io/v1/account");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer ht_your_api_key"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Credits remaining: " . $data["credits"]["total"];

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
  "io"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.humantone.io/v1/account", nil)
  req.Header.Set("Authorization", "Bearer ht_your_api_key")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)

  var data map[string]interface{}
  json.Unmarshal(body, &data)
  credits := data["credits"].(map[string]interface{})
  fmt.Println("Credits remaining:", credits["total"])
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.humantone.io/v1/account")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer ht_your_api_key"

response = http.request(request)
data = JSON.parse(response.body)
puts "Credits remaining: #{data['credits']['total']}"

AUTH ERRORS

Authentication errors.

These errors can occur on any endpoint.

Status	Error	Cause
401	Missing or invalid Authorization header	No header provided, or it does not start with Bearer
401	Invalid API key format	Key does not match expected format (ht_ prefix + 64 hex characters)
401	Invalid API key	Key format is correct but does not exist
401	This API key has been revoked	Key was deleted in dashboard
401	User not found	Account associated with this key no longer exists
403	...plan does not include API access...	Free plan or trial. Paid plan required.
404	Not Found	Endpoint does not exist
405	Method not allowed	Wrong HTTP method (e.g. GET instead of POST)

All errors return JSON:

{
  "error": "Human-readable error message"
}

PRICING

Same credits. No extra cost.

API calls use your existing HumanTone credits. No separate API pricing. No per-request fees. 1 credit = 100 words. Same as the app.

What you need	Where to get it
A paid plan (Basic, Standard, or Pro)	humantone.io/pricing
An API key	app.humantone.io/settings/api
More credits	Buy Extra Credits in your dashboard. No plan change needed.

Detection is free with your plan. 30 requests per day. No credits consumed.

Rate limits: There are no strict per-second rate limits at this time. If you plan to send large batches, space them out or contact [email protected] to discuss your use case.

Start building.

Get your API key and send your first request in under a minute.

Get Your API Key Questions? [email protected]