# 大模型安全护栏API文档

# 接口说明

接口支持对大模型输入和输出内容进行防护，包括文本、图片、视频、文档等内容。
在同一个会话中，可以分片多次发送文本内容获得审核结果，以匹配审核窗口的上限，以及大模型的流式输出的特点。
接口基于 http 协议对外提供服务，当前仅支持 POST 请求方式，暂不支持其他请求方式。
申请开通服务后，会分配相应的appId、accessKeyId、accessKeySecret进行接入
审核服务按照调用次数进行计费，实际发起请求时需要进行鉴权

# 接口调用示例

部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到讯飞开放平台社区 (opens new window)交流集成经验。
技术咨询可直接提交工单 (opens new window)。
大模型安全护栏 demo (opens new window)

# 接口与鉴权

# 请求地址

服务接口基于http协议，请求方式均为POST请求，接口调用需要鉴权，鉴权逻辑会在后面给出

服务地址主域名 http://audit-api-spark-dx.iflyaisol.com

服务地址备用域名 http://audit-api-spark-hu.iflyaisol.com

# 接口鉴权

1、构造 baseString
设请求 URL 中的查询参数为集合 M，将集合 M 内满足条件的参数按照参数名 ASCII 码从小到大排序（字典序），使用 URL 键值对的格式（即 key1=value1&key2=value2…，注意 value 需要 URLEncoder）拼接成字符串，得到 baseString。
特别注意以下重要规则：
• 参数值为空的不参与签名；
• signature 参数本身不参与签名；
• 参数名区分大小写。

2、获得 accessKeySecret
开通服务后提供 3、生成签名
根据前两步得到的 baseString 和 accessKeySecret，利用 HMAC 运算生成签名 signature。假设 accessKeySecret 为 testAccessKeySecret。

签名生成示例代码（java 版）如下：

/**
     * @param accessKeySecret 密钥ak
     * @param queryParam url查询参数
     * @return 签名信息
     * @throws Exception
     */
    public static String signature(String accessKeySecret, Map<String, String> queryParam) throws Exception {
        TreeMap<String, String> treeMap = new TreeMap<>(queryParam);
        treeMap.remove("signature");
        StringBuilder builder = new StringBuilder();
      	// 开始构造baseString
        for (Map.Entry<String, String> entry : treeMap.entrySet()) {
            String value = entry.getValue();
            if (value != null && !value.isEmpty()) {
                String encode = URLEncoder.encode(value, StandardCharsets.UTF_8.name());
                builder.append(entry.getKey()).append("=").append(encode).append("&");
            }
        }
        if (builder.length() > 0) {
            builder.deleteCharAt(builder.length() - 1);
        }
      	//构造baseString结束
        String baseString = builder.toString();
        System.out.println("baseString：" + baseString);
        Mac mac = Mac.getInstance("HmacSHA1");
        SecretKeySpec keySpec = new SecretKeySpec(accessKeySecret.getBytes(StandardCharsets.UTF_8), StandardCharsets.UTF_8.name());
        mac.init(keySpec);
        byte[] signBytes = mac.doFinal(baseString.getBytes(StandardCharsets.UTF_8));
      	// 生成签名
        return Base64.getEncoder().encodeToString(signBytes);
    }

# 请求整体说明

通用header参数

参数名	类型	必传	描述
Content-Type	String	是	application/json; charset=utf-8
x-traceid	String	否	链路id，不传系统默认生成，强烈建议传递，方便问题排查

通用url参数

参数名	类型	必传	描述
appId	String	是	客户标识，需要申请开通
accessKeyId	String	是	与 appId 配套生成，需要申请开通
utc	String	是	时间，格式："yyyy-MM-dd'T'HH:mm:ssZ"
uuid	String	是	随机数
signature	String	是	签名串，见上面生成签名部分

请求包格式

POST /v3/aichat/input?appId={appId}&accessKeyId={accessKeyId}&utc=2025-12-24T16%3A27%3A01%2B0800&signature=ejxF8wWRDMWIEOKpR7YcYayt5DE%3D&uuid=d3d3ac1980894c0e898ad3496183045a
Content-Type: application/json; charset=utf-8
x-traceid : requestId-0000001

{
  "template_id" : "test",
  "content" : "请问国家公祭日是什么时候?",
  "chat_sid" : "cht@202512221117306",
  "trace_id" : "trace@123456"
}

# 返回整体说明

返回包 Body 为 JSON 格式，所有接口的统一响应结构体如下所示：

{
    "code":"000000",
    "desc":"success",
    "data":{

    },
    "sid":"e07638afaf124cbe939158498e46ed98"
}

