Humanizio API

Three JSON endpoints: Humanize, Humanize + SEO, and Humanize + GEO. Simple bearer-key auth, one POST, natural writing back. This reference walks you from your first key to production-ready calls, with a full request-and-response example for every endpoint.

How do I get started?

Three steps: create an account, generate a key in your dashboard, and send your first POST. You can be humanizing text from the command line in under two minutes, and everything on this page works with tools you already have — no SDK to install and nothing to configure beyond a single header.

Step 1 — Create your account. Sign up on the registration page. The Free plan needs no card and gives you five humanizes a month, which is plenty to test the API end to end and wire it into a script before you decide on a paid plan.

Step 2 — Generate your API key. Open your dashboard and create a key. It looks like hz_live_ followed by a random string. Copy it once and keep it somewhere safe — a password manager, or an environment variable your app reads at runtime. The key carries your plan's permissions and counts every call against your allowance, so treat it like a password and never commit it to a public repository or ship it in front-end code a browser can read.

Step 3 — Make your first call. Point a POST at /v1/humanize with your key in the Authorization header and a JSON body containing at least twenty words of text. Here is the whole thing in one command:

curl https://humanizio-api.nanoo-shashwat.workers.dev/v1/humanize \
  -H "Authorization: Bearer hz_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"Our platform leverages cutting-edge technology to deliver seamless, end-to-end solutions that empower organizations to unlock value and drive meaningful outcomes at scale across every department."}'

A few seconds later (or up to a minute or two on the very first call of a session — see best practices) you get natural writing back:

{ "humanized": "Our platform is built to make the work simple from start to finish, so teams can get more done without fighting their tools.", "word_count": 24 }

That is the entire loop. Everything else in this reference builds on it: the same auth, the same POST shape, with richer inputs and reports for the SEO and GEO endpoints.

How does authentication work?

Every request carries your API key as a bearer token in the Authorization header — there are no cookies, sessions, or OAuth flows to manage. Generate a key in your dashboard, then send it with each call. The key identifies your account, enforces your plan's limits, and counts each call against your monthly allowance, so keep it secret.

Authorization: Bearer hz_live_xxxxxxxxxxxxxxxxxxxx

If the header is missing or the key is wrong, the API returns 401 and does nothing else. Because the key travels in a header rather than the URL, it never lands in server logs or browser history the way a query parameter would. Rotate a key any time from the dashboard if you suspect it has leaked; the old one stops working immediately.

Add-on endpoints (/v1/seo, /v1/geo) require a paid plan with the matching add-on enabled.

Base URL & limits

All endpoints live under one base URL and share the same request shape: a POST with a JSON body. The table below is the contract every call is held to.

The minimum exists because the engine needs enough context to rewrite in a natural voice — under twenty words there is nothing to work with, so it returns 400. The maximum protects both quality and cost: very long single jobs drift, so each plan caps words per job and you batch anything longer (covered under best practices).

What do the plans and monthly allowances include?

Every account has two limits that matter to the API: how many words a single job may contain, and how much you can process per month. Both scale with your plan. The Free plan is metered in whole humanizes; the paid plans are metered in words, which is a more natural unit once you are running real volume.

Each successful call draws down your allowance. On Free, one job spends one of your five monthly humanizes. On Pro and Premium, the job's word_count is subtracted from your monthly word budget — so a 900-word job on Pro leaves you 29,100 words for the rest of the month. When the budget runs out, calls return 402 until the month rolls over or you upgrade. Calls that fail before producing a result — an authentication error, a job over the per-job limit, or a warm-up 502 — do not count.

The /v1/seo and /v1/geo endpoints are gated separately: they need a paid plan and the matching add-on switched on. The SEO add-on inserts and grades keyword placement; the GEO add-on does the heavier, multi-pass work of structuring content for AI answer engines. See the pricing page for the current add-on prices and the annual discount. Billing is rolling out; free humanizing works today, so you can build and test the integration now and flip on a paid plan when you are ready.

POST /v1/humanize

Rewrites AI-drafted text into natural, human writing while preserving meaning and structure.

Request body

{ "text": "Your AI-drafted text (≥ 20 words)…" }

curl https://humanizio-api.nanoo-shashwat.workers.dev/v1/humanize \
  -H "Authorization: Bearer hz_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"In today'"'"'s rapidly evolving landscape, organizations must leverage..."}'

Response

{ "humanized": "Businesses today need to use…", "word_count": 128 }

Walkthrough — a marketing paragraph, start to finish. Say you drafted a product intro with an AI assistant and it came back stiff and over-formal, full of the usual tells: "leverage," "seamless," "moreover." You want it to sound like a person on your team wrote it, without losing the point. Send the draft as text:

{
  "text": "In today's rapidly evolving business landscape, organizations must leverage cutting-edge project management software to streamline their workflows. Moreover, such tools empower teams to collaborate seamlessly, thereby driving productivity and unlocking unprecedented value across the entire organization."
}

