Perguntas frequentes
Respostas a perguntas comuns sobre a API da ReWords.AI — o que o OCR consegue ler, fontes e textos mais longos, remover texto, A ou B, novas tentativas, cobrança, uso no front-end, SDKs e como obter ajuda.
OCR
Que texto o OCR consegue ler?
Texto impresso em chinês, inglês, japonês, coreano e na maioria dos idiomas europeus. Defina language com o idioma principal
do texto: en, zh, ja, ko, fr, de, es, pt, it ou ru. A região é ignorada, então pt-BR conta como pt e
zh-TW como zh. O idioma não é detectado automaticamente: sem language, ou com qualquer outro valor, o OCR lê chinês e inglês
(normalmente japonês também), e texto coreano, cirílico ou europeu com acentos sai errado. Envie language sempre que souber o idioma, inclusive para japonês. Escrita à mão, letras muito estilizadas e texto curvo ou vertical podem não ser encontrados
ou vir divididos em pedaços — para esses casos, envie a sua própria box.
O que é um item em texts?
Uma linha de texto, não uma palavra nem um parágrafo. Um título em duas linhas volta como dois itens. Para alterá-lo, envie uma
substituição por linha, ou uma substituição cuja box cubra as duas linhas e cujo to seja o título novo inteiro, com \n
onde a nova linha deve começar.
Por que o texto parece um pouco diferente do da imagem?
Caracteres de largura total são retornados em largura normal: ５０％ＯＦＦ vira 50%OFF, e um espaço de largura total vira um
espaço normal. Alguns idiomas voltam em minúsculas (francês, alemão e russo, por exemplo), e os espaços entre as palavras
podem sumir: o coreano 여름 세일 pode voltar como 여름세일. Use o texto retornado em from; a correspondência leva as duas
coisas em conta (veja abaixo).
O OCR não encontrou meu texto ou leu errado. E agora?
Envie uma box medida por você (veja Imagens). Quando uma substituição tem box, o texto
dentro da caixa é substituído e from é só uma dica — não precisa corresponder exatamente.
Preciso chamar o OCR?
Não. Envie from e to sem box e POST /edits encontra o texto para você, de graça. Essa chamada lê o texto
primeiro, o que costuma levar 5–20 segundos (o mesmo que POST /ocr), então reserve pelo menos 90 segundos para a requisição HTTP. O OCR não ocupa nenhuma das suas 10 vagas de
job. Chame POST /ocr antes só quando quiser mostrar o texto ao usuário, deixá-lo escolher ou conferir as caixas antes de pagar
por uma edição.
E se from for só parte de uma linha?
Só essa parte muda. from: "OFF", to: "ON" na linha 50% OFF dá 50% ON. Na resposta, replacements mostra a linha
inteira: from: "50% OFF", to: "50% ON". Esses valores vêm da leitura OCR da linha, então podem vir em minúsculas ou
sem espaços (veja acima). O texto novo é desenhado no estilo da linha original: confira maiúsculas e espaços na imagem,
não neste texto.
A correspondência ignora maiúsculas e espaços ao redor. Se algumas linhas forem exatamente iguais a from, só essas linhas mudam
e as que apenas o contêm ficam como estão. Caso contrário, toda linha que o contém muda, em cada ocorrência na linha:
from: "e" transforma Summer Collection em Summ3r Coll3ction se to for 3. match: "first" limita a mudança a uma
linha, não a uma ocorrência — envie uma box e a linha nova inteira quando precisar de controle exato. Se nada
corresponder, há mais uma tentativa ignorando todos os espaços, então 여름 세일 ainda encontra a linha 여름세일.
O OCR é cobrado quando a imagem não tem texto?
Sim. A chamada retorna "texts": [] e conta como uma chamada de OCR. A mesma imagem em até 24 horas não é cobrada de novo.
E árabe, hebraico, tailandês ou hindi?
Não são suportados. O OCR ainda pode retornar linhas nessas escritas, mas a leitura e o resultado editado não são garantidos. Um job que falha com elas não é cobrado.
Posso enviar um PDF ou várias páginas de uma vez?
Não. Cada requisição aceita uma imagem JPEG, PNG ou WebP. Renderize como imagem cada página que quiser alterar e envie uma requisição por página — elas podem rodar ao mesmo tempo, até as suas 10 vagas de job.
Edição
Posso escolher a fonte, a cor ou o tamanho?
Não. O novo texto copia a fonte, a cor, o tamanho e os efeitos do texto que ele substitui. Não há parâmetros de estilo.
E se o novo texto for mais longo ou mais curto?
Ele é encaixado no espaço ao redor do texto original sem cobrir o texto vizinho. Um texto muito longo pode sair menor. Mantenha-o perto do comprimento original para o resultado mais natural.
Posso remover texto em vez de substituí-lo?
Sim — para remover texto, defina to como string vazia. O fundo atrás dele é preenchido.
Qual o tamanho máximo de from e to?
Até 200 caracteres Unicode cada (um emoji conta como um). \n em to começa uma nova linha. from só pode ficar vazio quando
você envia uma box.
Quantas alterações uma edição pode fazer?
Até 20 substituições por imagem, todas em um job e cobradas como uma edição. Quando as mesmas palavras aparecem várias vezes,
match: "all" (o padrão) muda todas e match: "first" muda só a primeira, de cima para baixo e da esquerda para a direita;
envie caixas para escolher com exatidão. Não envie duas substituições para o mesmo texto nem caixas sobrepostas — só uma delas
será aplicada, e qual delas não é definido.
Como associo replacements da resposta à minha requisição?
A resposta tem um item por linha alterada, na ordem da sua requisição. Uma substituição sem box que correspondeu a três
linhas vira três itens, de cima para baixo. Se precisar de uma correspondência um para um, envie uma box para cada
substituição ou use match: "first".
Dá para mudar coisas que não são texto?
Não. Só o texto que você indicar é alterado. Logotipos, rostos e outros objetos não são editados de propósito.
Quanto tempo um job leva?
Normalmente 1–2 minutos: 9 em cada 10 jobs terminam em 3 minutos e quase todos em 5. estimated_seconds na resposta é nossa estimativa de quando ele vai terminar; um job pode
rodar por até 10 minutos depois de sair da fila e, com a fila cheia de 30, o último pode levar cerca de 30 minutos. Todo job
fica succeeded ou failed em até 60 minutos após o envio; se isso não acontecer, pare o polling e escreva para
[email protected] com o id dele. Veja Fila e limites.
Resultados
Devo usar A ou B?
B mantém cada pixel fora do texto exatamente como no seu envio — a escolha segura para fotos de produto, documentos e qualquer coisa em que o resto da imagem não pode mudar. A redesenha a imagem inteira, o que muitas vezes integra o novo texto de forma mais natural, mas pode mudar pequenos detalhes em outros lugares. Recomendamos mostrar ao seu usuário todos os resultados bem-sucedidos — A e B, mais C (4K) quando houver — e deixá-lo escolher.
O que é C, e por que ele foi pulado?
C é a edição da IA gerada em 4K, com até 3840 px no lado maior. Ele é pulado para imagens mais largas ou mais altas que 3:1
(aspect_ratio_unsupported) e pode falhar sozinho. C nunca muda o que você paga.
Os resultados têm marca d’água? Por quanto tempo ficam guardados?
Sem marca d’água. Os links dos resultados são arquivos JPEG públicos em img.rewords.ai, guardados por pelo menos 7 dias —
baixe o que precisar. Os links de um job não mudam entre leituras. GET /edits/{id} funciona enquanto os links forem
mantidos. As imagens enviadas por trás de um image_id ficam guardadas por 24 horas.
Posso editar um resultado de novo?
Sim. Passe a url do resultado como image_url em uma nova edição — o resultado B é o melhor ponto de partida. É um
novo job e é cobrado como qualquer outro. Faça isso quando mudar o texto em etapas ou quando o primeiro resultado precisar de
uma segunda alteração.
Posso cancelar um job?
Não, não há chamada de cancelamento. Um job só custa uma edição quando chega a succeeded; se você não precisar mais dele,
ignore o resultado. Um job que nunca foi enviado não custa nada, então confira seu texto com POST /ocr antes de enviar.
Um job falhou. Como tento de novo?
Jobs com falha são grátis. Envie de novo com uma nova Idempotency-Key: a antiga retorna o mesmo job com falha.
ai_generation_failed e upstream_failed costumam dar certo numa nova tentativa; content_blocked não.
Cobrança
Quando exatamente sou cobrado?
Uma edição por job, só quando A ou B dá certo — mesmo que o outro tenha falhado. No envio, uma edição é reservada para que
os jobs já na fila sempre possam terminar; ela é liberada se o job falhar. balance e edits_remaining já têm as edições
reservadas descontadas. Veja Preços e cobrança.
Existe uma chave de teste grátis ou sandbox?
Não há chaves de teste grátis. Edite uma imagem de graça em rewords.ai para ver a qualidade e depois comece com o pacote Lite. Jobs com falha e requisições rejeitadas nunca são cobrados.
Integração
Posso chamar a API de um navegador ou app móvel?
Não. Chame-a do seu servidor. A chave de API ficaria visível no código do front-end ou no pacote do app, e qualquer pessoa que a encontrasse poderia gastar o seu saldo. A API não envia cabeçalhos CORS, então os navegadores bloqueiam chamadas diretas.
Polling ou webhooks?
Qualquer um. Webhooks precisam de um endpoint https público e economizam requisições; o polling não precisa de nada. Se o seu
endpoint puder cair, faça também polling a cada poucos minutos, até o estado final, de qualquer job do qual você não tenha
notícia 15 minutos depois do envio. Um webhook que chegue depois não faz mal: você pula o id que já tratou.
Veja Webhooks.
Como ligo um job ao meu próprio pedido ou usuário?
Guarde o id da resposta 202 junto do seu registro. Para webhooks, você também pode acrescentar sua própria referência à query
string de callback_url, que é mantida: https://example.com/hooks/rewords?order=1234.
Minha requisição deu timeout. Um job foi criado?
Talvez. Tente de novo com a mesma Idempotency-Key: você recebe o job se ele foi criado, e ele não é cobrado duas vezes. Veja Erros.
A API vai mudar sem aviso?
A versão está no caminho: /v1. Dentro de /v1 só acrescentamos coisas — novos campos opcionais, novos valores em reason ou
error.code —, então ignore campos que você não conhece e trate um código desconhecido como upstream_failed. Qualquer coisa
que quebraria um cliente vai para uma nova versão, anunciada por e-mail antes de a antiga ser desativada. Dúvidas vão para
[email protected].
Existe um SDK?
Ainda não. Baixe openapi.yaml e gere um cliente com qualquer gerador de OpenAPI 3.1, ou copie os clientes completos em Node.js e Python de Exemplos.
Minha chave de API vazou. O que faço?
Revogue-a na página de chaves de API — ela para de funcionar em até um minuto — e crie
uma nova. Todas as chaves compartilham o seu saldo, então faça isso primeiro e confira GET /account depois. Se o segredo de
webhook também vazou, redefina-o na mesma página. Veja Autenticação.
Em que fuso horário estão created_at e completed_at?
UTC, no formato ISO 8601 com o sufixo Z: 2026-11-04T10:00:00Z.
Como obter ajuda
Escreva para [email protected] ou use a página de contato para WhatsApp e TikTok. O e-mail é o caminho mais rápido para dúvidas sobre a API.
Inclua o que nos permita encontrar a requisição:
- o
iddo job (edit_...) ou oimage_id, e o horário da requisição em UTC; - os primeiros 12 caracteres da chave que você usou (
rw_live_abcd...) — nunca a chave inteira; - o
error.codee amessageque você recebeu, ou o resultado que parece errado; - a imagem, se puder compartilhá-la, e as
replacementsque você enviou.
Uma dúvida de cobrança também precisa do e-mail da sua conta rewords.ai, para encontrarmos a compra.