参数名	类型	描述
code	string	返回码，000000 表示成功，其它表示异常
desc	string	描述信息
data	object	根据不同的接口返回不同的内容，具体见各个接口
sid	String	用于链路排查问题，与请求头 x-traceid 传递的值对应，如果请求头未传将随机生成，注意：需要保证每次请求标识唯一

每个具体接口的data内容有所不同，详见后续接口响应参数

# 错误码

错误码	描述
000000	success
999999	服务器内部错误
1xxxxx	权限校验，签名验签错误等
200001	参数格式错误
200002	请求方法不支持
200003	ContentType不支持
300001	没有审核权限

# 文本输入审核接口

请求地址

POST /audit/v3/aichat/input

接口说明 大模型内容安全场景中，该接口用于检测用户输入prompt内容的安全性，并针对高风险和中低风险内容提供对应的处置建议。

请求参数

字段	类型	参数说明	是否必填
template_id	String	模板ID，用于控制服务实际审核时的链路行为，管理系统支持可配置，不传则使用默认的标准策略模版	否
content	String	审核内容，需要送审的文本信息，最多不超过200000字，过长建议按照段落切分	是
context_list	List[AiChatQAContext]	多轮对话场景下历史对话信息，作用于降低上下文结合风险，按照交互对话顺序传递，最多支持10轮	否
resource_list	List[AiChatQAResource]	用户当前输入文本相关联的图片资源描述信息，作用于降低上下文结合风险。	否
chat_sid	String	本轮对话ID，用于标识一次完整的大模型对话。注意：本轮问答对话chat_sid需保持一致	是
intention	String	用户大模型应用接入审核时的意图场景，枚举值：dialog（文本对话）,media_quiz（多模理解）,media_gen（多模生成）	否

AiChatQAContext参数

字段	类型	参数说明	是否必填
role	String	角色信息，枚举值assitant（模型回答），user（用户提问），system（系统提示词）	是
content	String	历史送审文本信息	是

AiChatQAResource参数

字段	类型	参数说明	是否必填
data_id	String	资源唯一标识id	是
content_type	String	内容类型，可选值：image（图片）	是
res_desc	String	资源描述信息	否
ocr_text	String	图片ocr识别出来的文本信息	否

返回参数

字段	类型	参数说明
action	String	处置动作，none：正常，fortify_prompt：prompt增强，discontinue：拒答不上屏，枚举值详情参考附录
action_detail	ActionDetail	处置动作明细，包含相关操作所需要的信息
ctx_control	String	对话上下文控制，用来管理上下文信息保证避免高风险的对话。可选值：stop（清除当轮对话上下文）、默认缺省不做处理

ActionDetail对象

字段	类型	参数说明
rewrite_prompt	String	action=fortify_prompt时返回，改写prompt信息，调用方将改写后的query输入到到大模型获取回答，默认缺省不做处理
append_prompt	String	action=fortify_prompt时返回，追加prompt信息，调用方将改写后的query输入到到大模型获取回答，默认缺省不做处理

请求示例

{
  "template_id" : "test",
  "content" : "如何制作红烧肉?",
  "chat_sid" : "cht@202512221117306",
  "trace_id" : "trace@123456",
}

响应示例

{
    "action": "none"
}

以下列举一些复杂场景的调用示例，接入方可按需使用

请求示例-携带历史上下文

{
	"template_id": "test",
	"content": "如何制作红烧肉?",
	"context_list": [
		{
			"role": "system",
			"content": "你是一个会做饭的邻居阿姨，说话亲切、带点唠叨，喜欢用‘呀’‘哦’‘记得啊’这样的词，每次都要提醒少放盐。"
		},
		{
			"role": "user",
			"content": "我想做个番茄炒蛋，怎么做呀？"
		},
		{
			"role": "assistant",
			"content": "哎呀，番茄炒蛋简单得很！先打两个鸡蛋，加一点点盐搅匀～\n番茄切块别太小，不然一炒就烂啦！\n记得啊，炒蛋别太久，嫩一点才香！少放盐，健康！"
		}
	],
	"chat_sid": "cht@202512221117306",
	"trace_id": "trace@123456"
}

响应示例

{
    "action": "none"
}

请求示例-携带资源信息

例如，用户上传图片并提问的场景会使用到