The engine rewrites paragraph by paragraph, keeping every fact and the running order of ideas, and hands back:

{
  "humanized": "Teams are busier than ever, and the right project management software keeps the work moving instead of piling up. A good tool puts everyone on the same page — who owns what, what's due, and what's blocked — so people spend their time doing the work rather than chasing status updates.",
  "word_count": 52
}

The meaning is untouched: it still argues that project management software helps busy teams collaborate and stay productive. What changed is the rhythm and the word choices — the empty opener is gone, the sentence lengths vary, and the abstract "unlocking value" became a concrete "chasing status updates." The word_count is the length of the returned text, and it is the number that draws down your monthly word budget on a paid plan.

POST /v1/seo

Inserts a target keyword the smart way (title, a heading, the opening, natural variants elsewhere), then humanizes — and returns a placement report and 0–100 SEO score. Requires the SEO add-on.

Request body

{ "text": "…", "keyword": "project management software" }

Response (abridged)

{
  "humanized": "…",
  "markdown": "# … formatted article …",
  "mode": "seo",
  "keyword": "project management software",
  "word_count": 812,
  "report": {
    "seo_score": 100,
    "keyword_density_pct": 1.2,
    "checklist": { "in_title": true, "in_a_heading": true, "in_first_100_words": true, "has_2plus_headings": true },
    "readability_flesch": 58.4
  }
}

Walkthrough — ranking a draft for a keyword. You have an 800-word article about choosing project tools, and you want it to rank for project management software without keyword stuffing. Send the draft plus the keyword:

curl https://humanizio-api.nanoo-shashwat.workers.dev/v1/seo \
  -H "Authorization: Bearer hz_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"Choosing the right tool for your team can feel overwhelming...","keyword":"project management software"}'

The response humanizes the prose and, at the same time, places the keyword where search engines weight it most — the title, at least one heading, and the first hundred words — then uses natural variants (“the software,” “these tools”) through the body so density stays in a safe range rather than reading like a stuffed page. The markdown field gives you the article ready to paste, and the report tells you exactly what it did:

{
  "mode": "seo",
  "keyword": "project management software",
  "markdown": "# The best project management software for small teams\n\nPicking a tool your team will actually use...",
  "word_count": 812,
  "report": {
    "seo_score": 100,
    "keyword_density_pct": 1.2,
    "checklist": { "in_title": true, "in_a_heading": true, "in_first_100_words": true, "has_2plus_headings": true },
    "readability_flesch": 58.4
  }
}

Read the report like a checklist you would otherwise run by hand. seo_score is an overall 0–100 grade for on-page keyword placement. keyword_density_pct around 1–2% is the healthy band — high enough to signal relevance, low enough to avoid the stuffed-page look. The checklist booleans show the four placements that matter most, and readability_flesch reports the Flesch reading-ease score, where the 50–60 range reads as clear, general-audience prose. If a checklist item comes back false — say the keyword did not fit the title naturally — you can edit that one spot yourself rather than re-running the whole job.

POST /v1/geo

Optimizes content to be cited by AI answer engines (statistics, citations, direct answers), then humanizes. Unverifiable additions are marked [verify: …] — fill them with real sources before publishing. Requires the GEO add-on.

Request body

{ "text": "…", "keyword": "optional topic or question" }

Response (abridged)

{
  "humanized": "…",
  "markdown": "…",
  "mode": "geo",
  "word_count": 905,
  "report": {
    "statistics_surfaced": 3,
    "citation_placeholders": 2,
    "levers_applied": ["statistics_present","question_headings","citation_placeholders"],
    "warning": "Replace every [verify: …] placeholder with a real, checked source before publishing."
  }
}

Walkthrough — writing to be cited by AI answers. GEO stands for generative engine optimization: shaping content so tools like ChatGPT, Perplexity, and Google's AI Overviews quote it in their answers. Those systems favor content that answers the question directly, leads with concrete numbers, and formats claims so they are easy to lift. Send your draft, optionally with the topic or question it should target:

curl https://humanizio-api.nanoo-shashwat.workers.dev/v1/geo \
  -H "Authorization: Bearer hz_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"Composting turns kitchen and yard waste into soil...","keyword":"how does composting work"}'

The response rewrites the content with answer-first headings, surfaces the statistics already present, and adds the scaffolding an answer engine looks for. Crucially, it never invents a number or a source. Where a claim would be stronger with a citation the engine cannot supply, it inserts a [verify: …] placeholder for you to fill:

{
  "mode": "geo",
  "markdown": "## How does composting work?\n\nComposting works by letting microbes break down organic matter into humus, usually over [verify: typical timeframe from a composting authority]. Roughly [verify: share of household waste that is compostable] of household waste can be composted...",
  "word_count": 905,
  "report": {
    "statistics_surfaced": 3,
    "citation_placeholders": 2,
    "levers_applied": ["statistics_present","question_headings","citation_placeholders"],
    "warning": "Replace every [verify: …] placeholder with a real, checked source before publishing."
  }
}

