白泽 白泽AI威胁情报中心

白泽威胁情报 API 用户指南

版本：v1 · 更新日期：2026-10-08

白泽 API 提供 AI 安全情报文章和政策法规数据。你可以按条件查询，也可以将数据持续同步到自己的系统。

接入前，请向平台对接人员申请 API Key。拿到密钥后，从下面的快速开始操作即可。

1. 可以获取哪些数据

内容 用途 接口
订阅目录 查看可用数据、最近发布日期和调用额度 GET /api/v1/catalog
情报文章 查询安全事件、漏洞、攻防研究、监管及行业动态 GET /api/v1/articles
政策法规 按地区、来源和发布日期查询政策 GET /api/v1/policies
增量同步 获取文章和政策的新增、更新及删除信息 GET /api/v1/changes

默认只能访问申请日期往前一个自然月（含当日）起发布的文章和政策，以及之后的数据。申请日期由平台登记，未单独登记时以密钥开通日期为准。例如 2026-10-08 申请，最早发布日期为 2026-09-08；3 月 31 日申请则回溯到 2 月最后一天。这是固定起点，不是每天滚动的最近 30 天。缺失或无效发布日期的记录不向默认权限开放。

需要全部历史数据时，请详细说明研究或业务用途、所需时间范围、默认范围不足的原因、数据存储与共享安排，由平台审批后单独开通。提交理由不等于已获授权。

通过 API 获取的原始数据及批量数据集，未经平台书面授权不得公开发布（包括上传 GitHub）或转售。

报告订阅暂不开放，日报、周报、月报和行业报告不在本指南的接口范围内。

这里的“订阅”是由你的程序主动拉取数据，不是邮件通知或 Webhook 推送。数据随平台采集和处理结果更新；文章的发布日期不一定是平台收录日期。

2. 快速开始

接口地址：

https://whitzard-intelligence.tech/api/v1

以下命令适用于 macOS/Linux 的 Bash 或 zsh。先把占位文字替换成单独收到的 API Key，在当前终端执行一次：

export WHITZARD_URL='https://whitzard-intelligence.tech'
export WHITZARD_API_KEY='YOUR_API_KEY'

先确认接入成功：

curl -sS --fail-with-body \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/catalog"

成功时返回 JSON。history 为 limited 或 all；applied_on 是登记申请日期；earliest_publish_date 是当前允许的最早发布日期（含当日），全历史授权时为 null。这些范围由服务器决定，不能通过查询参数扩大。

返回的 resources 中包含 articles 和 policies。其中 latest 是各类数据目前最大的发布日期，可用于判断数据覆盖情况；它不是服务健康检查时间。

再获取两条情报：

curl -sS --fail-with-body \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/articles?limit=2"

需要格式化输出时，在命令末尾加 | python3 -m json.tool。如果旧版 curl 不支持 --fail-with-body，可改为 --fail。

每次请求只发送一个 X-API-Key 请求头。API Key 不要放在 URL、公开仓库或浏览器前端代码中；由你自己的后端程序或脚本调用。不同客户应使用各自的密钥，正式接入请勿共用他人的测试密钥。

3. 查询情报文章

GET /api/v1/articles

所有参数均为可选，可组合使用，组合条件同时满足才返回结果。默认按发布日期从新到旧排序；发布日期相同时按 ID 排序。

参数 说明 默认值或限制
limit 每页条数 默认 50，范围 1–200
offset 跳过的记录条数 默认 0，范围 0–1000000
id 精确查询文章 ID 最长 2048 字符
risk_level 风险等级 单个值：critical、high、medium、low、info
content_type 精确匹配内容类型 最长 80 字符，常见类型见下表
is_track_f 是否为 F 类行业参考 true / false；不传则包含两类
category 精确匹配一个威胁标签 如 提示注入，最长 100 字符
search 在标题和摘要中搜索子串 最长 200 字符
start_date 起始发布日期，包含当天 严格使用有效日期 YYYY-MM-DD
end_date 结束发布日期，包含当天 严格使用有效日期 YYYY-MM-DD