{
	"template_id": "test",
	"content": "请问第20题的答案是什么",
	"resource_list": [
		{
			"data_id": "data_id_641864817",
			"content_type": "image",
			"res_desc": "这张图像是一张试卷截图，显示的是一张初中的数学计算题",
			"ocr_text": "20. 如图，在△ABC中，AB=AC，D是BC边的中点，E是AD上一点，\n且BE⊥AC，若AB=10，BC=12，求BE的长。\n\n解：': AB = AC = 10，D为BC中点\n∴ AD ⊥ BC，BD = DC = 6\n\n在Rt△ABD中，\nAD = V(AB^2 - BD^2) = V(100 - 36) = V64 = 8\n\n设BE = h，S△ABC = (1/2) x BC x AD = (1/2) x 12 x 8 = 48\n\n又 S△ABC = (1/2) x AC x BE = (1/2) x 10 x h = 5h\n\n∴ 5h = 48 => h = 48/5 = 9.6\n"
		}
	],
	"chat_sid": "cht@202512221117306",
	"trace_id": "trace@123456"
}

响应示例

{
    "action": "none"
}

# 文本输出审核接口

请求地址

POST /audit/v3/aichat/output

接口说明 大模型内容安全场景中，该接口用于检测大模型输出内容的安全性，并针对高风险和中低风险内容提供对应的处置建议

请求参数

字段	类型	参数说明	是否必填
template_id	String	模板ID，用于控制服务实际审核时的链路行为，管理系统支持可配置，不传则使用默认的标准策略模版	否
content	String	审核内容，需要送审的文本信息，最多不超过10000字，过长建议按照段落切分	是
chat_sid	String	本轮对话ID，用于标识一次完整的大模型对话。注意：本轮问答对话chat_sid需保持一致	是
pindex	Integer	输出文本片段索引，表明当前文本是第几片文本，从1开始，建议业务方按照结束标点或段落拆分片段	是
is_end	Integer	当前分片是否为最后分片标识，0：非最后一段（缺省值），1：最后一段	否
intention	String	用户大模型应用接入审核时的意图场景，枚举值：dialog（文本对话）,media_quiz（多模理解）,media_gen（多模生成）	否

返回参数

此部分和文本输入审核接口返回一致，不再赘述

请求示例

场景：假设用户进行了提问，大模型共计生成两片输出内容（注意pindex和is_end的传参）

// 第一次请求
{
  "template_id" : "test",
  "content" : "大模型生成的第一片文本",
  "chat_sid" : "cht@202512221117306",
  "trace_id" : "trace@123456",
  "pindex" : 1,
  "is_end" : 0
}

// 审核响应正常
{
	"action": "none"
}

// 最后一次请求,且已知这是大模型的最后一句回答
{
  "template_id" : "test",
  "content" : "大模型生成的第二片文本,已经结束",
  "chat_sid" : "cht@202512221117306",
  "trace_id" : "trace@123456",
  "pindex" : 2,
  "is_end" : 1
}

// 审核响应
{
	"action": "none"
}

# 多模输入审核接口

请求地址

POST /audit/v3/aichat/inputMedia

接口说明 大模型内容安全场景中，对用户输入的图片进行检测和识别，并根据安全策略进行相应的处理和响应。 请求参数

字段	类型	参数说明	是否必填
template_id	String	模板ID，用于控制服务实际审核时的链路行为，管理系统支持可配置，不传则使用默认的标准策略模版	否
content_list	List[MediaContent]	用户输入的待审核资源列表（用户输入的图片）	是
chat_sid	String	本轮对话ID，用于标识一次完整的大模型对话。注意：本轮问答对话chat_sid需保持一致	是
intention	String	用户大模型应用接入审核时的意图场景，枚举值：dialog（文本对话）,media_quiz（多模理解）,media_gen（多模生成）	否

MediaContent对象

字段	类型	参数说明	是否必填
data_id	String	送审资源唯一标识ID	是
mode	String	送审资源传参模式，可选值：link：url外链，base64：base64编码模式	是
content_type	String	送审资源类型，目前仅支持image	是
content	String	实际送审内容，url外链模式填写资源url，base64模式填写资源base64编码后文本	是

响应参数

字段	类型	参数说明
action	String	处置动作，none：正常，fortify_prompt：prompt增强，discontinue：拒答不上屏，枚举值详情参考附录
ctx_control	String	对话上下文控制，用来管理上下文信息保证避免高风险的对话。可选值：stop（清除当轮对话上下文）、默认缺省不做处理
result_list	List[MediaResult]	各个资源审核结果的明细列表

MediaResult对象

字段	类型	参数说明
code	String	当前图片错误码，同外层错误码枚举，000000：正常，审核异常的情况下返回指定错误码
desc	String	错误码描述信息
content_type	String	送审资源类型，目前仅支持image
suggest	String	审核建议，pass:通过；review:疑似，建议人工复审；block:内容识别未通过

