Replace text in an image
Queues an edit and returns immediately. Pass callback_url, or poll GET /edits/{id}: every 5 seconds while
the job is processing or queued with queue_position 0, and every 30 seconds while it is further back
in the queue. One edit is reserved now and refunded automatically if neither A nor B
succeeds.
If a replacement has no box, we read the image before answering, so this call usually takes 5–20 seconds
(allow 90) and can return 422 text_not_found.
bearerAuthAuthorizationBearer <token>Send Authorization: Bearer rw_live_.... Create up to 5 keys at https://rewords.ai/developers/keys/ once your account has API balance.
Idempotency-Key?stringResending the same key within 24 hours returns 202 with the original job's id and its current status
(it may already be processing or finished). It is not charged again, even if the request body differs.
Keys are per account, shared by all of its API keys.
length <= 128- body
Provide exactly one of image_id, image_url or image_base64; none or more than one returns
400 invalid_request.
replacements*array<>1 <= items <= 20match?stringOnly for replacements without box: replace every matching line (all) or the first one, top to bottom,
left to right (first). Matching ignores case and surrounding spaces, and tries an exact line first, then a
line that contains the text, then both again ignoring every space.
"all""all""first"language?LanguageMain language of the text: en, zh, ja, ko, fr, de, es, pt, it or ru. Case and a region part
are ignored (pt-BR counts as pt). The language is not detected automatically: without it, or with any other
value, OCR reads Chinese and English (usually Japanese too), and other languages such as Korean or Russian come
out wrong. Send it whenever you know it. In an edit it is also used when we read the text: to find from
when a replacement has no box, and to fit the new text into result B.
callback_url?stringAn https URL that receives the editCompleted webhook.
^https://uriimage_url*stringPublic http(s) URL of a JPEG, PNG or WebP image up to 20 MB. We download it once, while handling the
request; we follow up to 3 redirects and give up after 15 seconds. A URL that cannot be downloaded, or
that points to a private network address (such as localhost, 10.x.x.x or 192.168.x.x), returns
400 invalid_image.
uriEdit accepted and queued.
application/json- response
id*stringstatus*string"queued""processing""succeeded""failed"queue_position?integerWhile queued: jobs waiting ahead of this one. Jobs already running are not counted, so 0 means next to start.
estimated_seconds?integerWhile queued, our estimate of the seconds until this job will finish.
results?replacements?array<>Replacements as applied: one item per line that is changed, with the box we located and the line's full
text in from and to. Items keep the order of your request; a replacement that matched several lines
becomes several items, top to bottom.
charged?integerEdits charged (1 when A or B succeeded, otherwise 0).
balance?integerEdits left on the account when this response was made — the same as edits_remaining in GET /account
(edits reserved for unfinished jobs, including this one, are already taken off).
error?Present when failed. code is one of content_blocked, ai_generation_failed, timeout,
upstream_failed or invalid_image (the file passed the upload checks but could not be decoded).
created_at?stringdate-timecompleted_at?stringdate-timecurl -X POST 'https://api.rewords.ai/v1/edits' \ -H 'Authorization: Bearer rw_live_your_key' \ -H 'Content-Type: application/json' \ -d '{ "image_id": "img_abc123", "replacements": [ { "from": "SALE", "to": "HOT DEAL", "box": [ 120, 80, 300, 60 ] }, { "from": "50% OFF", "to": "70% OFF" } ], "match": "all", "language": "en", "callback_url": "https://example.com/rewords-webhook"}'{ "id": "edit_9f8e7d", "status": "queued", "queue_position": 3, "estimated_seconds": 210, "replacements": [ { "from": "SALE", "to": "HOT DEAL", "box": [ 120, 80, 300, 60 ] }, { "from": "50% OFF", "to": "70% OFF", "box": [ 140, 160, 260, 50 ] } ], "balance": 299, "created_at": "2026-11-04T10:00:00Z"}