API接入

本文档介绍API接入的方法。

文本检测API说明

您可以调用该接口创建文本内容检测任务。

业务接口：POST https://{endpoint}/v1/{project_id}/aiguard/text-detect
支持的地域及接入地址：西南-贵阳一、华北-北京四、中国-香港
支持的地域对应的API域名：
- 西南-贵阳一：cn-southwest-2.aiguard.myhuaweicloud.cn
- 华北-北京四：cn-north-4.aiguard.myhuaweicloud.cn
- 中国-香港：ap-southeast-1.aiguard.myhuaweicloud.cn

请求参数

表1 请求path参数
名称	类型	是否必选	描述
v1	String	是	API接口版本。
project_id	String	是	如使用op账号调用，则使用op账号项目ID信息；如使用最终租户账号调用，则使用最终租户账号项目ID信息。
aiguard	String	是	API接口组件名称。
text-detect	String	是	API接口调用类型。

表2 请求header参数
名称	类型	是否必选	描述
Source-Signature	String	是	业务方签名，用于标示业务方身份，华为云内部服务调用时必传该字段。
Content-Type	String	否	文本请求默认为application/json。

表3 TextDetectionReq请求体
名称	类型	是否必选	描述
app_id	String	是	应用ID，用于区分配置。
message	表5	是	文本检测请求数据体。
history	Array of 表5	否	对话的历史数据，最多支持20轮。列表排序越前面的表示越早期的对话。越后面的表示越接近现在的对话。
extra	表4	否	受限公开字段。

表4 Extra
名称	类型	是否必选	描述
end_user	String	否	最终租户projectid（服务使用Op账号调用时，传此字段，供安全运营、识别恶意最终租户）。
source_region	String	否	最终租户调用的原始region（供安全运营）。

表5 Message
名称	类型	是否必选	描述
role	String	是	输入字段类型，可选值如下： user（默认）：用户输入请求内容 assistant：模型输出内容 system：系统提示词对于响应或多轮对话，以最新的内容为准。
content	String	是	检测文本，支持（1~262144），超过256K长度取后256K进行检测。如果超过这个长度，AI安全护栏会截断，只取后面的部分。

响应参数

返回状态码：200

表6 TextDetectionResponse
名称	类型	是否必选	描述
request_id	String	是	本次请求的唯⼀标识，⽤于问题排查，建议保存。
maf_engine	String	是	厂商信息，默认为cllmfw。
result	表1-10 TextDetectionResult	否	请求成功时表示调用结果。请求失败时无此字段。
error	表1-15 ErrorBody	否	请求出问题时返回的字段请求成功无此字段。

表7 TextDetectionResult
名称	类型	是否必选	描述
suggestion	String	是	审核结果是否通过。配置的异常处理动作：观察、脱敏、拦截 pass：未检测到异常信息。任何观察(log)和脱敏(desensitize)都在pass类别中。 block：检测到异常信息。
risk_types	Array of String	是	命中的风险类型，例如合规攻击、注入攻击。
hit_details	Array of 表8	是	检测详情。
replacement	String	否	配置脱敏时生效，当前仅支持违规词库脱敏。(白词库，语义模型当前不用脱敏) 若没有配置脱敏，返回空字段。

表8 TextDetectionResultDetail
名称	类型	是否必选	描述
risk_type	String	是	命中的风险类型，例如合规攻击、注入攻击。
sub_risk_type	Array of String	是	命中的风险子类型，支持合规检测的标签、自定义词库的名字。更多信息请参见功能介绍。
prob	Float	是	置信度分数，命中词库时默认为1.0。
segments	Array of 表9	否	用于词库。单个词库命中所有风险片段信息，如果命中了语义算法模型，则会返回一个空的列表。

