FAQ
Answers to common questions about the ReWords.AI API — what OCR can read, fonts and longer text, removing text, A versus B, retries, billing, front-end use, SDKs and how to get help.
OCR
Which text can OCR read?
Printed text in Chinese, English, Japanese, Korean and most European languages. Set language to the main language of
the text: en, zh, ja, ko, fr, de, es, pt, it or ru. A region is ignored, so pt-BR counts as pt and
zh-TW as zh. The language is not detected for you: without language, or with any other value, OCR reads Chinese and
English (Japanese usually too), and Korean, Cyrillic or accented European text comes out wrong. Send language whenever you know it,
Japanese included. Handwriting, heavily
stylised lettering, curved and vertical text may be missed or split into pieces — send your own box for those.
What is one item in texts?
One line of text, not a word or a paragraph. A heading on two lines comes back as two items. To change it, send one
replacement per line, or one replacement whose box covers both lines and whose to is the whole new heading, with
\n where the new line should start.
Why does the text look slightly different from the image?
Full-width characters are returned as half-width: ５０％ＯＦＦ becomes 50%OFF, and a full-width space becomes a
normal space. Some languages come back in lower case (French, German and Russian, for example), and spaces between words
can be missing: Korean 여름 세일 may come back as 여름세일. Use the returned text in from; matching allows for both
(see below).
OCR missed my text or read it wrong. What now?
Send a box that you measure yourself (see Images). When a replacement has a box,
the text inside the box is replaced and from is only a hint — it does not have to match exactly.
Do I have to call OCR?
No. Send from and to without box and POST /edits finds the text for you, free. That call then reads the
text first, which usually takes 5–20 seconds (as long as POST /ocr), so allow at least 90 seconds for the HTTP request. OCR does not use one of your 10 job slots.
Call POST /ocr first only when you want to show the user the text, let them choose, or check the boxes before paying
for an edit.
What if from is only part of a line?
Only that part changes. from: "OFF", to: "ON" on the line 50% OFF gives 50% ON. In the response,
replacements shows the full line: from: "50% OFF", to: "50% ON". These come from the OCR reading of the line, so they can be lower
case or miss spaces (see above). The new text is drawn in the style of the original line: check case and spacing in the
image, not in this text.
Matching ignores case and surrounding spaces. If some lines equal from exactly, only those lines change and lines
that only contain it are left alone. Otherwise every line that contains it changes, at every occurrence in the line:
from: "e" turns Summer Collection into Summ3r Coll3ction if to is 3. match: "first" limits the change to
one line, not to one occurrence — send a box and the whole new line when you need exact control. If nothing matches,
one more try ignores every space, so 여름 세일 still finds the line 여름세일.
Is OCR charged when the image has no text?
Yes. The call returns "texts": [] and counts as one OCR call. The same image within 24 hours is not charged again.
What about Arabic, Hebrew, Thai or Hindi?
Not supported. OCR may still return lines in those scripts, but the reading and the edited result are not guaranteed. A job that fails on them is not charged.
Can I send a PDF, or several pages at once?
No. Each request takes one JPEG, PNG or WebP image. Render each page you want to change as an image and send one request per page — they can run at the same time, up to your 10 job slots.
Editing
Can I choose the font, colour or size?
No. The new text copies the font, colour, size and effects of the text it replaces. There are no style parameters.
What if the new text is longer or shorter?
It is fitted into the space around the original text without covering neighbouring text. Very long text may come out smaller. Keep it close to the original length for the most natural result.
Can I remove text instead of replacing it?
Yes — to remove text, set to to an empty string. The background behind it is filled in.
How long can from and to be?
Up to 200 Unicode characters each (an emoji counts as one). \n in to starts a new line. from can only be empty
when you send a box.
How many changes can one edit make?
Up to 20 replacements per image, all in one job and charged as one edit. When the same words appear several times,
match: "all" (the default) changes every one and match: "first" changes only the first, top to bottom and left to
right; send boxes to choose exactly. Do not send two replacements for the same text or overlapping boxes — only one of
them will be applied, and which one is not defined.
How do I match replacements in the response to my request?
The response has one item per line that is changed, in the order of your request. A replacement without box that
matched three lines becomes three items, top to bottom. If you need a one-to-one mapping, send a box for each
replacement or use match: "first".
Can it change things that are not text?
No. Only the text you list is changed. Logos, faces and other objects are not edited on purpose.
How long does a job take?
Usually 1–2 minutes: 9 in 10 jobs finish within 3 minutes and almost all within 5. estimated_seconds in the response is our estimate of when it will finish; a job may run for
up to 10 minutes after it leaves the queue, and with a full queue of 30 the last one can take about 30 minutes. Every
job is succeeded or failed within 60 minutes of being submitted; if one is not, stop polling and write to
[email protected] with its id. See Queue and limits.
Results
Should I use A or B?
B keeps every pixel outside the text exactly as in your upload — the safe choice for product photos, documents and anything where the rest of the image must not change. A redraws the whole image, which often blends the new text more naturally but can change small details elsewhere. We recommend showing your user every result that succeeded — A and B, plus C (4K) when it is there — and letting them choose.
What is C, and why was it skipped?
C is the AI edit generated at 4K, up to 3840 px on the longest side. It is skipped for images wider or taller than
3:1 (aspect_ratio_unsupported) and may fail on its own. C never changes what you are charged.
Do results have a watermark? How long are they kept?
No watermark. Result links are public JPEG files on img.rewords.ai, kept for at least 7 days — download what you
need. A job's links do not change between reads. GET /edits/{id} works for as long as the links are kept. Uploaded
images behind an image_id are kept for 24 hours.
Can I edit a result again?
Yes. Pass the result's url as image_url in a new edit — result B is the best starting point. It is a new job
and is charged like any other. Do this when you change text in steps, or when the first result needs a second change.
Can I cancel a job?
No, there is no cancel call. A job only costs an edit when it reaches succeeded; if you no longer need it, ignore
the result. A job that was never submitted costs nothing, so check your text with POST /ocr before you submit.
A job failed. How do I retry?
Failed jobs are free. Submit again with a new Idempotency-Key: the old key returns the same failed job.
ai_generation_failed and upstream_failed often succeed on a retry; content_blocked will not.
Billing
When exactly am I charged?
One edit per job, only when A or B succeeds — even if the other failed. When you submit, one edit is reserved so
jobs already queued can always finish; it is released if the job fails. balance and edits_remaining already have
reserved edits taken off. See Pricing and billing.
Is there a free test key or sandbox?
There are no free test keys. Edit one image free on rewords.ai to see the quality, then start with the Lite pack. Failed jobs and rejected requests are never charged.
Integration
Can I call the API from a browser or mobile app?
No. Call it from your server. The API key would be visible in front-end code or an app bundle, and anyone who finds it can spend your balance. The API does not send CORS headers, so browsers block direct calls.
Polling or webhooks?
Either. Webhooks need a public https endpoint and save requests; polling needs nothing. If your endpoint may be down,
also poll any job you have not heard about 15 minutes after submitting, every few minutes until it is final. A webhook
that arrives later is harmless: you skip the id you already handled. See Webhooks.
How do I link a job to my own order or user?
Keep the id from the 202 response next to your record. For webhooks you can also add your own reference to the
callback_url query string, which is kept: https://example.com/hooks/rewords?order=1234.
My request timed out. Was a job created?
Maybe. Retry with the same Idempotency-Key: you get the job back if it was created, and it is not charged twice. See Errors.
Will the API change under me?
The version is in the path: /v1. Within /v1 we only add things — new optional fields, new values in reason or
error.code — so ignore fields you do not know and treat an unknown code like upstream_failed. Anything that would
break a client goes into a new version, announced by email before the old one is retired. Questions go to
[email protected].
Is there an SDK?
Not yet. Download openapi.yaml and generate a client with any OpenAPI 3.1 generator, or copy the complete Node.js and Python clients on Examples.
My API key leaked. What do I do?
Revoke it on the API keys page — it stops working within a minute — and create
a new one. Every key shares your balance, so do this first and check GET /account afterwards. If the webhook secret
leaked too, reset it on the same page. See Authentication.
What time zone are created_at and completed_at in?
UTC, in ISO 8601 form with a Z suffix: 2026-11-04T10:00:00Z.
Getting help
Write to [email protected], or use the contact page for WhatsApp and TikTok. Email is the fastest route for API questions.
Include what lets us find the request:
- the job
id(edit_...) orimage_id, and the time of the request in UTC; - the first 12 characters of the key you used (
rw_live_abcd...) — never the whole key; - the
error.codeandmessageyou received, or the result that looks wrong; - the image, if you can share it, and the
replacementsyou sent.
A billing question also needs the email address of your rewords.ai account, so we can find the purchase.