API Reference

AI 隐私网关 API 文档

一个与 OpenAI 兼容的接口。敏感信息在离开您的网络之前完成识别与替换，模型只看到假名化后的文本，返回结果再自动还原。

工作原理

网关位于您的应用与大模型之间。请求到达后，先由 PII 引擎识别中文敏感信息，按策略替换为格式一致的假名（手机号仍是手机号、身份证仍能通过校验位），再转发给模型；模型返回后，网关把假名还原成原值。

假名与原值的映射保存在本地令牌库中，同一个原值在同一租户下始终得到同一个假名，因此模型仍能理解「这两条记录是同一个人」，而无需知道这个人是谁。

与直接调用模型的差别只有两处：把 base_url 指向本网关，把 api_key 换成网关签发的密钥。其余请求体格式完全不变。

快速开始

Base URL https://api.mogai.cn/v1

使用任意 OpenAI 兼容的 SDK。以 Python 为例：

Python · openai SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.mogai.cn/v1",
    api_key="mpg_live_xxxxxxxx_your_secret",   # 网关签发的密钥
)

resp = client.chat.completions.create(
    model="dashscope/qwen-max",
    messages=[{
        "role": "user",
        "content": "客户张伟，手机号13800138000，请写一句回访问候语。",
    }],
)

print(resp.choices[0].message.content)

或直接用 HTTP 调用：

curl

curl https://api.mogai.cn/v1/chat/completions \
  -H "Authorization: Bearer mpg_live_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
        "model": "dashscope/qwen-max",
        "messages": [
          {"role": "user", "content": "客户手机号13800138000，请回访"}
        ]
      }'

PowerShell 用户注意：请使用 -ContentType 'application/json; charset=utf-8' 参数，不要把 Content-Type 写在 -Headers 里。 Windows PowerShell 5.1 在未声明 charset 时会以 ISO-8859-1 编码请求体，中文会在发送前变成问号。

认证

所有接口（除 /healthz）都需要在请求头中携带密钥：

HTTP Header

Authorization: Bearer mpg_live_xxxxxxxx_your_secret

密钥格式为 mpg_{环境}_{编号}_{密文}：

密钥只在创建时显示一次。系统仅保存其哈希值，无法找回。密钥泄露时请立即联系我们吊销，吊销在 30 秒内生效。

对话补全

POST /v1/chat/completions

与 OpenAI 的同名接口保持兼容。请求体中的 messages 会先经过脱敏，模型返回后自动还原。

请求参数

返回示例

标准 OpenAI 响应，额外附带一个 mpg 字段，记录本次请求的脱敏与计费情况。

200 OK

{
  "id": "chatcmpl-...",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "张伟先生您好，..."
      }
    }
  ],
  "usage": { "prompt_tokens": 42, "completion_tokens": 28 },
  "mpg": {
    "request_id": "7c1f...",
    "entities_processed": 2,
    "jurisdiction": "domestic",
    "egress": "direct",
    "cost": 0.0043,
    "balance": 99.9957,
    "audit_head": "a3f1..."
  }
}

暂不支持流式输出。stream: true 会返回 400。返回内容需要整体扫描后才能还原，逐 token 推送无法保证不泄漏；我们选择明确报错，而不是在后台缓冲后假装是流式。

脱敏 / 还原

不调用模型，仅做脱敏与还原。适合数据入仓、日志清洗、对外导出等场景， 不产生模型费用。

POST /v1/tokenize

请求 / 响应

// 请求
{
  "text": "客户张伟手机号13800138000，请回访",
  "language": "zh",
  "model": "dashscope/qwen-max"
}

// 响应
{
  "text": "客户黄明手机号15944857843，请回访",
  "surrogates": { "黄明": "张伟", "15944857843": "13800138000" },
  "decisions": [
    { "entity_type": "PERSON",    "action": "tokenize", "confidence": 1.0 },
    { "entity_type": "CN_MOBILE", "action": "tokenize", "confidence": 1.0 }
  ]
}

为什么要传 model？ 脱敏强度取决于数据要发往哪里。发往境内模型与境外模型适用不同策略，因此调用方必须声明目的地。仅做本地清洗时可传 local/none。

POST /v1/detokenize

把假名还原为原值，需要传入脱敏时返回的 surrogates。

请求

{
  "text": "客户黄明手机号15944857843，请回访",
  "surrogates": { "黄明": "张伟", "15944857843": "13800138000" }
}

仅识别

POST /v1/detect

只报告文本中包含哪些敏感信息及其位置，不做任何替换。适合做合规扫描、风险评估或数据资产盘点。

请求 / 响应

// 请求
{ "text": "身份证11010519491231002X", "language": "zh" }

// 响应
{
  "entities": [
    { "entity_type": "CN_ID_CARD", "start": 3, "end": 21, "score": 0.95 }
  ]
}

健康检查

GET /healthz

无需认证。用于负载均衡与监控探活。

200 OK

{ "ok": true, "audit_head": "a3f1..." }

audit_head 是审计日志的哈希链头。每条请求都会追加一条记录，链头随之变化；定期留存该值即可对外证明日志未被篡改。

模型列表

model 参数必须使用下表中完整的模型标识（含厂商前缀）。缺少前缀会返回 400。

共 {{ filteredModels.length }} 个

当前仅阿里云百炼（DashScope）系列已开放。 其余模型的接入通道已就绪，开放时间取决于合规评估与出境链路准备情况。如需提前开通，请联系我们。

境外模型涉及数据出境。即便经过假名化，是否合规仍需结合业务场景评估。默认策略下，身份证、银行卡等高敏字段发往境外模型时会被直接拦截而非替换。

识别类型

针对中文场景设计。带校验位的类型会做真实校验，而不是仅靠正则匹配长度，因此订单号、时间戳等不会被误判为身份证。

策略动作

每个识别到的实体，会依据租户策略与目标模型所在区域，得到一个动作：

识别引擎不可用时，网关拒绝请求（503），不会放行原文。 宁可请求失败，也不让未经检查的数据流向模型。

计费

采用预付费余额。每次调用按模型的输入 / 输出 token 单价计费，费用与余额在响应的 mpg 字段中实时返回。

脱敏类接口不计模型费用。 /v1/tokenize、/v1/detokenize、 /v1/detect 不调用大模型，因此不产生 token 费用。

错误码

错误响应为 JSON，包含 error 与 detail 字段。