advanced-api-usage/custom-moderation-controls.md +128 −0 created
1#### Advanced API Usage
2
3# Custom Moderation Controls
4
5Add 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.
6
7Grok follows the guidelines as it writes its response, in its own words. The response has the same shape as a response without guidelines.
8
9## Categories and behaviors
10
11Each entry in `guidelines` has three fields: `type`, which is always `"policy"`, a `category`, and the `behavior` you want for that category.
12
13| Category | Behavior | What Grok does |
14|----------|----------|----------------|
15| `nsfw` | `decline` | Avoids sexual innuendo or sexualized conversations. Still answers educational and clinical questions about sexual topics. |
16| `violence` | `decline` | Avoids depictions of graphic violence. Engages with history and news without graphic detail. |
17| `profanity` | `decline` | Writes without using profanity. Declines when the request is for profanity alone, or when the request is highly offensive. |
18
19The table describes each behavior at a high level. SpaceXSI may refine the details over time.
20
21A category you leave out keeps the model's default behavior, so list only the categories you want to change.
22
23## Set guidelines on a request
24
25This example request sets `violence` and `nsfw` to `decline`.
26
27```python customLanguage="pythonOpenAISDK"
28import os
29from openai import OpenAI
30
31client = OpenAI(
32 api_key=os.getenv("XAI_API_KEY"),
33 base_url="https://api.x.ai/v1",
34)
35
36response = client.responses.create(
37 model="grok-4.7",
38 input="Write a short story about a knight.",
39 extra_body={
40 "guidelines": [
41 {"type": "policy", "category": "violence", "behavior": "decline"},
42 {"type": "policy", "category": "nsfw", "behavior": "decline"},
43 ],
44 },
45)
46
47print(response.output_text)
48```
49
50```bash customLanguage="bash"
51curl https://api.x.ai/v1/responses \
52 -H "Authorization: Bearer $XAI_API_KEY" \
53 -H "Content-Type: application/json" \
54 -d '{
55 "model": "grok-4.7",
56 "input": "Write a short story about a knight.",
57 "guidelines": [
58 { "type": "policy", "category": "violence", "behavior": "decline" },
59 { "type": "policy", "category": "nsfw", "behavior": "decline" }
60 ]
61 }'
62```
63
64```javascript customLanguage="javascriptOpenAISDK"
65import OpenAI from "openai";
66
67const client = new OpenAI({
68 apiKey: process.env.XAI_API_KEY,
69 baseURL: "https://api.x.ai/v1",
70});
71
72const response = await client.responses.create({
73 model: "grok-4.7",
74 input: "Write a short story about a knight.",
75 guidelines: [
76 { type: "policy", category: "violence", behavior: "decline" },
77 { type: "policy", category: "nsfw", behavior: "decline" },
78 ],
79});
80
81console.log(response.output_text);
82```
83
84```python customLanguage="pythonXAI"
85import os
86
87from xai_sdk import Client
88from xai_sdk.chat import user
89
90client = Client(api_key=os.getenv("XAI_API_KEY"))
91
92chat = client.chat.create(
93 model="grok-4.7",
94 guidelines=[
95 {"type": "policy", "category": "violence", "behavior": "decline"},
96 {"type": "policy", "category": "nsfw", "behavior": "decline"},
97 ],
98)
99chat.append(user("Write a short story about a knight."))
100
101response = chat.sample()
102print(response.content)
103```
104
105The 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`.
106
107Guidelines 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.
108
109## Requests that cannot use guidelines
110
111Guidelines 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.
112
113## Errors
114
115The API checks `guidelines` before it runs the model. If it cannot apply them, it returns an error and does not run the model.
116
117| Status | Cause |
118|--------|-------|
119| `422` | The `category` or `behavior` is not a known value. The error lists the valid values. |
120| `400` | The same category appears more than once. |
121| `400` | The `type` is not `"policy"`. |
122| `400` | The request cannot use guidelines, as described in [Requests that cannot use guidelines](#requests-that-cannot-use-guidelines). The message names the model or the option. |
123
124In 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.
125
126## Supported APIs
127
128`guidelines` is accepted on [Chat Completions](/developers/rest-api-reference/inference/chat-completions) and the [Responses API](/developers/rest-api-reference/inference/responses), and on `chat.create` in the xAI Python SDK.