AI humanizer API: Humanizer API v2 e Detector API per sviluppatori

L'AI humanizer API di Academic Humanizer ha due endpoint REST per sviluppatori e istituzioni: POST /api/v2/external/humanize, che restituisce il testo umanizzato con le modifiche a livello di frase, e POST /api/v2/external/detector, che restituisce una valutazione di rilevamento AI fino a 100.000 caratteri. Entrambi usano una chiave API lato server e attingono allo stesso saldo crediti del tuo account.

Questo post spiega a chi è destinata l'API, come funzionano autenticazione e controllo degli accessi, cosa restituisce ogni endpoint e come vengono conteggiati i crediti. La documentazione completa si trova su /docs.

A chi è destinata l'API dell'AI humanizer

L'editor web è adatto ai singoli ricercatori. L'API è adatta a prodotti e team che gestiscono testi accademici in grandi volumi o all'interno della propria interfaccia:

• Piattaforme di scrittura che vogliono offrire un passaggio di umanizzazione nel proprio editor.
• LMS e strumenti didattici che hanno bisogno di un segnale di rilevamento AI come uno degli elementi di un processo di revisione umana, non come verdetto automatico.
• Servizi di editing e correzione di bozze che sottopongono le bozze dei clienti a un primo passaggio uniforme prima che un editor le legga.
• Uffici ricerca che vogliono controllare in blocco testi di progetti o report.

Se il tuo utilizzo riguarda lavori di studenti, progettalo in modo che le decisioni finali spettino alle persone. L'output di un detector è un elemento da valutare, e il nostro post su cosa considerare prima di mettere in dubbio la paternità di un lavoro studentesco spiega perché.

Autenticazione, allow-list IP e rate limit

Crea una chiave su /api dopo aver effettuato l'accesso. La chiave viene mostrata una sola volta, al momento della creazione, e Academic Humanizer ne conserva solo un hash, quindi copiala subito nel tuo secret manager o in una variabile d'ambiente del server. Non includerla mai nel codice di browser o app mobile.

Invia la chiave nell'header X-API-Key. È l'header consigliato dalla documentazione; il server accetta la chiave anche come bearer token nell'header Authorization.

Ogni richiesta supera poi alcuni controlli prima che il testo venga elaborato.

1. Controllo della chiaveLa chiave deve esistere ed essere attiva, e l'account a cui appartiene deve essere attivo.
2. Allow-list IPIn modalità limitata vengono accettate solo le richieste dagli IP o dagli intervalli CIDR che hai indicato.
3. Rate limitLe richieste oltre il limite al secondo previsto per la chiave vengono rifiutate con HTTP 429.
4. ElaborazioneIl testo viene umanizzato o analizzato, e i crediti vengono verificati rispetto al tuo saldo.
5. Risultato salvatoIl risultato viene salvato nel tuo account e restituito in JSON.

L'accesso IP ha due modalità: pubblica, in cui qualsiasi IP può effettuare chiamate con una chiave valida, e limitata, in cui possono farlo solo gli IP o i blocchi CIDR indicati. Conviene attivare la modalità limitata su qualsiasi server di produzione con un indirizzo di uscita fisso. Il rate limit predefinito è di 10 richieste al secondo.

L'endpoint Humanize

Il corpo della richiesta è un JSON con un campo obbligatorio, originalContent, e un campo facoltativo, researchField. Se invii un campo di ricerca, deve essere uno dei nomi supportati: Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences o Medical and Health Sciences. Omettilo o invia null se non ti serve.

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"}'

Una chiamata riuscita restituisce HTTP 201 con un corpo JSON che contiene:

• humanizedText: il testo riscritto completo.
• changedCount: quante frasi sono state modificate.
• sentences: un array di voci a livello di frase, ciascuna con gli offset di inizio e fine nel testo originale, la frase di partenza, la frase umanizzata e un flag changed. L'array può essere vuoto.

L'ID del risultato salvato viene restituito nell'header di risposta X-Humanizer-Id, così puoi collegare una richiesta nel tuo sistema al risultato salvato nell'account dell'utente. Tieni presente che changed indica se una frase è stata riscritta; non è un verdetto di rilevamento AI. Per quello usa l'endpoint Detector.

Gli offset delle frasi rendono semplice mostrare un diff nella tua interfaccia: evidenzia i tratti modificati e lascia che l'utente accetti o modifichi ciascuno. Gli utenti dovrebbero rivedere ogni output prima di usarlo, perché la riscrittura con AI può introdurre errori o spostare il significato.

L'endpoint Detector

L'endpoint Detector accetta un solo campo obbligatorio, text, fino a 100.000 caratteri. Restituisce lo stato dell'analisi, il numero di caratteri, il tempo impiegato, una valutazione complessiva del documento, i risultati dei detector e creditUsed. Qui i campi di ricerca non vengono usati.

Uno schema tipico è chiamare prima Detector, mostrare all'utente quali passaggi presentano segnali e chiamare Humanize solo sulle sezioni che sceglie. In questo modo costi e modifiche restano al minimo.

Come vengono conteggiati i crediti dell'API

Entrambi gli endpoint spendono i crediti dell'account a cui appartiene la chiave. I due endpoint li conteggiano in modo diverso.

Humanize costa 1 credito ogni 500 caratteri, arrotondato per eccesso per ogni richiesta, e viene addebitato solo quando si salva un risultato completo. Detector costa 1 credito ogni 5.000 caratteri, arrotondato per eccesso. Se il saldo è insufficiente, la richiesta fallisce con un errore di crediti insufficienti invece di restituire un risultato parziale. Piani e pacchetti sono descritti in come funzionano crediti e prezzi, e i prezzi attuali sono su /pricing.

Errori da gestire

I corpi di errore includono un breve codice leggibile dalle macchine, quindi basa la logica sul codice e non sul testo del messaggio.

Domande frequenti

Come ottengo una chiave API?

Accedi e apri /api. Crea una chiave, copiala subito (viene mostrata una sola volta) e conservala sul tuo server.

Posso limitare i server che usano la mia chiave?

Sì. Passa l'accesso IP alla modalità limitata e indica gli IP o gli intervalli CIDR autorizzati a chiamare l'API. Le richieste da qualsiasi altra provenienza vengono rifiutate con HTTP 403.

Esiste un piano gratuito per l'API?

L'API usa gli stessi crediti dell'app web. I nuovi account ricevono una sola volta 10 crediti gratuiti, sufficienti per provare l'endpoint Humanize su alcuni passaggi brevi.

Con quali detector viene verificato l'output?

Academic Humanizer è validato con Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling e Originality.ai. Come per qualsiasi strumento, i risultati variano a seconda del detector e nessun esito è garantito.

Sviluppare con Academic Humanizer

Se il tuo prodotto gestisce già manoscritti, abstract o elaborati, l'API ti permette di aggiungere un passaggio di umanizzazione o un controllo di rilevamento senza mandare gli utenti altrove. Parti da una chiave di test, fai passare qualche paragrafo reale in entrambi gli endpoint e leggi la documentazione completa su /docs prima di andare in produzione.