Guia de migração da API Pangram 3.0

A API 3.0 da Pangram já está disponível! Este guia abrange tudo o que precisa de saber sobre a migração dos nossos pontos finais v2 para a nova API v3.

O que há de novo na versão 3?

Introduzimos uma terceira categoria de classificação para textos assistidos por IA. Os textos que se enquadram nesta categoria são normalmente escritos com uma contribuição significativa da IA e do ser humano, refletindo a forma como as pessoas realmente utilizam as ferramentas de IA atualmente.

Principais alterações no esquema

A API v3 classifica todos os documentos com três campos fracionários que indicam a quantidade do documento que se enquadra em cada categoria:

• fração_humana — parte classificada como escrita por humanos
• fração_ai_assistida — parte classificada como assistida por IA
• fração_ai — parte classificada como gerada por IA

Esses três campos são mutuamente exclusivos e coletivamente exaustivos; a sua soma será sempre igual a 1.

Além disso, cada documento inclui três sequências de previsão em diferentes níveis de detalhe:

• manchete — por exemplo, «Totalmente escrito por humanos», «Assistido por IA», «Detetado por IA»
• previsão — explicação detalhada da classificação. Por exemplo, «Estamos confiantes de que este documento foi totalmente gerado por IA» ou «Acreditamos que este documento foi assistido por IA, mas não totalmente gerado por IA».
• previsão_curta — por exemplo, «Humano», «Misto», «IA»

Análise ao nível da janela

Cada documento de entrada é dividido em janelas. Cada janela é identificada com:

• rótulo — sequência de classificação («Humano», «Moderadamente assistido por IA», «Gerado por IA», etc.)
• confiança — resultado de confiança do modelo de deteção do Pangram («Alta», «Média», «Baixa»)
• pontuação_assistência_IA — escalar de 0 a 1 indicando a magnitude da assistência da IA

Nota: Espera-se que rótulos adicionais («Ligeiramente assistido por IA», «Fortemente assistido por IA») sejam introduzidos num futuro próximo.

---

Devo migrar?

SIM, se:

• Utilizar os resultados do Pangram num ambiente de produção
• Quer melhorar a precisão dos resultados dos modelos de IA mais recentes?
• Planeie utilizar a API Pangram após 1 de abril de 2026

NÃO, se:

• É um investigador que precisa de uma API estática para reprodutibilidade

---

Cronograma

Data	Evento
11 de dezembro de 2025	Pangram 3.0 lançado através do painel de controlo
23 de dezembro de 2025	Pangram 3.0 disponível através da API
Final de janeiro de 2026	Pangram 3.1 lançado (painel + API). Todos os utilizadores da API 3.0 foram atualizados automaticamente.
1 de abril de 2026	API Pangram 2.0 em fim de vida útil

---

Terminais V2 (disponíveis até 1 de abril de 2026)

Os seguintes pontos finais v2 permanecem disponíveis durante o período de transição:

• text.api.pangram.com
• text-batch.api.pangram.com
• text-sliding.api.pangram.com
• text-extended.api.pangram.com
• painel-texto.api.pangram.com

---

Guia de Migração de Campo

De text.api.pangram.com

Ponto final: https://text.api.pangram.com → https://text.api.pangram.com/v3

Para uma compreensão mais abrangente das previsões do Pangram, utilize os campos de nível superior:

v2 Campo	v3 Campo	Notas
previsão	manchete	Valores como «Totalmente escrito por humanos», «Assistido por IA», «Detetado por IA»
ai_probabilidade	fração_ai	Quantidade de texto que se acredita ter sido gerado por IA
—	fração_ai_assistida	Novo: Quantidade que se acredita ser assistida por IA
—	fração_humana	Quantidade que se acredita ter sido escrita por humanos

Correspondência com o comportamento original do ponto final: O ponto final original utilizava apenas a primeira janela do texto para fazer a sua previsão. Para corresponder a este comportamento:

v2 Campo	v3 Campo
previsão	janelas[0].rótulo e janelas[0].confiança
ai_probabilidade	windows[0].ai_assistance_score

Importante: A interpretação de pontuação_assistência_IA difere de ai_probabilidade. Estes campos não são um-para-um. Espere mais previsões na faixa intermediária (0–1). Use rótulo para compreender a nossa interpretação recomendada.

---

De text-batch.api.pangram.com

Atualmente, não há um ponto final em lote para a API v3. Use um loop para processar cada item individualmente, seguindo o text.api.pangram.com guia de migração acima.

---

De text-sliding.api.pangram.com

Ponto final: https://text-sliding.api.pangram.com → https://text.api.pangram.com/v3

v2 Campo	v3 Campo	Notas
previsão	manchete ou previsão	Diferentes níveis de detalhe disponíveis
previsão_curta	previsão_curta	Inalterado
ai_probabilidade, probabilidade_média_de_IA	fração_ai, fração_ai_assistida, fração_humana	Use campos de quantidade em vez de pontuações de confiança agregadas
max_ai_probabilidade	fração_ai (recomendado)	Campos de quantidade preferidos

Alterações na janela:

• Em deslizamento de texto, as janelas são sobreposição
• Na versão 3, as janelas não se sobrepõem.

Campo da janela v2	Campo da janela v3
windows[].prediction	windows[].label + windows[].confiança
windows[].ai_probabilidade	windows[].ai_assistance_score

---

De text-extended.api.pangram.com

Ponto final: https://text-extended.api.pangram.com → https://text.api.pangram.com/v3

A maioria dos campos permanece inalterada:

Campo	Status
manchete	Inalterado
previsão	Inalterado
previsão_curta	Inalterado
fração_humana	Inalterado
fração_ai	Inalterado
windows[].label	Inalterado
windows[].confiança	Inalterado
windows[].start_index	Inalterado
windows[].end_index	Inalterado

Campos que foram alterados:

v2 Campo	v3 Campo	Notas
fração_mista	fração_ai_assistida	Campo renomeado para maior clareza
painel de controlo	link_do_painel_público	Campo renomeado para maior clareza
probabilidade_média_de_IA	fração_ai, fração_ai_assistida, fração_humana	Use campos de quantidade em vez de pontuações de confiança agregadas
max_ai_probabilidade	fração_ai, fração_ai_assistida, fração_humana	Use campos de quantidade em vez de pontuações de confiança agregadas
windows[].ai_probabilidade	windows[].ai_assistance_score	As pontuações de probabilidade e assistência da IA não são equivalentes. Utilização rótulo para orientação.

---

Documentação

A documentação completa da API está disponível aqui.

---

Dúvidas?

Se tiver dúvidas sobre a migração para a versão 3, entre em contacto através do e-mail support@pangram.com.