O Que É o Parâmetro guidelines da API Grok? Moderação de Conteúdo Personalizada, Explicada

A xAI adicionou um parâmetro guidelines à API de texto do Grok, permitindo que você instrua o modelo a moderar categorias específicas de conteúdo enquanto escreve. Se você desenvolve com o Grok e precisa de maior controle sobre saídas sensíveis, este é o primeiro controle de conteúdo por requisição que a xAI disponibiliza para texto. Veja exatamente o que o parâmetro guidelines da API Grok faz, quais categorias ele cobre, como configurá-lo e os limites de requisição e erros a considerar.

O que o parâmetro guidelines faz

O parâmetro guidelines é um array que você adiciona a uma requisição da API de texto do Grok para alterar como o modelo lida com determinadas categorias de conteúdo. Para cada categoria listada, você escolhe um comportamento aprimorado; o Grok então segue as diretrizes ao escrever sua resposta, com suas próprias palavras. A resposta tem o mesmo formato de uma resposta normal — não há wrapper extra para processar.

Dois pontos importantes:

• É opt-in por categoria. Qualquer categoria que você omitir mantém o comportamento de moderação padrão do modelo, então você lista apenas as categorias que deseja alterar.
• É por requisição. As diretrizes se aplicam apenas à requisição que as contém. Para cobrir uma conversa inteira, você as envia em cada requisição dessa conversa.

O recurso foi documentado nas notas de versão da API Grok em outubro e, conforme o anúncio da xAI, está disponível para todos os clientes da API.

Quais categorias e comportamentos são suportados

Cada entrada em guidelines tem três campos: type (sempre "policy"), uma category e o behavior desejado. Atualmente, o único comportamento disponível é decline.

A documentação descreve esses comportamentos em alto nível e observa que a xAI pode refiná-los ao longo do tempo. A conclusão prática: decline é um direcionamento mais suave dentro da resposta, não um classificador rígido que retorna um erro — o Grok reformula sua própria resposta para se manter dentro da categoria especificada.

Como configurar guidelines em uma requisição

Você passa guidelines como um array de nível superior. Na Responses API, ele fica junto com os outros parâmetros; no Chat Completions, vai no mesmo nível que messages. Veja uma requisição que define violence e nsfw como decline:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Write a short story about a knight.",
    "guidelines": [
      { "type": "policy", "category": "violence", "behavior": "decline" },
      { "type": "policy", "category": "nsfw", "behavior": "decline" }
    ]
  }'

Observações sobre SDKs que costumam causar confusão:

• OpenAI Python SDK: o campo não está definido, então passe-o em extra_body.
• OpenAI JavaScript SDK: envie guidelines junto com os outros parâmetros da requisição.
• xAI Python SDK: chat.create armazena as diretrizes no chat, então cada chamada sample() as envia automaticamente — você não precisa repeti-las.

Quais APIs suportam — e quais não suportam

guidelines é aceito no Chat Completions, na Responses API e em chat.create no xAI Python SDK. Ele não funciona em alguns casos, e a API rejeita essas requisições com um 400 antes de o modelo ser executado:

• Modelos multi-agente, como grok-4.20-multi-agent.
• Completions diferidas (deferred completions).
• Uma requisição sem ferramentas server-side e sem anexos de arquivo que também define stop, ou define n maior que 1.

Como a verificação ocorre antecipadamente, uma requisição rejeitada não consome inferência do modelo — mas isso significa que você precisa tratar esses erros no código.

Erros a esperar

A API valida guidelines antes de executar o modelo e retorna um erro se não conseguir aplicá-las:

No xAI Python SDK, uma categoria ou comportamento desconhecido gera um ValueError antes mesmo de a requisição ser enviada; os outros erros retornam como status gRPC INVALID_ARGUMENT.

Por que isso importa para desenvolvedores

O Grok historicamente foi posicionado como um modelo mais permissivo, e as chamadas à API de texto anteriormente não tinham controles de moderação por requisição — você aceitava o comportamento padrão do modelo ou filtrava a saída por conta própria. O parâmetro guidelines é um caminho intermediário: direcionamento por categoria declarado inline, sem chamada de moderação separada e sem lógica de threshold no seu próprio código.

É deliberadamente limitado por enquanto — três categorias, um comportamento (decline), somente texto. Para um chatbot voltado ao cliente onde você não pode arriscar saídas sexualizadas ou com violência gráfica, declarar nsfw e violence como decline é uma proteção de uma linha. Para algo mais restrito ou auditável, você ainda vai querer suas próprias verificações de saída, já que decline reformula a resposta em vez de bloqueá-la completamente — e você ainda deve tratar as rejeições 400/422 mencionadas acima.

Construa fluxos de trabalho de IA moderados com seus próprios agentes

Controles de conteúdo como o parâmetro guidelines do Grok são uma peça para executar IA com segurança em produção — a parte mais difícil é conectar a saída de um modelo a tarefas reais, aprovações e ferramentas. O Eigent é um aplicativo "Cowork" multi-agente de código aberto que executa uma força de trabalho de IA localmente, para que você possa manter prompts e dados sensíveis na sua própria máquina enquanto os agentes gerenciam o fluxo de trabalho com checkpoints de supervisão humana. Veja como isso se encaixa em uma equipe enxuta em como gerenciar uma empresa solo com agentes de IA, ou baixe o Eigent para experimentar.