API de humanizador de IA: Humanizer API v2 e Detector API para devs

A API de humanizador de IA do Academic Humanizer tem dois endpoints REST para desenvolvedores e instituições: POST /api/v2/external/humanize, que devolve o texto humanizado com as alterações por frase, e POST /api/v2/external/detector, que devolve uma avaliação de detecção de IA para até 100.000 caracteres. Os dois usam uma chave de API do lado do servidor e consomem o mesmo saldo de créditos da sua conta.

Este post explica para quem é a API, como funcionam a autenticação e o controle de acesso, o que cada endpoint devolve e como os créditos são contados. A referência completa está em /docs.

Para quem é a API do AI humanizer

O editor web atende pesquisadores individuais. A API atende produtos e equipes que lidam com textos acadêmicos em volume ou dentro da própria interface:

• Plataformas de escrita que querem oferecer uma etapa de humanização dentro do próprio editor.
• Ferramentas de LMS e de material didático que precisam de um sinal de detecção de IA como uma das entradas de um processo de revisão humana, não como um veredito automático.
• Serviços de edição e revisão de texto que passam os rascunhos dos clientes por uma primeira etapa padronizada antes de um editor lê-los.
• Escritórios de pesquisa que querem verificar textos de propostas ou relatórios em lote.

Se o seu uso envolve trabalhos de estudantes, projete-o para que as pessoas tomem as decisões finais. O resultado do detector é uma evidência a ser revisada, e nosso post sobre o que considerar antes de questionar a autoria de um estudante explica por quê.

Autenticação, listas de IPs permitidos e limites de taxa

Crie uma chave em /api com a sessão iniciada. A chave é exibida uma única vez, na criação, e o Academic Humanizer armazena apenas um hash dela, então copie-a direto para o seu gerenciador de segredos ou para uma variável de ambiente do servidor. Nunca a inclua em código de navegador ou de aplicativo móvel.

Envie a chave no cabeçalho X-API-Key. Esse é o cabeçalho recomendado na documentação; o servidor também aceita a chave como bearer token no cabeçalho Authorization.

Cada requisição passa então por algumas verificações antes de qualquer texto ser processado.

1. Verificação da chaveA chave precisa existir e estar ativa, e a conta associada também precisa estar ativa.
2. Lista de IPs permitidosNo modo restrito, só são aceitas requisições dos IPs ou faixas CIDR que você cadastrou.
3. Limite de taxaRequisições acima do limite por segundo da chave são rejeitadas com HTTP 429.
4. ProcessamentoO texto é humanizado ou analisado, e os créditos são conferidos com o seu saldo.
5. Resultado salvoO resultado é salvo na sua conta e devolvido em JSON.

O acesso por IP tem dois modos: público, em que qualquer IP pode fazer chamadas com uma chave válida, e restrito, em que só os IPs ou blocos CIDR cadastrados podem. Vale ativar o modo restrito em qualquer servidor de produção com endereço de saída fixo. O limite de taxa padrão é de 10 requisições por segundo.

O endpoint Humanize

O corpo da requisição é um JSON com um campo obrigatório, originalContent, e um opcional, researchField. Se você enviar uma área de pesquisa, ela precisa ser um dos nomes suportados, escritos em inglês: Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences ou Medical and Health Sciences. Omita o campo ou envie null se não precisar dele.

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

Uma chamada bem-sucedida devolve HTTP 201 com um corpo JSON contendo:

• humanizedText: o texto reescrito completo.
• changedCount: quantas frases foram alteradas.
• sentences: uma lista de entradas no nível da frase, cada uma com as posições de início e fim no texto original, a frase de origem, a frase humanizada e um indicador changed. A lista pode vir vazia.

O ID do resultado salvo vem no cabeçalho de resposta X-Humanizer-Id, para que você possa ligar uma requisição no seu sistema ao resultado salvo na conta do usuário. Observe que changed indica se uma frase foi reescrita; não é um veredito de detecção de IA. Para isso, use o endpoint Detector.

As posições das frases facilitam exibir um diff na sua própria interface: destaque os trechos alterados e deixe o usuário aceitar ou editar cada um. Os usuários devem revisar cada resultado antes de usá-lo, já que a reescrita por IA pode introduzir erros ou mudar o sentido.

O endpoint Detector

O endpoint Detector recebe um único campo obrigatório, text, com até 100.000 caracteres. Ele devolve o status da análise, a contagem de caracteres, o tempo decorrido, uma avaliação geral do documento, os resultados dos detectores e creditUsed. Áreas de pesquisa não são usadas aqui.

Um padrão comum é chamar primeiro o Detector, mostrar ao usuário quais trechos apresentam sinais e chamar o Humanize só nas seções que ele escolher. Assim, tanto o custo quanto as alterações ficam no mínimo.

Como os créditos da API são contados

Os dois endpoints gastam créditos da conta dona da chave. Cada endpoint conta de um jeito.

O Humanize custa 1 crédito a cada 500 caracteres, arredondado para cima por requisição, e só é cobrado quando um resultado completo é salvo. O Detector custa 1 crédito a cada 5.000 caracteres, arredondado para cima. Se o saldo for insuficiente, a requisição falha com um erro de créditos insuficientes em vez de devolver um resultado parcial. Planos e pacotes estão descritos em como funcionam os créditos e os preços, e os preços atuais estão em /pricing.

Erros que você deve tratar

Os corpos de erro incluem um código curto legível por máquina, então baseie sua lógica no código, e não no texto da mensagem.

Perguntas frequentes

Como obtenho uma chave de API?

Entre na sua conta e abra /api. Crie uma chave, copie-a na hora (ela só é exibida uma vez) e guarde-a no seu servidor.

Posso restringir quais servidores usam minha chave?

Sim. Mude o acesso por IP para o modo restrito e cadastre os IPs ou faixas CIDR autorizados a chamar a API. Requisições de qualquer outro lugar são rejeitadas com HTTP 403.

Existe um plano gratuito para a API?

A API usa os mesmos créditos do aplicativo web. Contas novas recebem 10 créditos grátis uma única vez, o suficiente para testar o endpoint Humanize em alguns trechos curtos.

Com quais detectores o resultado é verificado?

O Academic Humanizer é validado com Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling e Originality.ai. Como em qualquer ferramenta, os resultados variam conforme o detector e nenhum resultado é garantido.

Desenvolvendo com o Academic Humanizer

Se o seu produto já lida com manuscritos, resumos ou trabalhos acadêmicos, a API permite adicionar uma etapa de humanização ou uma verificação de detecção sem mandar os usuários para outro lugar. Comece com uma chave de teste, passe alguns parágrafos reais pelos dois endpoints e leia a referência completa em /docs antes de ir para produção.