常见问题
关于 ReWords.AI API 的常见问题——OCR 能识别什么、字体和更长的文字、删除文字、A 与 B 的区别、重试、计费、前端调用、SDK 以及如何获取帮助。
OCR
OCR 能识别哪些文字？
中文、英文、日文、韩文和大多数欧洲语言的印刷体文字。把 language 设为文字的主要语言：
en、zh、ja、ko、fr、de、es、pt、it 或 ru。地区部分会被忽略，所以 pt-BR 按 pt、zh-TW 按 zh 处理。
我们不会自动判断语言：不传 language 或传其他值时，OCR 按中文和英文识别（日文通常也能识别），韩文、俄文等西里尔字母以及带重音的欧洲文字会识别错误。只要知道语言就请传 language，日文也一样。
手写、风格强烈的艺术字、弯曲和竖排的文字可能识别不到或被拆成几段——这些情况请发送你自己的 box。
texts 里的一项是什么？
一行文字，不是一个词也不是一个段落。两行的标题会返回两项。要修改它，可以每行发送一个替换；
或者发送一个替换，让它的 box 覆盖两行，to 写完整的新标题，在需要换行的地方加 \n。
为什么返回的文字和图片上的看起来略有不同？
全角字符会以半角返回：５０％ＯＦＦ 变成 50%OFF，全角空格变成普通空格。有些语言会以小写返回（例如法语、德语和俄语），
词与词之间的空格也可能丢失：韩文 여름 세일 可能返回成 여름세일。请在 from 中使用返回的文字；匹配对这两种情况都有处理（见下文）。
OCR 漏掉了我的文字或识别错了，怎么办？
发送你自己测量的 box（见图片）。替换带有 box 时，框内的文字会被替换，
from 只是一个提示——不需要完全匹配。
必须先调用 OCR 吗？
不必。发送不带 box 的 from 和 to，POST /edits 会免费帮你找到文字。这样调用会先识别文字，通常需要 5–20 秒（和 POST /ocr 一样），
所以 HTTP 请求至少留出 90 秒。OCR 不占用你的 10 个任务名额。
只有当你想把文字展示给用户、让他们选择，或在为编辑付费之前检查框时，才需要先调用 POST /ocr。
如果 from 只是一行的一部分呢？
只修改那一部分。在 50% OFF 这一行上，from: "OFF"、to: "ON" 得到 50% ON。
在响应中，replacements 显示完整的一行：from: "50% OFF"、to: "50% ON"。
这两个值来自 OCR 对这一行的识别结果，所以可能是小写或缺少空格（见上文）。新文字会按原来那一行的样式绘制，
大小写和空格请以图片为准，而不是这里的文字。
匹配时忽略大小写和首尾空格。如果有些行与 from 完全相同，就只修改这些行，仅仅包含它的行保持不变。
否则，所有包含它的行都会修改，并且修改行内每一处出现：如果 to 是 3，from: "e" 会把 Summer Collection
变成 Summ3r Coll3ction。match: "first" 把修改限制在一行，而不是一处——需要精确控制时，请发送 box 和完整的新一行。
如果都匹配不上，还会忽略所有空格再试一次，所以 여름 세일 也能找到 여름세일 这一行。
图片里没有文字，OCR 也扣费吗？
扣费。调用返回 "texts": []，算作一次 OCR 调用。24 小时内同一张图片不会再次扣费。
阿拉伯语、希伯来语、泰语或印地语呢？
不支持。OCR 仍可能返回这些文字的行，但识别结果和编辑结果都没有保证。在这些文字上失败的任务不扣费。
可以发送 PDF，或一次发送多页吗？
不可以。每个请求只接收一张 JPEG、PNG 或 WebP 图片。把要修改的每一页渲染成图片，每页发送一个请求—— 它们可以同时运行，最多占满你的 10 个任务名额。
编辑
可以选择字体、颜色或字号吗？
不可以。新文字会沿用被替换文字的字体、颜色、字号和效果。没有样式参数。
新文字更长或更短怎么办？
它会被放进原文字周围的空间，不会盖住相邻的文字。很长的文字可能会变小。长度和原文接近时效果最自然。
可以删除文字而不是替换吗？
可以——要删除文字，把 to 设为空字符串。文字背后的背景会被补全。
from 和 to 最长多少？
各自最多 200 个 Unicode 字符（一个表情符号算一个）。to 中的 \n 表示换行。只有发送 box 时，from 才可以为空。
一次编辑可以改多少处？
每张图片最多 20 处替换，全部在一个任务里，按一次编辑扣费。同样的文字出现多次时，
match: "all"（默认）会全部修改，match: "first" 只修改第一处（从上到下、从左到右）；要精确选择请发送框。
不要为同一段文字发送两个替换，也不要发送重叠的框——只有其中一个会生效，而且是哪一个并不确定。
如何把响应里的 replacements 和我的请求对应起来？
响应中每一行被修改的文字对应一项，按你请求的顺序排列。一个不带 box 的替换如果匹配了三行，就会变成三项，从上到下排列。
如果需要一一对应，请为每个替换发送 box，或使用 match: "first"。
能修改文字以外的东西吗？
不能。只会修改你列出的文字。Logo、人脸和其他物体刻意不做编辑。
一个任务需要多长时间？
通常 1–2 分钟：九成任务 3 分钟内完成，几乎全部在 5 分钟内完成。响应中的 estimated_seconds 是我们对完成时间的估计；任务离开队列后最多运行 10 分钟，
队列满 30 个时，最后一个大约需要 30 分钟。每个任务都会在提交后 60 分钟内变为 succeeded 或 failed；
如果没有，请停止轮询，并带上它的 id 写信到 [email protected]。见队列与限制。
结果
应该用 A 还是 B？
B 让文字以外的每个像素都和你上传的完全一样——商品图、文档以及其他不能改动画面其余部分的场景，选它最稳妥。 A 会重绘整张图，新文字往往融合得更自然，但其他地方的小细节可能会变。建议把成功的结果都展示给用户（A 和 B，有 C（4K）时也包括 C），让用户自己选。
C 是什么，为什么被跳过了？
C 是以 4K 生成的 AI 编辑结果，最长边最多 3840 px。宽或高超过 3:1 的图片会跳过它（aspect_ratio_unsupported），
它也可能单独失败。C 永远不会改变扣费。
结果有水印吗？会保存多久？
没有水印。结果链接是 img.rewords.ai 上的公开 JPEG 文件，至少保留 7 天——需要的请下载。
同一个任务的链接在多次查询之间不会变。只要链接还在，GET /edits/{id} 就能用。image_id 对应的上传图片保留 24 小时。
可以再次编辑结果吗？
可以。把结果的 url 作为新编辑的 image_url 传入——结果 B 是最好的起点。这是一个新任务，和其他任务一样扣费。
分步修改文字，或第一次的结果还需要再改一处时，可以这样做。
可以取消任务吗？
不可以，没有取消接口。任务只有变为 succeeded 时才扣一次编辑；如果不再需要，忽略结果即可。
没有提交的任务不花钱，所以提交前可以先用 POST /ocr 检查文字。
任务失败了，怎么重试？
失败的任务免费。用一个新的 Idempotency-Key 重新提交：旧的 key 会返回同一个失败任务。
ai_generation_failed 和 upstream_failed 重试后常常能成功；content_blocked 不会。
计费
到底什么时候扣费？
每个任务一次编辑，只在 A 或 B 成功时扣费——即使另一个失败了。提交时会预留一次编辑，保证已经排队的任务总能完成；
任务失败时会释放。balance 和 edits_remaining 已经扣除了预留的编辑。见价格与计费。
有免费的测试密钥或沙盒吗？
没有免费的测试密钥。可以在 rewords.ai 上免费编辑一张图片看看效果，然后从 Lite 包开始。 失败的任务和被拒绝的请求永远不扣费。
集成
可以从浏览器或移动应用调用 API 吗？
不可以。请从你的服务器调用。API 密钥会暴露在前端代码或应用安装包里，任何找到它的人都能花你的余额。 API 不发送 CORS 响应头，所以浏览器会拦截直接调用。
轮询还是 Webhook？
都可以。Webhook 需要一个公开的 https 地址，能节省请求；轮询什么都不需要。如果你的接收端可能宕机，
对于提交 15 分钟后仍没有收到通知的任务，也要每隔几分钟轮询一次，直到出最终结果。之后才到达的 Webhook 不会造成问题：
跳过已经处理过的 id 即可。见 Webhook。
如何把任务和我自己的订单或用户关联起来？
把 202 响应中的 id 和你的记录存在一起。对于 Webhook，你也可以在 callback_url 的查询字符串里加上自己的标识，
它会被保留：https://example.com/hooks/rewords?order=1234。
我的请求超时了，任务创建了吗？
可能创建了。用同一个 Idempotency-Key 重试：如果任务已创建，你会拿回它，并且不会被扣两次费。 见错误。
API 会在我不知情的情况下改变吗？
版本号在路径里：/v1。在 /v1 内我们只做新增——新的可选字段、reason 或 error.code 的新值——
所以请忽略你不认识的字段，并把未知错误码当作 upstream_failed 处理。任何会破坏客户端的改动都会放进新版本，
并在旧版本下线前通过邮件通知。有问题请写信到 [email protected]。
有 SDK 吗？
暂时没有。下载 openapi.yaml，用任意 OpenAPI 3.1 生成器生成客户端， 或者直接复制示例中完整的 Node.js 和 Python 客户端。
我的 API 密钥泄露了，怎么办？
在 API 密钥页面吊销它——一分钟内就会失效——然后创建一个新的。
所有密钥共享你的余额，所以请先做这一步，再检查 GET /account。如果 Webhook 密钥也泄露了，在同一页面重置它。
见认证。
created_at 和 completed_at 是哪个时区？
UTC，ISO 8601 格式，带 Z 后缀：2026-11-04T10:00:00Z。
获取帮助
写信到 [email protected]，或者通过 联系页面使用 WhatsApp 和 TikTok。API 相关问题用邮件最快。
请附上能让我们找到这次请求的信息：
- 任务
id（edit_...）或image_id，以及请求的 UTC 时间； - 你所用密钥的前 12 个字符（
rw_live_abcd...）——千万不要发送完整密钥； - 你收到的
error.code和message，或者看起来不对的结果； - 如果可以分享，附上图片以及你发送的
replacements。
计费问题还需要你的 rewords.ai 账号邮箱，方便我们找到对应的购买记录。