Guida alla migrazione dell'API Pangram 3.0

L'API 3.0 di Pangram è attiva! Questa guida illustra tutto ciò che occorre sapere sulla migrazione dai nostri endpoint v2 alla nuova API v3.

Cosa c'è di nuovo nella versione 3?

Abbiamo introdotto una terza categoria di classificazione per i testi assistiti dall'intelligenza artificiale. I testi che rientrano in questa categoria sono in genere scritti con un contributo significativo dell'intelligenza artificiale e dell'uomo, riflettendo il modo in cui le persone utilizzano effettivamente gli strumenti di intelligenza artificiale oggi.

Modifiche chiave allo schema

L'API v3 classifica ogni documento con tre campi frazionari che indicano la percentuale del documento che rientra in ciascuna categoria:

• frazione_umana — porzione classificata come scritta da esseri umani
• frazione_ai_assistita — porzione classificata come assistita dall'intelligenza artificiale
• frazione_ai — porzione classificata come generata dall'intelligenza artificiale

Questi tre campi sono mutuamente esclusivi ed esaustivi nel loro insieme; la loro somma sarà sempre pari a 1.

Inoltre, ogni documento include tre stringhe di previsione con diversi livelli di verbosità:

• titolo — ad esempio, "Scritto interamente da esseri umani", "Assistito dall'IA", "Rilevato dall'IA"
• previsione — spiegazione dettagliata della classificazione. Ad esempio, "Siamo certi che questo documento sia stato interamente generato dall'intelligenza artificiale" oppure "Riteniamo che questo documento sia stato redatto con l'ausilio dell'intelligenza artificiale, ma non interamente generato dall'intelligenza artificiale".
• prediction_short — ad esempio, "Umano", "Misto", "AI"

Analisi a livello di finestra

Ogni documento in ingresso viene suddiviso in finestre. Ogni finestra è contrassegnata con:

• etichetta — stringa di classificazione ("Umano", "Moderatamente assistito dall'IA", "Generato dall'IA", ecc.)
• fiducia — livello di affidabilità del modello di rilevamento di Pangram ("Alto", "Medio", "Basso")
• punteggio_assistenza_ai — scalare da 0 a 1 che indica l'entità dell'assistenza fornita dall'intelligenza artificiale

Nota: nel prossimo futuro saranno introdotte ulteriori etichette ("Leggermente assistito dall'IA", "Fortemente assistito dall'IA").

---

Devo migrare?

SÌ se:

• Utilizzo dei risultati Pangram in un ambiente di produzione
• Desideri una maggiore precisione nei risultati dei modelli di IA più recenti?
• Prevedi di utilizzare l'API Pangram oltre il 1° aprile 2026

NO se:

• Sei un ricercatore che necessita di un'API statica per garantire la riproducibilità?

---

Cronologia

Data	Evento
11 dicembre 2025	Pangram 3.0 rilasciato tramite la dashboard
23 dicembre 2025	Pangram 3.0 disponibile tramite API
Fine gennaio 2026	Rilascio di Pangram 3.1 (dashboard + API). Tutti gli utenti dell'API 3.0 sono stati aggiornati automaticamente.
1 aprile 2026	API Pangram 2.0 in fase di dismissione

---

Endpoint V2 (disponibili fino al 1° aprile 2026)

I seguenti endpoint v2 rimangono disponibili durante il periodo di transizione:

• text.api.pangram.com
• text-batch.api.pangram.com
• text-sliding.api.pangram.com
• text-extended.api.pangram.com
• dashboard-text.api.pangram.com

---

Guida alla migrazione sul campo

Da text.api.pangram.com

Punto finale: https://text.api.pangram.com → https://text.api.pangram.com/v3

Per comprendere appieno le previsioni di Pangram, utilizza i campi di primo livello:

v2 Campo	v3 Campo	Note
previsione	titolo	Valori come "Scritto interamente da esseri umani", "Assistito dall'IA", "Rilevato dall'IA"
ai_probabilità	frazione_ai	Quantità di testo che si ritiene sia stato generato dall'intelligenza artificiale
—	frazione_ai_assistita	Novità: quantità ritenuta assistita dall'intelligenza artificiale
—	frazione_umana	Quantità ritenuta scritta da esseri umani

Corrispondenza con il comportamento dell'endpoint originale: l'endpoint originale utilizzava solo la prima finestra del testo per effettuare la previsione. Per corrispondere a questo comportamento:

v2 Campo	v3 Campo
previsione	finestre[0].etichetta e finestre[0].fiducia
ai_probabilità	windows[0].punteggio_assistenza_ai

Importante: L'interpretazione di punteggio_assistenza_ai differisce da ai_probabilità. Questi campi non sono uno a uno. Aspettati più previsioni nella fascia media (0–1). Usa etichetta per comprendere la nostra interpretazione raccomandata.

---

Da text-batch.api.pangram.com

Al momento non c'è un endpoint batch per l'API v3. Usa un ciclo per elaborare ogni elemento singolarmente, seguendo il text.api.pangram.com guida alla migrazione sopra.

---

Da text-sliding.api.pangram.com

Punto finale: https://text-sliding.api.pangram.com → https://text.api.pangram.com/v3

v2 Campo	v3 Campo	Note
previsione	titolo o previsione	Sono disponibili diversi livelli di verbosità
prediction_short	prediction_short	Invariato
ai_probabilità, probabilità_media_ai	frazione_ai, frazione_ai_assistita, frazione_umana	Utilizza i campi quantità invece dei punteggi di affidabilità aggregati
massima probabilità AI	frazione_ai (consigliato)	Campi quantità preferiti

Modifiche alle finestre:

• In scorrimento del testo, le finestre sono sovrapposizione
• Nella versione 3, le finestre non si sovrappongono.

v2 Campo finestra	v3 Campo finestra
windows[].prediction	windows[].label + windows[].confidence
windows[].ai_probabilità	windows[].ai_assistance_score

---

Da text-extended.api.pangram.com

Punto finale: https://text-extended.api.pangram.com → https://text.api.pangram.com/v3

La maggior parte dei campi rimane invariata:

Campo	Stato
titolo	Invariato
previsione	Invariato
prediction_short	Invariato
frazione_umana	Invariato
frazione_ai	Invariato
windows[].label	Invariato
windows[].confidence	Invariato
windows[].start_index	Invariato
windows[].end_index	Invariato

Campi modificati:

v2 Campo	v3 Campo	Note
frazione_mista	frazione_ai_assistita	Campo rinominato per maggiore chiarezza
cruscotto	link_pannello_di_controllo_pubblico	Campo rinominato per maggiore chiarezza
probabilità_media_ai	frazione_ai, frazione_ai_assistita, frazione_umana	Utilizza i campi quantità invece dei punteggi di affidabilità aggregati
massima probabilità AI	frazione_ai, frazione_ai_assistita, frazione_umana	Utilizza i campi quantità invece dei punteggi di affidabilità aggregati
windows[].ai_probabilità	windows[].ai_assistance_score	I punteggi di probabilità e assistenza dell'IA non sono uno a uno. Utilizzo etichetta per assistenza.

---

Documentazione

La documentazione completa dell'API è disponibile qui.

---

Domande?

Per qualsiasi domanda relativa alla migrazione alla versione 3, contattaci all'indirizzo support@pangram.com.