Custom Moderation Controls

Add a guidelines array to a request to set how Grok further handles specific content categories. For each category you include, you choose a further enhanced behavior. Today the only behavior is decline. Categories you leave out continue to keep the model's default moderation behavior.

Grok follows the guidelines as it writes its response, in its own words. The response has the same shape as a response without guidelines.

Each entry in guidelines has three fields: type, which is always "policy", a category, and the behavior you want for that category.

The table describes each behavior at a high level. SpaceXSI may refine the details over time.

A category you leave out keeps the model's default behavior, so list only the categories you want to change.

This example request sets violence and nsfw to decline.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.7",
    input="Write a short story about a knight.",
    extra_body={
        "guidelines": [
            {"type": "policy", "category": "violence", "behavior": "decline"},
            {"type": "policy", "category": "nsfw", "behavior": "decline"},
        ],
    },
)

print(response.output_text)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.responses.create({
  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" },
  ],
});

console.log(response.output_text);

import os

from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4.7",
    guidelines=[
        {"type": "policy", "category": "violence", "behavior": "decline"},
        {"type": "policy", "category": "nsfw", "behavior": "decline"},
    ],
)
chat.append(user("Write a short story about a knight."))

response = chat.sample()
print(response.content)

The OpenAI SDKs do not define guidelines. With the OpenAI Python SDK, pass it in extra_body. The OpenAI JavaScript SDK sends it with the other request parameters. On Chat Completions, add the same guidelines array as a top-level field of the request body, at the same level as messages.

Guidelines apply only to the request that carries them. To apply them to a whole conversation, send them on every request in it. In the xAI Python SDK, chat.create stores them on the chat, so every sample call sends them.

Guidelines currently do not work with multi-agent models, such as grok-4.20-multi-agent, or with deferred completions. A request with no server-side tools and no file attachments also cannot use guidelines if it sets stop or sets n greater than 1. The API rejects these requests with 400 before the model runs. The error message names the model or the option.

The API checks guidelines before it runs the model. If it cannot apply them, it returns an error and does not run the model.

In the xAI Python SDK, an unknown category or behavior raises ValueError before the SDK sends the request. The API returns the other errors as a gRPC INVALID_ARGUMENT status.

guidelines is accepted on Chat Completions and the Responses API, and on chat.create in the xAI Python SDK.