The report is your publish checklist. statistics_surfaced counts the concrete figures the rewrite foregrounded. citation_placeholders counts the [verify: …] markers you must resolve — search the markdown for that token and replace each with a real, checked source. levers_applied lists the GEO tactics used, so you know what was done, and the warning is a hard reminder: never publish with a placeholder still in the text. Because everything factual traces to something you can verify, the output improves your own credibility rather than putting words in your mouth.

How do I call the API from my language?

It is a plain JSON-over-HTTPS API, so any HTTP client works and there is nothing to install. Below is the same humanize call in three common forms. Swap in your own key and text, and the SEO and GEO endpoints work identically — just change the path and add a keyword field to the body.

curl — quickest for a one-off test or a shell script:

curl https://humanizio-api.nanoo-shashwat.workers.dev/v1/humanize \
  -H "Authorization: Bearer $HUMANIZIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Paste at least twenty words of AI-drafted text here so the engine has enough to rewrite naturally."}'

JavaScript — fetch, in Node or a server-side handler (never ship your key to the browser):

const res = await fetch(
  "https://humanizio-api.nanoo-shashwat.workers.dev/v1/humanize",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HUMANIZIO_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: draft }),
  }
);
if (res.status === 502) { /* engine warming up — retry shortly */ }
const data = await res.json();
console.log(data.humanized, data.word_count);

Python — requests, with a small retry for the warm-up case:

import os, time, requests

URL = "https://humanizio-api.nanoo-shashwat.workers.dev/v1/humanize"
headers = {"Authorization": f"Bearer {os.environ['HUMANIZIO_KEY']}",
           "Content-Type": "application/json"}

def humanize(text):
    for attempt in range(4):
        r = requests.post(URL, json={"text": text}, headers=headers, timeout=180)
        if r.status_code == 502:           # engine spinning up
            time.sleep(30)
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("engine did not warm up in time")

out = humanize(draft)
print(out["humanized"], out["word_count"])

What are the best practices for production?

Three habits keep an integration fast and cheap: handle the cold start gracefully, stay under your per-job word limit, and batch anything long. Get these right and the API is boringly reliable.

Handle the cold-start 502 with a retry. The engine runs on serverless GPU capacity that scales to zero when nobody is using it, so the first call after an idle stretch spins that capacity up — one to two minutes in the worst case — and may answer with 502 while it warms. This is expected, not an error in your request. Wrap calls in a short retry loop: on a 502, wait about 30 seconds and try again, up to three or four attempts, ideally with exponential backoff (30s, then 60s, then 120s). Humanizing the same input twice yields the same kind of result, and a warm-up 502 never produced output, so retrying is safe and does not double-charge your allowance. If your workload is bursty, a cheap trick is to fire one tiny "warm-up" job at the start of a session so the first real call lands on an already-warm engine.

Keep each input under your plan's per-job limit. The ceiling is 200 words on Free, 1,500 on Pro, and 5,000 on Premium. Send more and you get 403 with nothing processed — the request is rejected before it costs you anything. Count words on your side before you send, and if a document is close to the line, trim or split it rather than hoping it squeaks under. Remember the floor too: every chunk you send must be at least 20 words, or it returns 400.

Batch long documents by section. To humanize something longer than your per-job limit, split it into chunks that each sit comfortably under the ceiling, send them one at a time, and stitch the results back together. Split on natural boundaries — headings first, then paragraphs — so you never cut a sentence in half and the document's structure survives the round trip. A 6,000-word guide on Pro (1,500-word ceiling) becomes four or five section-sized jobs. Process them sequentially rather than firing all of them at once; sequential calls are gentler on the warm-up behavior and easier to retry cleanly. When you reassemble, keep the original heading order, and do a quick read of the seams where two chunks meet to make sure the transition still flows. Batching also spreads a long document across several smaller word_count deductions, which makes it easy to track spend against your monthly budget.

A few smaller habits. Store your key in an environment variable, not in code. Set a generous client timeout (180 seconds) so a warm-up call is not cut off by your own HTTP client. Log the word_count from each response to track your monthly usage against the allowance table above. And for SEO and GEO, always read the report and resolve every [verify: …] placeholder before anything goes live.

Errors

Errors return a JSON { "error": "…" } with an HTTP status. Each status maps to one cause, so you can branch on the code alone:

Handle them distinctly: 401 means fix your key; 400 means fix your input (too short, or a missing keyword on /v1/seo); 403 means either split the text under your per-job limit or enable the plan/add-on the endpoint needs; 402 means you have used your monthly allowance and it is time to upgrade or wait for the reset; and 502 is the only one you should retry automatically, because it just means the engine is still spinning up. A 200 always carries a JSON body — humanized and word_count for humanize, plus markdown, mode, and a report for SEO and GEO.

Get your API key