表9 SegmentInfo
名称	类型	是否必选	描述
segment	String	是	命中的风险片段。
category	String	是	命中的词库。自定义词库为词库的名称，内置词库为词库的类别。
position	Array of Integer	否	命中词库时生效。命中的风险片段在文本中的起始位置，从0开始。否则无字段。
lexicon_id	String	否	命中自定义词库时生效，返回对应词库ID。否则无字段。
lexicon_type	String	否	0：豁免。 1：违规。命中自定义词库时生效，返回自定义词库是豁免还是违规。

**表10** ErrorBody
名称	类型	是否必选	描述
error_code	String	是	错误码长度：8
error_msg	String	是	错误描述最小长度：2 最大长度：512

示例代码

# 1. Define Access Credentials
AK="<your_access_key>"
SK="<your_secret_key>"
# 2. Generate Timestamp and Signature
# Get current timestamp in milliseconds
TS=$(date +%s%3N)
# Calculate HMAC-SHA256 signature
# Format: AK&Timestamp
SIG=$(echo -n "${AK}&${TS}" | openssl dgst -sha256 -hmac "$SK" -binary | base64)
# 3. Define Request Parameters
# 请替换为您实际的项目 ID (project_id)
PROJECT_ID="<your_project_id>"
REGION_URL="<your_region_url>"
API_URL="https://${REGION_URL}/v1/${PROJECT_ID}/aiguard/text-detect"
# 4. Execute the Request
curl -kv -X POST "${API_URL}" \
    -H "Content-Type: application/json" \
    -H "Source-Signature: HMAC-SHA256 source_id=${AK}, timestamp=${TS}, signature=${SIG}" \
    -d '{
        "app_id": "<your_app_id>",
        "history": [
            {"role": "system", "content": "你是一个好帮手"},
            {"role": "user", "content": "你好，介绍下你自己"},
            {"role": "assistant", "content": "我是你的大模型助手。"},
        ],
        "message": {
            "role": "user", 
            "content": "hello"
        }}'

图片检测API说明

您可以调用该接口创建图片内容检测任务。

业务接口：POST https://{endpoint}/v1/{project_id}/aiguard/image-detect
支持的地域及接入地址：西南-贵阳一、华北-北京四、中国-香港

支持的地域对应的API域名：
- 西南-贵阳一：cn-southwest-2.aiguard.myhuaweicloud.cn
- 华北-北京四：cn-north-4.aiguard.myhuaweicloud.cn
- 中国-香港：ap-southeast-1.aiguard.myhuaweicloud.cn

请求参数

**表11** 请求path参数
名称	类型	是否必选	描述
v1	String	是	API接口版本。
project_id	String	是	如使用op账号调用，则使用op账号项目ID信息；如使用最终租户账号调用，则使用最终租户账号项目ID信息。
aiguard	String	是	API接口组件名称。
image-detect	String	是	API接口调用类型。

**表12** 请求header参数
名称	类型	是否必选	描述
Source-Signature	String	是	业务方签名，用于标示业务方身份，华为云内部服务调用时必传该字段。
Content-Type	String	否	文本请求默认为application/json。

**表13** PicDetectionReq请求体
名称	类型	是否必选	描述
app_id	String	是	应用ID，用于区分配置。
message	表15	是	图片检测请求数据体。
extra	表14	否	受限公开字段。

**表14** Extra
名称	类型	是否必选	描述
end_user	String	否	最终租户projectid（服务使用Op账号调用时，传此字段，供安全运营、识别恶意最终租户）。
source_region	String	否	最终租户调用的原始region（供安全运营）。

**表15** Message
名称	类型	是否必选	描述
role	String	是	输入字段类型，可选值如下： user（默认）：用户输入请求内容 assistant：模型输出内容 system：系统提示词对于响应或多轮对话，以最新的内容为准。
content	String	是	[{"type": "text", "text": "图里有什么？"}, {"type": "image_url", "image_url": {"url": ""} }] 检测的图片内容，匹配first(item in list where item.type == "image_url").image_url.url 如果有多个图片的url，目前只检测匹配到的第一个。说明：仅支持base64，且url里面base64的格式也是固定的data:xxx;base64,xxx，例如：（data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAA）

