API documentation

Build your integration

UltraHumanizer combines natural rewriting with explicit editorial controls and detail-change checks. The API is designed for server-side integrations in apps, content systems and automation workflows.

For integration support, contact the team. To evaluate the current writing experience, try the web editor. Do not use the website’s private browser endpoints as a developer API.

Download the OpenAPI specification ↓

Authentication

The API uses a server-side Bearer key. Keep it in an environment variable or secrets manager, never in frontend bundles, shared prompts or public repositories. Create and revoke keys in the developer dashboard. A new key is shown once; only its SHA-256 hash is stored. Maximum 10 active keys per account.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_OPERATION_ID

Generate one operation ID for each new rewrite and persist it before sending. Reuse that ID when retrying the same body. A changed body represents a new operation. Keys share the account’s API balance. Revocation blocks new requests immediately; an already accepted request may finish.

A request in your language

This example replaces a stiff phrase while keeping the product name and price. The credentials and operation ID are placeholders. Supply a stored operation ID in your own code; no SDK is required.

# Bash / macOS / Linux terminal. Set ULTRAHUMANIZER_API_KEY first.
curl --fail-with-body --max-time 120 https://ultrahumanizer.ai/api/v1/humanize \
  -H "Authorization: Bearer $ULTRAHUMANIZER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-rewrite-001" \
  -d '{
  "text": "You can utilize Acme for $20 per month.",
  "tone": "natural",
  "length": "keep",
  "strength": "balanced",
  "reading_level": "general",
  "protected_terms": [
    "Acme"
  ],
  "task": "humanize"
}'

Rewrite text

Send plain text and editorial preferences. Receive one rewritten result, usage metadata and supported detail changes. Source language is preserved as an editorial instruction; this endpoint is not a translation service.

Illustrative successful response

{
  "request_id": "req_example",
  "text": "You can use Acme for $20 per month.",
  "usage": {
    "billing_unit_version": "2026-10-v1",
    "input_units": 8,
    "charged_units": 8
  },
  "detail_changes": [],
  "warnings": [],
  "engine_version": "uh-editorial-2026-10"
}

request_id identifies the operation. usage describes the input charge, and engine_version identifies the editorial release for reproducibility. The response example is illustrative; generated wording may vary.

Use changes to guide a review

detail_changes reports additions, removals and occurrence-count changes. Supported categories are number, date, link, email, quote, citation and term.

{
  "detail_changes": [
    {
      "kind": "number",
      "value": "$20",
      "before": 1,
      "after": 0
    },
    {
      "kind": "number",
      "value": "$30",
      "before": 0,
      "after": 1
    }
  ],
  "warnings": [
    "Review the changed price before publishing."
  ]
}

Here, before and after are occurrence counts, not confidence scores. A change from $20 to $30 creates one removed value and one added value. This is a separate example of a result needing review, not the response to the request above.

• Dates cover supported numeric formats; citation checks cover numeric markers such as [4]. These are not comprehensive citation validation.
• Protected terms are case-sensitive exact terms. Check warnings and keep editorial approval for material content.
• An empty array means no supported differences were identified. It does not establish that meaning, attribution, facts or citation placement are correct.
• Use warning presence to route content for review. Do not treat the API response as an automatic publishing authorization.

Estimate a request and inspect usage

Submit {"text":"Your source text"} to calculate input credits before generating. The estimate should identify its counting version and whether the input fits current limits. An estimate does not reserve credits or guarantee that a later request will be accepted.

{
  "input_units": 8,
  "billing_unit_version": "2026-10-v1",
  "within_limits": true
}

Read the account’s available and reserved credits. Querying usage and estimating input are non-billable, subject to 120 requests per minute per account. usage also returns balance_credits, which can be negative after a refund or dispute affecting already-spent credits.

Recover a request

Returns status (pending, complete or failed), charged_units, result_available and result. A complete response contains the original result while its 24-hour replay window is open. Recovery requires a valid key from the same account. A missing or inaccessible ID returns 404 request_not_found.

Predictable input-based billing

The API uses one-time prepaid packs. API credits are separate from website memberships. The website’s paid plan or free word allowance does not grant API access.