风险等级大致对应严重、高、中、低、信息。info 是接口接受的值，不代表当前一定有该等级的数据。

start_date 不能晚于 end_date。日期参数不接受 Unix 时间戳或带时分秒的字符串。risk_level 和 category 当前均为单选，不能用逗号传多个值。接口目前不提供自定义排序参数。

常见 content_type：

类型 含义 类型 含义
incident_report 安全事件 vulnerability 漏洞
research_paper 研究论文 jailbreak_technique 越狱技术
alignment_safety 对齐与安全 vendor_advisory 厂商公告
policy_regulation 政策法规 regulatory_action 监管行动
legal_action 法律行动 security_ai_tool AI 安全工具
industry_analysis 行业分析 industry_observation 行业观察
ai_society_risk AI 社会风险 ecosystem_news 生态动态
positive_development 正向进展 product_with_security 产品安全相关

内容类型和标签可能随数据扩展，以实际记录为准。客户端收到未见过的类型时，建议保留原值，不要直接丢弃记录。

示例：查询高危漏洞。

curl -sS --fail-with-body -G \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/articles" \
  --data-urlencode 'risk_level=high' \
  --data-urlencode 'content_type=vulnerability' \
  --data-urlencode 'limit=10'

示例：查询指定日期范围内与 OpenAI 有关的文章。

curl -sS --fail-with-body -G \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/articles" \
  --data-urlencode 'search=OpenAI' \
  --data-urlencode 'start_date=2026-10-01' \
  --data-urlencode 'end_date=2026-10-08'

示例：查询“提示注入”标签，排除 F 类行业参考。

curl -sS --fail-with-body -G \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/articles" \
  --data-urlencode 'category=提示注入' \
  --data-urlencode 'is_track_f=false'

中文、空格或 URL 类型的 ID 请用 --data-urlencode 传递。

4. 查询政策法规

GET /api/v1/policies

参数 说明 默认值或限制
limit 每页条数 默认 50，范围 1–200
offset 跳过的记录条数 默认 0，范围 0–1000000
id 精确匹配政策 ID 最长 2048 字符
area 精确匹配国家或地区 如 China，最长 100 字符
source 精确匹配来源标识 使用记录中的 source 原值，最长 100 字符
start_date 起始发布日期，包含当天 YYYY-MM-DD
end_date 结束发布日期，包含当天 YYYY-MM-DD 
curl -sS --fail-with-body -G \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/policies" \
  --data-urlencode 'area=China' \
  --data-urlencode 'limit=10'

policies 面向政策条目；监管新闻、法律事件等也可能作为情报文章收录在 articles。如果你关注完整的监管动态，建议同时使用两类数据。

5. 理解返回结果与分页

文章和政策列表使用相同的分页结构。下例仅演示结构，文章字段已省略部分：

{
  "data": [
    {
      "id": "example-001",
      "title": "示例情报标题",
      "publish_date": "2026-10-08 09:00:00",
      "risk_level": "high",
      "content_type": "vulnerability",
      "threat_categories": ["提示注入"]
    }
  ],
  "total": 21,
  "limit": 1,
  "offset": 0,
  "next_offset": 1
}

下一页保持筛选条件不变，将 offset 换成返回的 next_offset。例如每页 20 条，第二页为：

curl -sS --fail-with-body \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/articles?limit=20&offset=20"

文章常用字段包括标题、摘要、来源链接、发布日期、风险、实体、威胁标签、处置建议和关联事件。部分字段可能是 null 或空数组；不是每篇文章都有漏洞编号、攻击链或处置建议。政策通常提供标题、摘要及原文链接，不应假定返回全文。

默认权限下，related_event_ids 和 cross_event_timeline 返回空数组，防止通过跨记录关联展开获取范围外的历史数据。全历史授权下，related_event_ids 可用于识别关联报道；不同报道仍保留各自 ID。空字段不应被解释为“已确认没有风险”。

数据持续写入时，列表页的位置可能变化。检索和浏览使用分页即可；建立本地数据库或持续同步时，使用下一节的增量接口。