响应参数

**表16** ImageDetectionResponse
名称	类型	是否必选	描述
request_id	String	是	本次请求的唯⼀标识，⽤于问题排查，建议保存。
maf_engine	String	是	厂商信息，默认为cllmfw。
result	表17	否	请求成功时表示调用结果。请求失败时无此字段。
error	表20	否	请求出问题时返回的字段请求成功无此字段。

**表17** ImageDetectionResult
名称	类型	是否必选	描述
suggestion	String	是	审核结果是否通过。配置的异常处理动作：观察、脱敏、拦截。 pass：未检测到异常信息。任何观察(log)和脱敏(desensitize)都在pass类别中。 block：检测到异常信息。
risk_types	Array of String	是	命中的风险类型，例如合规攻击、注入攻击。
hit_details	Array of 表18	是	检测详情。
replacement	String	否	配置脱敏时生效，当前仅支持违规词库脱敏。(白词库，语义模型当前不用脱敏)。若没有配置脱敏，返回空字段。

**表18** ImageDetectionResultDetail
名称	类型	是否必选	描述
risk_type	String	是	命中的风险类型，例如合规攻击、注入攻击。
sub_risk_type	Array of String	是	命中的风险子类型，支持合规检测的标签、自定义词库的名字。更多信息请参见功能介绍。
prob	Float	是	置信度分数，命中词库时默认为1.0。
segments	Array of 表19	否	用于词库。单个词库命中所有风险片段信息，如果命中了语义算法模型，则会返回一个空的列表。
risk_source	String	否	只针对图片。用于反映是图片文本的风险还是图片语义的风险。

**表19** SegmentInfo
名称	类型	是否必选	描述
segment	String	是	命中的风险片段。
category	String	是	命中的词库。自定义词库为词库的名称，内置词库为词库的类别。
position	Array of Integer	否	命中词库时生效。命中的风险片段在文本中的起始位置，从0开始。否则无字段。
lexicon_id	String	否	命中自定义词库时生效，返回对应词库ID。否则无字段。
lexicon_type	String	否	0：豁免 1：违规命中自定义词库时生效，返回自定义词库是豁免还是违规。

**表20** ErrorBody
名称	类型	是否必选	描述
error_code	String	是	错误码，长度为8。
error_msg	String	是	错误描述。最小长度为2，最大长度为512。

示例代码

# 1. Define Access Credentials
AK="<your_access_key>"
SK="<your_secret_key>"
# 2. Generate Timestamp and Signature
# Get current timestamp in milliseconds
TS=$(date +%s%3N)
# Calculate HMAC-SHA256 signature
# Format: AK&Timestamp
SIG=$(echo -n "${AK}&${TS}" | openssl dgst -sha256 -hmac "$SK" -binary | base64)
# 3. Define Request Parameters
# 请替换为您实际的项目 ID (project_id)
PROJECT_ID="<your_project_id>"
REGION_URL="<your_region_url>"
API_URL="https://${REGION_URL}/v1/${PROJECT_ID}/aiguard/image-detect"
# 4. Execute the Request
curl -kv -X POST "${API_URL}" \
    -H "Content-Type: application/json" \
    -H "Source-Signature: HMAC-SHA256 source_id=${AK}, timestamp=${TS}, signature=${SIG}" \
    -d '{
        "app_id": "<your_app_id>",
        "message": {
            "role": "user",
            "content": [
                {"type": "text", "text": "图里有什么？"},
                {
                    "type": "image_url",
                    "image_url": 
                        {
                            "url": "<your_image_full_base64>" // base64输入
                        }
                }
            ]
        }
    }'

父主题：接入与卸载方案

上一篇：接入与卸载方案

下一篇：SDK接入与卸载

API接入

文本检测API说明

请求参数

响应参数

示例代码

图片检测API说明

请求参数

响应参数

示例代码

相关文档

您对此文档页面的整体评价？