• Count input once. Billing version 2026-10-v1 counts letter/number words (internal straight or curly apostrophes stay in a word); Han, Hiragana, Katakana and Hangul characters each count separately. The final charge is the greater of this count and UTF-8 bytes divided by 12, rounded up. Punctuation has no word count but contributes to the byte floor. Output adds no separate charge.
• Estimate exactly. “Hello world” costs 2 credits; “你好世界” costs 4; “Hello 世界” costs 3. Long words, emoji and scripts without word spaces can trigger the byte floor. Call /estimate for the exact charge. Only text is counted; editorial controls and protected terms do not add credits.
• Reserve, then settle. Credits are reserved before generation and settled when a successful result is stored. Failed generation releases the reservation.
• Make retries safe. Retrying the same operation with the same body and idempotency key does not create another charge. A requested new rewrite is a new billable operation.
• Stop at the balance. Insufficient available credits reject new work. The API has no automatic renewal, automatic top-up or postpaid overage.

A client timeout does not prove generation failed. Retry the identical operation with the same Idempotency-Key, or call GET /api/v1/requests/{request_id}. Completed results can be recovered for 24 hours. Request IDs and key hashes remain as billing records; an expired or failed operation key cannot be reused for a new operation. A failed request is not charged; confirm its status before starting again with a new key. View prepaid packs.

Credits do not expire while the service remains available. Purchases are one-time USD payments processed by Stripe. A purchase grants API usage credits, not cash value or website membership. For a mistaken or unused purchase, contact support@ultrahumanizer.ai with the receipt before spending the credits. Refunds are reviewed individually; applicable rights are unaffected. Approved refunds and disputes reverse the associated credits. Spending already-refunded credits is blocked until any negative balance is resolved.

Errors and retries

The error envelope includes a request ID, a stable code and a human-readable message. Handle the code rather than parsing the message.

{
  "request_id": "req_example",
  "error": {
    "code": "insufficient_credits",
    "message": "Available credits are below the requested input amount."
  }
}

Additional 409 codes: request_in_progress (retry the same key), request_failed (confirmed failure; use a new key to retry), and result_expired (already charged; recovery window ended). For retryable failures, use exponential backoff with jitter, a maximum attempt count and a maximum elapsed time. Respect Retry-After when supplied. Persist the original body and operation ID, and avoid retrying invalid input or missing credentials.

Limits and data handling

The API accepts up to 1,000 input credits and 12,000 UTF-8 bytes per rewrite (JSON body: 20,000 bytes). Each account can run 2 concurrent generations and send 30 generation requests per minute; estimate, usage and recovery share 120 requests per minute. A shared IP also has a 300-request-per-minute cap. Generation is bounded to 90 seconds; client timeout should be at least 120 seconds. Reservations expire after 3 minutes and are released on the next balance/request operation or daily maintenance.

• Long-document jobs, streaming, native connectors and client callbacks are not included in API v1.
• Keep the source in your application and record request IDs for support. Avoid placing submitted text, credentials or sensitive returned content in ordinary application logs.
• Source text is not stored in the API request table. Successful response content is encrypted for replay, available for 24 hours, then removed during daily cleanup (within 48 hours under normal operation). Request fingerprints, key hashes, usage and financial records remain for billing, security and support. This is not a zero-retention or regional data-residency service.
• Discuss sensitive-data requirements with us before submitting that data to an API integration. Current website policies are available in the privacy policy.

Integration patterns

CMS or WordPress publishing

Read a draft → request an estimate → submit the rewrite from your server → display source, result and warnings → ask an editor to approve → update the draft. Preserve headings and formatting in your application; plain-text responses are not a guaranteed HTML or Markdown round trip.

n8n or Make automation

Store credentials in the platform’s credential store. Use an HTTP request step, persist the operation ID with the job, branch on warning fields and send uncertain results to a review queue. These are integration patterns, not currently available native nodes.

A writing feature inside a SaaS product

Call the API through your backend, enforce your own customer allowances, and let users review the replacement before applying it. Keep the original available for undo. Never embed a master API key in a browser or mobile client.

Before a production integration

1. Confirm access, the released contract, supported languages and published limits.
2. Evaluate real samples for meaning, protected terms and the intended tone.
3. Test quota exhaustion, concurrent requests, repeated operation IDs, key revocation and failed requests.
4. Confirm pricing, counting rules, result recovery and data-handling terms.
5. Keep approval and monitoring in your application before enabling automated workflows.