Skip to main content
This guide takes you from an API key to a humanized result. You submit text, wait for the job to finish, then read the output.

​
Prerequisites

Before you begin, you need:
  • A Wibble account.
  • API words in your balance. Each request reserves words equal to its input word count. Buy word packs and learn how billing works in Words and billing.
  • An API key with the humanize scope. Keys look like wib_live_.... Create one at https://wibble.ai/dashboard/api.
Keep your API key on the server. Anyone with the key can spend your account’s API words.

​
Get started

1

Submit a job

Send your text to POST /humanize. Wibble reserves the required API words and responds with HTTP 202 and a job in status queued.
curl https://wibble.ai/api/v1/humanize \
  -H "Authorization: Bearer wib_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "The mitochondria is the powerhouse of the cell."}'
The response includes the job id and a status_url to poll:
Response
{
  "id": "7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "status": "queued",
  "mode": "humanize",
  "input_words": 9,
  "words_reserved": 9,
  "words_charged": 9,
  "status_url": "https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "current_stage": "detecting_language",
  "detected_language": null,
  "created_at": "2026-06-14T12:00:00.000Z",
  "completed_at": null
}
2

Wait for the result

Poll GET /humanize/{id} until status is succeeded or failed. A single lookup looks like this:
curl
curl https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10 \
  -H "Authorization: Bearer wib_live_..."
In practice, loop until the job reaches a terminal status. Poll about every 2.5 seconds, and stop on succeeded or failed. Lookups are limited to 120 requests per minute per key, so keep the interval at or above the recommended value.
import time
import requests

headers = {"Authorization": "Bearer wib_live_..."}
status_url = "https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10"

while True:
    response = requests.get(status_url, headers=headers)
    job = response.json()

    if job["status"] == "succeeded":
        print(job["output"])
        break
    if job["status"] == "failed":
        print("Job failed:", job["error"]["code"], job["error"]["message"])
        break

    time.sleep(2.5)
A job that never finishes is marked failed after about an hour with the error code job_expired, and its reserved words are refunded. Treat a failed status as terminal and stop polling.
3

Read the output

A succeeded job returns the humanized text in output:
Response
{
  "id": "7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "status": "succeeded",
  "mode": "humanize",
  "input_words": 9,
  "words_reserved": 9,
  "words_charged": 9,
  "status_url": "https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "current_stage": "completed",
  "detected_language": "en",
  "created_at": "2026-06-14T12:00:00.000Z",
  "completed_at": "2026-06-14T12:00:42.000Z",
  "output": "Mitochondria are the cell's powerhouses."
}
If a job failed, read the error object for the reason. The reserved words are refunded automatically.

​
Skip polling with a webhook

Instead of polling, pass a webhook_url when you submit. Wibble sends a signed POST to that URL when the job finishes.
curl
curl https://wibble.ai/api/v1/humanize \
  -H "Authorization: Bearer wib_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The mitochondria is the powerhouse of the cell.",
    "webhook_url": "https://example.com/webhooks/wibble"
  }'
Verify the signature before trusting a delivery. See Webhooks for the payload, delivery behavior, and verification steps. Keep polling available as a fallback.
Retrying a submission? Send an Idempotency-Key header so a repeated request returns the original job instead of creating a duplicate. See Idempotency for how safe retries work.
You submitted text, waited for the job to reach succeeded, and read the humanized output. You now have the full request-and-poll loop working.

​
Next steps

Humanization

What the humanizer does, the request options, supported languages, and responsible use.

API reference

The full job lifecycle, limits, error codes, and webhooks.