Moderação de Conteúdo com a API
Nesta página
Atualizado em 3 de novembro de 2026 com base no guia de Moderação da OpenAI: as categorias
illiciteillicit/violentpara o modeloomni-moderation-latestestavam em falta na lista e no código. Fonte: Moderation.
Moderação de Conteúdo com a API
A API de Moderação da OpenAI deteta automaticamente conteúdo inadequado. É uma ferramenta gratuita e essencial para qualquer aplicação que aceite conteúdo gerado por utilizadores. A lição anterior mostrou-lhe como escrever filtros personalizados; esta oferece-lhe um classificador treinado que deteta o que as expressões regulares nunca conseguirão apanhar — ameaças veladas, insultos indiretos e formulações implícitas.
A API de Moderação
A chamada é intencionalmente minimalista: um modelo, um texto e um resultado que se resume a um booleano. O campo flagged responde à questão binária: «Este conteúdo viola as políticas de utilização?», enquanto categories detalha quais foram violadas. Como este endpoint é gratuito, não existe qualquer razão económica para o ignorar, mesmo em grandes volumes.
from openai import OpenAI
client = OpenAI()
# A API de Moderação é GRATUITA
moderation = client.moderations.create(
model="omni-moderation-latest",
input="Hello, how are you?"
)
result = moderation.results[0]
print(f"Content flagged: {result.flagged}")
print(f"Categories: {result.categories}")
# Result:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)
Categorias de Moderação
Por detrás do booleano esconde-se uma grelha de granularidade fina. O modelo devolve uma decisão por categoria — assédio, assédio ameaçador, ódio, ódio ameaçador, instruções para atos ilícitos (com ou sem violência), automutilação com as suas variantes (instruções e intenção), conteúdo sexual, conteúdo sexual envolvendo menores, violência e violência gráfica — juntamente com uma pontuação de confiança entre 0,0 e 1,0 para cada uma.
Estas pontuações são mais importantes do que a decisão binária quando deseja calibrar a sua política. Uma plataforma de fóruns profissional poderá querer bloquear a partir de 0,3 para assédio, enquanto um serviço de ficção poderá aceitar 0,7 para violência. A função abaixo expõe ambos os níveis de insight: as categorias realmente acionadas e as pontuações brutas para os seus próprios limiares.
def analyze_moderation(text: str) -> dict:
"""Análise detalhada de moderação."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Categorias disponíveis
categories = {
"harassment": result.categories.harassment,
"harassment_threatening": result.categories.harassment_threatening,
"hate": result.categories.hate,
"hate_threatening": result.categories.hate_threatening,
"illicit": result.categories.illicit,
"illicit_violent": result.categories.illicit_violent,
"self_harm": result.categories.self_harm,
"self_harm_instructions": result.categories.self_harm_instructions,
"self_harm_intent": result.categories.self_harm_intent,
"sexual": result.categories.sexual,
"sexual_minors": result.categories.sexual_minors,
"violence": result.categories.violence,
"violence_graphic": result.categories.violence_graphic,
}
# Pontuações de confiança (0.0 a 1.0)
scores = {
"harassment": result.category_scores.harassment,
"hate": result.category_scores.hate,
"self_harm": result.category_scores.self_harm,
"sexual": result.category_scores.sexual,
"violence": result.category_scores.violence,
}
return {
"flagged": result.flagged,
"detected_categories": [k for k, v in categories.items() if v],
"main_scores": {k: round(v, 4) for k, v in scores.items()},
}
# Teste
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")
Pipeline de Moderação Completo
Moderação de Inputs do Utilizador
Vamos envolver esta chamada num componente reutilizável. O ContentModerator devolve um par explícito — aceitável ou não, com o motivo — em vez de um objeto bruto que cada chamador teria de reinterpretar. Traduzir as categorias numa linguagem clara é fundamental: este é o vocabulário que aparecerá na sua interface e nos registos, e deve ser compreensível pela equipa de moderação humana que assumirá o controlo.
class ContentModerator:
"""Moderador de conteúdo para aplicações."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Modera texto. Devolve (é_aceitável, detalhes)."""
moderation = self.client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
if result.flagged:
categories = []
if result.categories.harassment:
categories.append("harassment")
if result.categories.hate:
categories.append("hate speech")
if result.categories.sexual:
categories.append("sexual content")
if result.categories.violence:
categories.append("violence")
if result.categories.self_harm:
categories.append("self-harm")
return False, {
"reason": "Inappropriate content detected",
"categories": categories
}
return True, {"reason": "Content acceptable"}
def moderate_conversation(self, messages: list[str]) -> list[dict]:
"""Modera uma lista de mensagens."""
results = []
for msg in messages:
acceptable, details = self.moderate(msg)
results.append({
"message": msg[:50] + "..." if len(msg) > 50 else msg,
"acceptable": acceptable,
**details
})
return results
# Utilização
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")
Integração no Pipeline da API
A moderação enquadra a chamada em ambos os lados. Filtrar o input evita pagar pela geração de conteúdo que iria rejeitar de qualquer forma; filtrar o output protege contra casos em que o modelo, habilmente provocado, produz algo inaceitável por si só. Note a diferença no tratamento: para o input, pode dizer ao utilizador o que foi detetado, uma vez que foi ele o autor; para o output, a mensagem mantém-se vaga, porque detalhá-la significaria descrever aquilo que o modelo acabou de produzir.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot com moderação de inputs E outputs."""
moderator = ContentModerator()
# 1. Moderar input
input_ok, input_details = moderator.moderate(user_input)
if not input_ok:
return (f"Your message was blocked: "
f"{', '.join(input_details['categories'])}")
# 2. Gerar resposta
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Respond in a professional and safe manner.",
input=user_input
)
# 3. Moderar output
output_ok, output_details = moderator.moderate(response.output_text)
if not output_ok:
return "I am unable to provide that response."
return response.output_text
# Teste
print(moderated_chatbot("What is the capital of France?"))
Moderação em Lote
Esta chamada dupla adiciona latência, o que é aceitável numa conversa, mas torna-se proibitivo quando precisa de processar dez mil avaliações de clientes importadas de um ficheiro. Para moderar grandes volumes com eficiência, passe um array diretamente: a API processa todos os textos num único pedido e devolve os resultados pela mesma ordem, permitindo-lhe reassociá-los por índice.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Modera múltiplos textos num único pedido."""
results = []
# A API aceita um array de inputs
moderation = client.moderations.create(
model="omni-moderation-latest",
input=texts
)
for i, result in enumerate(moderation.results):
results.append({
"index": i,
"text_preview": texts[i][:50],
"flagged": result.flagged,
})
flagged_count = sum(1 for r in results if r["flagged"])
print(f"Moderated {len(texts)} texts: {flagged_count} flagged")
return results
# Utilização
texts = [
"Hello, how are you?",
"Great product, I recommend it!",
"Customer service is excellent.",
]
results = moderate_batch(texts)
Registo de Moderação
Uma decisão de moderação afeta um utilizador e, mais cedo ou mais tarde, terá de a justificar — seja a um cliente que conteste um bloqueio, seja a um regulador. Portanto, registe sistematicamente o veredicto, o ID do utilizador, as pontuações e um excerto do texto. O nível de registo distingue os dois casos: warning para conteúdo assinalado, que merece revisão humana, e info para o restante, que alimenta as suas estatísticas.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Modera e regista o resultado para auditoria."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
log_entry = {
"timestamp": datetime.now().isoformat(),
"user_id": user_id,
"flagged": result.flagged,
"text_preview": text[:100],
"scores": {
"harassment": round(result.category_scores.harassment, 4),
"hate": round(result.category_scores.hate, 4),
"violence": round(result.category_scores.violence, 4),
}
}
if result.flagged:
logger.warning(json.dumps(log_entry))
else:
logger.info(json.dumps(log_entry))
return not result.flagged
# Utilização
is_ok = moderate_with_log("Test message", user_id="user-123")
Um último aviso antes de avançar: a moderação classifica o conteúdo; não compreende a intenção. Uma mensagem perfeitamente educada que tente contornar as proteções do seu assistente passará por todos estes filtros sem ser assinalada uma única vez. Esse é o tema da próxima lição.
Pontos-chave
- A API de Moderação é gratuita — utilize-a sistematicamente
- Modere tanto os inputs (conteúdo do utilizador) COMO os outputs (respostas do modelo)
- O modelo
omni-moderation-latestcobre todas as categorias de conteúdo - Registe todas as decisões de moderação para auditoria
- Utilize o processamento em lote para moderar grandes volumes com eficiência
- A moderação complementa as instruções do sistema; não as substitui