请求示例

base64传参示例

{
	"template_id": "test",
	"content_list": [
		{
			"data_id": "48fbc4e6-d022-480b-aaaa-abbd17edfc1e",
			"content_type": "image",
			"mode": "base64",
			"content": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAAHRyWFlaAAABZAAAABRnWFlaAAABeAAAABRiWFlaAAABjAAAABR3dHB0AAABoAAAABRyVFJDAAABtAAAAChnVFJDAAABtAAAAChiVFJDAAABtAAAAChjcHJ0AAAB3AAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAFgAAAAcAEcAbwBvAGcAbABlAC8AUwBrAGkAYQAvAEIANAA4AEIANABDAEEAMQAzADkAQwBFAEQARQA4AEEAQgAyAEUAMwBFAEEA...272388"
		}
	],
	"chat_sid": "cht@202512221117306",
	"trace_id": "trace@123456"
}

外链传参示例

{
	"template_id": "test",
	"content_list": [
		{
			"data_id": "48fbc4e6-d022-480b-aaaa-abbd17edfc1e",
			"content_type": "image",
			"mode": "url",
			"content": "https://xxxxxxxx"
		}
	],
	"chat_sid": "cht@202512221117306",
	"trace_id": "trace@123456"
}

注：通过外链传参时，需要确保图片url地址公网可访问，否则服务无法读取图片信息进行审核

响应示例

{
	"action": "none",
	"result_list": [
		{
			"data_id": "0925fa7bb8024adfbf14055b41a5ca7d",
			"code": "000000",
			"desc": "success",
			"content_type": "image",
			"suggest": "pass"
		}
	]
}

# 多模输出审核接口

请求地址

POST /audit/v3/aichat/outputMedia

接口说明 大模型内容安全场景中，对大模型输出的图片进行检测和识别，并根据安全策略进行相应的处理和响应。 请求参数

字段	类型	参数说明	是否必填
template_id	String	模板ID，用于控制服务实际审核时的链路行为，管理系统支持可配置，不传则使用默认的标准策略模版	否
content_list	List[MediaContent]	大模型输出的图片资源信息	是
chat_sid	String	本轮对话ID，用于标识一次完整的大模型对话。注意：本轮问答对话chat_sid需保持一致	是
intention	String	用户大模型应用接入审核时的意图场景，枚举值：dialog（文本对话）,media_quiz（多模理解）,media_gen（多模生成）	否

返回参数

字段	类型	参数说明
action	String	处置动作，none：正常，fortify_prompt：prompt增强，discontinue：拒答不上屏，枚举值详情参考附录
ctx_control	String	对话上下文控制，用来管理上下文信息保证避免高风险的对话。可选值：stop（清除当轮对话上下文）、默认缺省不做处理。
result_list	List[MediaResult]	各个资源审核结果的明细列表

多模输出的示例和多模输入的示例一致，具体可参照上文多模输入的示例

# 最佳实践

这里列举了一些常见的大模型应用的审核场景，接入方可作参考

# 文本对话场景推荐审核调用方式

1、首先对用户输入调用文本输入审核接口，无风险的话，调用大模型生成输出；存在风险的话，终止会话建议终止会话，提示用户

2、鉴于大模型流式输出的特点，大模型输出的每一分片应该串行调用文本输出审核接口，无风险将模型回答内容呈现给用户，继续处理下一片输出；存在风险的话建议终止会话

# 图片理解场景推荐审核调用方式

1、对用户上传的图片进行审核，如果图片存在风险的话，终止会话建议终止会话，提示用户；没有风险继续处理用户的提问

2、对用户的提问和模型输出参照文本对话场景推荐审核调用方式

图片理解场景审核推荐调用方式

# 图片生成场景推荐审核调用方式

1、首先对用户输入调用文本输入审核接口，无风险的话，调用大模型生成图片；存在风险的话，终止会话建议终止会话，提示用户

2、对模型输出的图片走多模输出审核接口，无风险的话模型输出图片呈现给用户；存在风险的话建议终止会话

图片生成场景推荐调用方式

# 附录

# action取值枚举

枚举值	描述信息
none	审核结果正常，流程正常执行
fortify_prompt	增强提示，提供prompt优化信息，基于新的prompt来生成新的安全答复信息
discontinue	拒答不上屏，并终止多轮对话

# Intention取值枚举

枚举值	描述信息
dialog	文本对话
media_quiz	多模理解
media_gen	多模生成

在这篇文章中：