---
title: "xAI API 新增 safety_identifier：多用户应用怎么避免一个用户连累整个 API Key"
description: "xAI 在 2026 年 9 月的 release notes 加入可选字段 safety_identifier，让违规请求归到具体终端用户而非整个 API Key。本文讲清它是什么、怎么生成、怎么传，附上线检查表。"
url: https://cdnping.org/blog/xai-api-safety-identifier
language: zh-CN
published: 2026-10-18
category: "开发工具"
tags: ["xAI","Grok API","safety_identifier","合规","多用户应用"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# xAI API 新增 safety_identifier：多用户应用怎么避免一个用户连累整个 API Key

xAI 开发者 release notes 在 2026 年 9 月新增了一个可选请求字段 `safety_identifier`。你的应用把每个终端用户的不透明标识放进请求，xAI 在处理违反使用政策的请求时，就能把它归到具体的终端用户，而不是整个 API Key。如果你做的是 SaaS、机器人或团队内部工具，多个用户共用一个 Key，官方文档建议为每个用户单独设置这个字段。

> 时间口径：以下内容基于 xAI 官方文档截至 2026 年 10 月 17 日的页面。release notes 的条目列在 9 月标题下，页面未给出具体日期，请以官方页面为准。

## safety_identifier 到底是什么？

按 [xAI release notes](https://docs.x.ai/developers/release-notes) 的说法，它是“由你的应用分配的、代表终端用户的不透明标识”，请求字段可选。目的是让违规归因落到具体用户，一个用户的滥用不再牵连整个账号。

[官方 Security FAQ](https://docs.x.ai/developers/faq/security) 补充了几点：

- 标识应当稳定，同一个用户每次请求都用同一个值，并且由你的应用分配，终端用户不能自己指定。
- 如果请求违反使用政策，xAI 可以把它归到这个标识，并在联系你时引用它。
- 建议发送内部用户 ID 或其他不透明值的哈希。不要发送邮箱、手机号、昵称。页面说明该字段的格式不做校验，并提到长度上限为 96 个字符。
- 如果你让很多终端用户共用一个 API Key，应为每个用户设置它，让滥用报告落到用户而不是 Key 上。

## 哪些接口支持？旧的 user 字段还能用吗？

两篇官方文档列出的支持范围：Chat Completions、Responses API（FAQ 提到包含流式和 WebSocket 模式）、延迟补全（deferred chat completions）、Batch API，以及 gRPC 的 `GetCompletionsRequest`。

原有的 `user` 字段仍然被接受，但 FAQ 写明 `safety_identifier` 是今后文档推荐的字段。如果两个字段同时传会怎样，文档没有说明，所以别依赖这种行为：新代码只传 `safety_identifier`，旧代码迁移时替换掉 `user`。

## 不传会怎样？

文档没有写不传的后果，也没有说 xAI 会因为没传而拒绝请求。能确定的只是它的设计意图：没有标识时，违规请求只能归到 Key 这一层。所以对多用户应用，补上它的成本很低，收益是出问题时影响范围可以收窄。是否真的能避免 Key 被限制，取决于 xAI 的处理，官方没有做这个承诺。

## 标识该怎么生成？

原则是稳定、不可逆、不含个人信息。一个常见做法是对内部用户 ID 做带密钥的哈希（HMAC），这样别人无法从标识反推出你的用户 ID。下面是示例，不是官方代码：

```python
import hmac, hashlib, os

SECRET = os.environ["SAFETY_ID_SECRET"].encode()

def safety_id(internal_user_id: str) -> str:
    return hmac.new(SECRET, internal_user_id.encode(), hashlib.sha256).hexdigest()
```

注意：

- 密钥不要随意轮换，换了以后同一用户的标识会变，归因就断了。
- 用内部 ID，不要用邮箱。用户改邮箱不应该改变标识。
- 机器人场景里，一个群或一个频道不等于一个用户，尽量落到真实的终端用户。

## 请求里怎么写？

字段放在请求体里。下面以 Responses 接口为例，模型名用占位符，按你在官方模型页看到的名称填写：

```bash
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "input": "你好",
    "safety_identifier": "a1b2c3d4e5f6..."
  }'
```

如果你用 OpenAI 兼容的 SDK，SDK 的类型定义里可能还没有这个字段，可以通过它的“额外请求体参数”传入（OpenAI Python SDK 里是 `extra_body`），具体以所用 SDK 版本为准：

```python
client.chat.completions.create(
    model="<model>",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={"safety_identifier": safety_id(user.id)},
)
```

Batch 和 gRPC 的字段位置请以官方 API 文档为准，这里不展开。

## 上线前的检查表

1. 所有调用 xAI 的代码路径都传了字段：聊天、批处理、后台任务、定时任务都算。
2. 值是哈希或随机 ID，没有邮箱、手机号、昵称。
3. 同一用户每次请求值一致，不同用户值不同。
4. 日志里记录“请求 ID、标识、时间”，但不要把用户的原始内容长期明文存放。出了问题时，你能用标识定位到是哪个用户。
5. 前置内容审核：标识只负责归因，不会替你拦截违规内容。入口处的审核、频率限制和异常用户封禁，仍然是你自己的责任。
6. 在服务条款里写明：违规使用可能导致你限制该用户的访问。

## 怎么跟踪 xAI 文档后续的改动？

这类字段的语义以后可能补充细节。可以看 cdnping 的 [官网动态](/changes)，它监控各家官方更新日志与价格页的增删；调用本身的健康状况看 [xAI API 状态](/status/xai)。更多思路见 [大模型 API 价格变了怎么第一时间知道](/blog/track-llm-price-and-model-changes)。

如果你正在比较直连官方、云厂商托管或经由网关接入，可以读 [AI API 接入方式怎么选](/blog/official-api-vs-cloud-vs-gateway)。通过中间层转发请求时，上游看到的是中间层的 Key，终端用户归因更要自己做好，评估方法见 [api中转站怎么选](/blog/api-relay-how-to-evaluate)。出现报错时，[怎么看 OpenAI 状态页和 Claude 状态页](/blog/how-to-read-ai-status-pages) 里的方法同样适用于判断是不是上游事件。

## 参考来源

- [xAI Developer Release Notes](https://docs.x.ai/developers/release-notes)
- [xAI Security FAQ：如何识别是哪个终端用户造成了违规](https://docs.x.ai/developers/faq/security)