6. 持续同步到自己的系统

GET /api/v1/changes

参数 说明 默认值或限制
after 从哪个游标之后继续 默认 0，非负整数；使用服务返回的 next_cursor
limit 每次最多返回多少项变更 默认 100，范围 1–200
resource 只同步一种资源 articles 或 policies；不传则两类都同步

第一次从 after=0 开始：

curl -sS --fail-with-body \
  -H "X-API-Key: $WHITZARD_API_KEY" \
  "$WHITZARD_URL/api/v1/changes?after=0&limit=100"

返回结构示意，记录字段已省略部分：

{
  "data": [
    {
      "revision": 123,
      "resource": "articles",
      "id": "example-001",
      "report_type": null,
      "operation": "upsert",
      "changed_at": "2026-10-08 08:00:00",
      "data": {
        "id": "example-001",
        "title": "示例情报标题"
      }
    }
  ],
  "next_cursor": 123,
  "has_more": false
}

report_type 是保留字段，目前为 null，可忽略，不表示报告订阅已开放。

接入程序按以下流程处理：

  1. 首次使用游标 0，后续读取已保存的游标。
  2. 按 (resource, id) 定位本地记录。operation=upsert 表示新增或覆盖；operation=delete 表示删除本地记录，此时 data 为 null。
  3. 本页全部处理成功后，保存 next_cursor。建议数据修改与游标更新在同一个本地事务内完成。
  4. has_more 为 true 时继续读取下一页，同时遵守调用额度；为 false 时建议等 60 秒再拉取。空页也要保存返回游标。

不要把示例中的 123 当作自己的初始游标。重试同一个游标可能收到重复记录，按身份覆盖或删除即可。

如果使用 resource=articles 或 resource=policies，请为各自的筛选方式分别保存游标；更换 resource 时重新从 0 开始，不要混用。

这是最新状态同步，不是完整的修改历史。一条记录在两次拉取间多次修改时，可能只返回最终状态。在授权发布日期范围内，较晚收录的旧文章和已有文章的修订都可以通过此接口获取，不能只按发布日期代替增量同步。

文章、政策、按 ID 查询与增量同步都受相同的权限起点约束。查询范围外的数据返回空列表，不会因传入更早的 start_date 或 after=0 而扩大权限。已可访问的记录被撤回、删除或修正为范围外日期时，同步流会发送 delete；旧删除记录若无法确认原发布日期则不向默认权限返回。

权限扩大或缩小时，请先确认 catalog 中的范围，清理旧镜像并从 after=0 重建；不要沿用原游标。权限缩小不会自动删除客户端以前已经下载的数据。

changed_at 使用 UTC，表示同步记录的变更时间，不是原文发布日期。客户端以 revision/next_cursor 的顺序为准。

7. 调用额度与错误处理

当前默认每个 API Key 每分钟最多 60 次请求，单次最多 200 条记录。实际额度可查看 catalog 的 rate_per_minute。多个程序共用同一密钥时，共享调用额度。

HTTP 状态 常见原因 处理方式
200 调用成功 读取 data；空数组也是正常结果
401 Key 缺失、错误、已撤销，或重复发送 Key 请求头 检查密钥及请求头；仍失败则联系平台对接人员
404 路径不存在或接口未开放 检查地址；reports 当前不开放
405 请求方法不支持 使用 GET
409 同步游标超出当前数据版本 联系平台确认是否需要重新同步；确认后重建本地镜像并从 0 开始
422 参数格式、范围或组合不合法 查看 detail；检查日期、分页、枚举及资源类型
429 超过调用额度 等待 Retry-After 指定的秒数，保持原游标后重试
503 订阅服务尚未配置或暂不可用 稍后重试，持续失败则联系平台对接人员

网络超时或其他 5xx 错误可逐步延长间隔后重试，不要高频循环。同步失败时不要提前推进游标。

排查问题时，请提供请求路径、去除敏感信息的参数、时间与时区、HTTP 状态和错误信息，不要发送包含完整 API Key 的截图或日志。