brunoquiodetto/ai-text-humanizer-api

🤖 API REST para humanização de textos e chamados usando inteligência artificial. Transforma mensagens técnicas em comunicação empática e humanizada.

1.0.0 2025-09-11 12:58 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Bruno Quiodetto

• php
• api
• nlp
• ai
• rest-api
• text-processing
• artificial-intelligence
• OpenRouter
• text-humanizer
• humanization

README

Uma API REST moderna para humanização de textos e chamados usando inteligência artificial. Transforme comunicação técnica e formal em mensagens empáticas e humanizadas.

✨ Características

• 🤖 IA Avançada: Integração com OpenRouter para múltiplos modelos
• 📱 Interface Moderna: Design responsivo inspirado no Apple
• 🎯 Fácil de Usar: API REST simples e intuitiva
• 🔧 Configurável: Sistema flexível de configuração
• 🛡️ Robusto: Tratamento completo de erros
• 📖 Bem Documentado: Código limpo e documentação completa

🚀 Instalação Rápida

# Via Composer
composer create-project brunoquiodetto/ai-text-humanizer-api

# Ou como dependência
composer require brunoquiodetto/ai-text-humanizer-api

🚀 Instalação e Configuração

Pré-requisitos

• PHP 7.4 ou superior
• Extensão cURL habilitada
• Servidor web (Apache/Nginx)
• Conta no OpenRouter para obter API key

1. Clone ou baixe o projeto

git clone [URL_DO_SEU_REPOSITORIO]
cd ai-text-humanizer-api

2. Configure a API Key

1. Copie o arquivo de configuração de exemplo:

   # Windows
   copy config\config.example.php config\config.php
   
   # Linux/Mac
   cp config/config.example.php config/config.php

2. Edite o arquivo config/config.php e substitua SEU_OPENROUTER_API_KEY_AQUI pela sua API key do OpenRouter:

   'api_key' => 'sk-or-v1-sua-api-key-aqui',

3. Configure o servidor web

Configure seu servidor web para apontar o DocumentRoot para a pasta public/.

4. Como obter sua API Key do OpenRouter

1. Acesse OpenRouter
2. Crie uma conta ou faça login
3. Vá para a seção "API Keys"
4. Gere uma nova API key
5. Copie a key e cole no arquivo config/config.php

⚠️ IMPORTANTE: Nunca compartilhe sua API key publicamente ou faça commit dela no Git!

Estrutura do Projeto

api/
├── public/
│   ├── index.php          # Ponto de entrada da API
│   └── .htaccess          # Configuração do Apache
├── src/
│   ├── controllers/       # Controladores da API
│   │   └── humanizercontroller.php
│   ├── services/          # Serviços
│   │   └── openrouterservice.php
│   ├── utils/            # Utilitários
│   │   └── promptloader.php
│   └── bootstrap.php     # Arquivo de inicialização
└── config/
    ├── config.php        # Configurações gerais
    └── prompts/          # Arquivos de prompt
        └── HumanizadordeChamado.yaml

Endpoints Disponíveis

1. Humanizador de Texto (POST /humanize)

Humaniza textos de chamados técnicos, tornando-os mais claros e profissionais.

Parâmetros:

• entrada (string, obrigatório): O texto a ser humanizado
• NmsgD (string, obrigatório): Indicador se é a primeira mensagem do dia

Exemplo de requisição:

{
    "entrada": "<p>me envia anexo do gestor pra eu te dar acesso</p>",
    "NmsgD": "1"
}

Exemplo de resposta:

{
    "success": true,
    "response": "<p>Bom dia! Por favor, me envie em anexo a aprovação do seu gestor para que eu possa conceder acesso.</p>"
}

2. Health Check (GET /health)

Verifica o status da API.

Resposta:

{
    "status": "ok",
    "timestamp": "2025-09-10 14:30:00",
    "version": "1.0.0"
}

Códigos de Status HTTP

• 200: Sucesso
• 400: Erro de validação (parâmetros inválidos ou ausentes)
• 405: Método não permitido
• 404: Endpoint não encontrado
• 500: Erro interno do servidor

Formato das Respostas

Sucesso

{
    "success": true,
    "response": "Resultado da operação"
}

Erro

{
    "success": false,
    "error": "Descrição do erro"
}

Segurança

• CORS habilitado para todas as origens
• Headers de segurança configurados
• Validação de entrada implementada
• Tratamento de erros adequado

🧪 Como Testar a API

Método 1: Testando Localmente via Interface Web

O projeto já inclui scripts automáticos para inicialização do servidor em ambiente de desenvolvimento. Basta executar o comando de start disponível no seu gerenciador de dependências ou IDE. Consulte a documentação do projeto ou o arquivo package.json/composer.json para detalhes sobre os comandos disponíveis.

1. Acesse http://seu-servidor/teste.html no navegador
2. Preencha o formulário com um texto para humanizar
3. Clique em "🚀 Testar API"
4. Veja o resultado na tela

Método 2: cURL (Terminal)

# Teste do health check
curl -X GET http://seu-servidor/health

# Teste do humanizador
curl -X POST http://seu-servidor/humanize \
  -H "Content-Type: application/json" \
  -d '{
    "entrada": "<p>Me envia anexo do gestor pra eu te dar acesso</p>",
    "NmsgD": "1"
  }'

Método 3: Postman ou Insomnia

1. URL: POST http://seu-servidor/humanize
2. Headers: Content-Type: application/json
3. Body (JSON):

   {
     "entrada": "<p>Me envia anexo do gestor pra eu te dar acesso</p>",
     "NmsgD": "1"
   }

Método 4: JavaScript (Frontend)

const response = await fetch('/humanize', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        entrada: '<p>Me envia anexo do gestor pra eu te dar acesso</p>',
        NmsgD: '1'
    })
});

const result = await response.json();
console.log(result);

🔧 Solução de Problemas

Erro: "API Key inválida"

• Verifique se copiou a API key corretamente
• Confirme se a key está ativa no OpenRouter
• Certifique-se de que não há espaços extras na key
• Se for uma key gratuita atente-se as limitações de timeout ou limites de requisições.

Erro: "Arquivo de configuração não encontrado"

• Verifique se criou o arquivo config/config.php a partir do config.example.php
• Confirme as permissões de leitura do arquivo

Erro: "Endpoint não encontrado"

• Verifique se o servidor web está apontando para a pasta public/
• Confirme se o mod_rewrite está habilitado (Apache)
• Teste primeiro o endpoint /health

Erro: "CORS"

• Os headers CORS já estão configurados
• Se persistir, verifique se há proxy/firewall bloqueando