版本

1. 简介

1.1 说明

主要用于AI视觉管理平台开放接口说明，通过本文档可以明确该平台对外开放的所有接口以及对接规范

2. 公共部分

2.1 说明

本节涉及到的规则、对象等是所有接口共同的属性跟行为规范

2.2 Header

2.3 鉴权

鉴权指的是Header中的Authorization字段，value 遵循 Http Bearer Token 协议规范，是一个JWT_TOKEN，JWT_TOKEN 由点分割为三个部分，其中Header 部分的kid 为AccessKey，AccessKey 与 SecretKey 由平台统一颁发，iat 为签发时间，exp 为 过期时间，JWT_TOKEN 为标准JWT，需要拥有JWT基础知识后再根据以下信息生成

1. Decoded Header

{
"kid": "0B553EB26124479DA1FB7CB26BBC1E8F",
"alg": "HS256",
"typ": "JWT"
} 

2. Decoded Payload

{
"iat": 1772432854,
"exp": 1803968854
}

3. JWT Signature

Signature = HMACSHA256(
  Base64UrlEncode(header) + "." + Base64UrlEncode(payload),
  secret
)

2.3 返回值

{
    "code": 20000,
    "success": true,
    "clientRequestId":"332996B32A2746E99303DAD731592551",
    "serverResponseId": "30817637A95B4D00B1A00E0E4B3C1026",
    "name": "Ok",
    "message": "success",
    "elapsedTime": 492,
    "data": null
}

2.4 SDK

鉴于鉴权的复杂性，建议客户端集成SDK以快速对接服务端接口。目前仅提供Java语言的SDK, 以下为内部依赖坐标

2.4.1 依赖

<dependency>
  <groupId>com.hisign</groupId>
  <artifactId>hisign-commons-api-sdk</artifactId>
  <version>${VERSION}</version>
</dependency>

<dependency>
  <groupId>com.hisign</groupId>
  <artifactId>ai-vision-platform-sdk-openapi-model</artifactId>
  <version>${VERSION}</version>
</dependency>

<dependency>
  <groupId>com.hisign</groupId>
  <artifactId>ai-vision-platform-sdk-openapi</artifactId>
  <version>${VERSION}</version>
</dependency>

2.4.2 依赖历史版本

2.4.3 平台、服务、SDK接口之间的关系

2.4.4 SDK 接口初始化示例

构建管理服务接口

/**
 * 协议基本参数，以下为测试数据，请根据实际情况变更
 */
String protocol = "https";// 协议
String domain = "ai-vision.livedetect.cn";// 域名
int port = 443;// 端口
String accessKey = "0B553EBxx124479DAAFB7CB26Bxx1E8F";//
String secretKey = "0C4B5E2xx2B74C2BAA987977A8xx2E9B";//

// 默认客户端与服务器端的时间是同步的，如果不同步则需要设置偏移量
Duration timeOffsetFromServer = null;
// 假如客户端时间-标准时间=20s，那么需要偏移-20s
// Duration timeOffsetFromServer = Duration.ofSeconds(-20)
// 假如客户端时间-标准时间=-20s，那么需要偏移20s
// Duration timeOffsetFromServer = Duration.ofSeconds(20)

Duration tokenValidityDuration = Duration.ofSeconds(10);// 默认请求的Token过期时长
Boolean disableSslValidation = false;// https协议 是否禁用ssl验证
Duration httpTimeoutDuration = Duration.ofSeconds(10);// 协议请求、连接、读取、回写默认时长
String clientRequestId = LangUtils.getUppercaseUUID();// 客户端请求ID，可以自定义请求ID

/**
 * 构建API对象, 该对象建议全局单例, 如果调用不同的接口有不同的超时或其他的参数标准，可全局实例化多个
 */
ManageApi manageApi = new ManageApiImpl(new OpenVisionTokenKeyApi(protocol, domain, port,
    new HttpClientParam(disableSslValidation, httpTimeoutDuration, httpTimeoutDuration, httpTimeoutDuration,
        httpTimeoutDuration),
    new TokenKey(accessKey, secretKey, tokenValidityDuration, timeOffsetFromServer)));

构建隐私服务接口

/**
 * 协议基本参数，以下为测试数据，请根据实际情况变更
 */
String protocol = "http";// 协议
String domain = "127.0.0.1";// 域名
int port = 443;// 端口
String accessKey = "0BxxxEB26124479DA1F17CB26BBCxxxF";//
String secretKey = "0CxxxE2482B74C2BA4917977A871xxxB";//

// 默认客户端与服务器端的时间是同步的，如果不同步则需要设置偏移量
Duration timeOffsetFromServer = null;
// 假如客户端时间-标准时间=20s，那么需要偏移-20s
// Duration timeOffsetFromServer = Duration.ofSeconds(-20)
// 假如客户端时间-标准时间=-20s，那么需要偏移20s
// Duration timeOffsetFromServer = Duration.ofSeconds(20)

Duration tokenValidityDuration = Duration.ofSeconds(10);// 默认请求的Token过期时长
Boolean disableSslValidation = false;// https协议 是否禁用ssl验证
Duration httpTimeoutDuration = Duration.ofSeconds(10);// 协议请求、连接、读取、回写默认时长
String clientRequestId = LangUtils.getUppercaseUUID();// 客户端请求ID

/**
 * 构建API对象, 该对象建议全局单例, 如果调用不同的接口有不同的超时或其他的参数标准，可全局实例化多个
 */
PrivacyApi privacyApi = new PrivacyApiImpl(new OpenVisionTokenKeyApi(protocol, domain, port,
    new HttpClientParam(disableSslValidation, httpTimeoutDuration, httpTimeoutDuration, httpTimeoutDuration,
        httpTimeoutDuration),
    new TokenKey(accessKey, secretKey, tokenValidityDuration, timeOffsetFromServer)));

2.5 对象

2.5.1 当前支持的标签列表

2.5.2 UTCOffset对象

2.5.3 Attachment对象

2.5.4 SimpleDescribe对象

2.5.5 DetailedDescribe对象

2.5.6 Tag对象

3. 接口列表

3.1 获取每日摘要

3.1.1 Url

/vision-privacy-api/statistics/get/daily-summary

3.1.2 Header

3.1.3 Request Body

请求样例

{
  "deviceId":"1",
  "timestampOfStatisticsDate":1772432854000
}

字段描述

3.1.4 Response Body

如果该响应体返回值为null或者没有返回，那表示此数据不存在或者还没有完成日结统计

响应样例

{
    "code": 20000,
    "data": {
        "animalActivitySummary": "{\"person\": \"今天家中充满了温馨的日常互动：有人提着物品归家时小心翼翼，有人手持包裹似在准备惊喜，深夜时分的身影模糊却温暖，仿佛在默默为家人整理生活点滴。这些平凡的瞬间，串联成了家的幸福故事。\",\"pet\":\"猫咪在窝里安睡、静坐凝视前方，更在纸箱上欢快跳跃玩耍，展现着它活泼可爱的天性。,狗狗从早到晚都充满活力：嗅闻地面、在门口徘徊张望、趴着休息、来回走动，甚至玩起了拖拽行李箱的游戏。它时而专注整理物品，时而好奇地探头张望，是家中最活泼的成员。\"}",
        "sceneChangeSummary": "傍晚时分（约18点27分），有人从走廊走向电梯，仿佛结束一天的忙碌回到温暖的家。傍晚至晚间时段（19点至21点间），家人陆续从门内走出，或向右移动、或提着物品归家，为家中带来生机与欢笑。深夜21点41分，有人提着包轻声走过走廊，像是在守护家人安眠的静谧时刻。",
        "originalTimeline": "=== 2026-02-27 ===\n18:27:37: 人正从走廊走向电梯。\n19:05:08: 人从门内走出，向右移动。\n19:17:43: 人从门内走出\n19:44:07: 人从门内走出，向右移动。\n20:38:14: 人从门后走出，手持物品。\n21:11:38: 人从门内走出，手提物品。\n21:31:13: 人从门内走出，身影模糊。\n21:41:25: 人提着包走过走廊。"
    },
    "success": true,
    "clientRequestId":"332996B32A2746E99303DAD731592551",
    "serverResponseId": "7A2996B32A2746E99303DAD731592553",
    "name": "Ok",
    "message": "success",
    "elapsedTime": 280
}

响应对象字段描述

3.1.5 SDK使用方式

/**
 * 构建获取每日摘要请求参数，以下为测试数据，请根据实际情况变更
 */
GetDailySummaryRequest dailySummaryRequest = new GetDailySummaryRequest();
dailySummaryRequest.setDeviceId("001");// 设备id
dailySummaryRequest.setTimestampOfStatisticsDate(1772640000000L);// 当天的时间戳的开始毫秒 0时0分0秒

/**
 * 请求并返回消息
 */
Request<GetDailySummaryRequest> request = new Request<GetDailySummaryRequest>(clientRequestId,
    dailySummaryRequest);
Response<GetDailySummaryResponse> response = api.getDailySummary(request);

// 响应体
System.out.println(JSON.toJSONString(response));

// 如果该响应体返回值为null，表示发生错误或者还没有完成日结统计
System.out.println(JSON.toJSONString(response.getData()));

3.2 图片万物识别

3.2.1 Url

/vision-privacy-api/llm/image/rec-everything/v2

3.2.2 Header

3.2.3 Request Body

请求样例

{
    "customPrompt": null,
    "enableSystemPrompt": true,
    "eventTimeZone": {
        "hourOffset": 8,
        "minuteOffset": 0,
        "timeZone": "EASTERN_ZONE"
    },
    "eventTimestampStart": 1774246676515,
    "eventTimestampEnd": 1774246676515,
    "fromDeviceId": "001",
    "m3u8UrlAttachments": "https://hisign.com/index.m3u8",
    "responseLanguage": "zh",
    "standardAttachments": [
        {
            "id": "0CABCE2482B74C2BA4917977A871CDAB",
            "type": "OBJECT_URL",
            "value": "https://hisign.com/abc.jpg"
        }
    ],
    "systemPromptResponseType": "DETAILED_DESCRIBE"
}

请求对象字段描述

3.2.4 Response Body

响应样例

{
    "code": "20000",
    "data": {
        "customDescribe": "一名女性在客厅里看电视很高兴，两个孩子在客厅活动。",
        "detailedDescribe": {
            "scene": "一个大客厅",
            "tags": [
                {
                    "describe": "一名女性在看电视，两个在做游戏",
                    "name": "person"
                }
            ],
            "value": "一名女性和两个孩子在客厅活动。"
        },
        "simpleDescribe": {
            "tags": [
                "person"
            ],
            "value": "一名女性和两个孩子在客厅活动。"
        }
    },
    "elapsedTime": 100,
    "message": "success",
    "name": "Ok",
    "clientRequestId": "332996B32A2746E99303DAD731592551",
    "serverResponseId": "7A2996B32A2746E99303DAD731592553",
    "success": true
}

响应对象字段描述

3.2.5 SDK使用方式

/**
 * 构建万物识别请求参数
 */
RecEverythingRequest recEverythingRequest = new RecEverythingRequest();
// 自定义客户端请求ID
String clientRequestId = LangUtils.getUppercaseUUID();
// 来源设备id，必填，长度小于等于32个字符
recEverythingRequest.setFromDeviceId("001");
// 标准附件列表
recEverythingRequest
    .setStandardAttachments(Stream.of(new RecEverythingAttachment("0CABCE2482B74C2BA4917977A871CDAB",
        AttachmentType.OBJECT_URL, "https://hisign.com/abc.jpg")).collect(Collectors.toList()));
// m3u8附件列表
recEverythingRequest.setM3u8UrlAttachments("https://hisign.com/index.m3u8");
// 自定义提示词
recEverythingRequest.setCustomPrompt(null);
// 启用系统提示词
recEverythingRequest.setEnableSystemPrompt(true);
// 附件事件发生时间：注意实际情况不是当前时间
recEverythingRequest.setEventTimestampStart(System.currentTimeMillis());
recEverythingRequest.setEventTimestampEnd(System.currentTimeMillis());
// 附件事件发生时区：东八区
recEverythingRequest.setEventTimeZone(new UTCOffset(TimeZone.EASTERN_ZONE, 8, 0));
// 响应语言
recEverythingRequest.setResponseLanguage(Language.zh);
// 系统提示词响应的类型
recEverythingRequest.setSystemPromptResponseType(RecEverythingReponseType.DETAILED_DESCRIBE);

/**
 * 请求并返回消息
 */
Request<RecEverythingRequest> request = new Request<>(clientRequestId, recEverythingRequest);
Response<RecEverythingResponse> response = privacyApi.imageRecEverythingV2(request);

// 响应体
System.out.println(JSON.toJSONString(response));

// 如果该响应体返回值为null，表示发生错误，或无数据返回
System.out.println(JSON.toJSONString(response.getData()));

3.3 视频万物识别

3.3.1 Url

/vision-privacy-api/llm/video/rec-everything/v2

3.3.2 Header

3.3.3 Request Body

请求样例

{
    "customPrompt": null,
    "enableSystemPrompt": true,
    "eventTimeZone": {
        "hourOffset": 8,
        "minuteOffset": 0,
        "timeZone": "EASTERN_ZONE"
    },
    "eventTimestampStart": 1774246676515,
    "eventTimestampEnd": 1774246676515,
    "fromDeviceId": "001",
    "m3u8UrlAttachments": "https://hisign.com/index.m3u8",
    "responseLanguage": "zh",
    "standardAttachments": [
        {
            "id": "0CABCE2482B74C2BA4917977A871CDAB",
            "type": "OBJECT_URL",
            "value": "https://hisign.com/abc.jpg"
        }
    ],
    "systemPromptResponseType": "DETAILED_DESCRIBE"
}

请求对象字段描述

3.3.4 Response Body

响应样例

{
    "code": "20000",
    "data": {
        "customDescribe": "一名女性在客厅里看电视很高兴，两个孩子在客厅活动。",
        "detailedDescribe": {
            "scene": "一个大客厅",
            "tags": [
                {
                    "describe": "一名女性在看电视，两个在做游戏",
                    "name": "person"
                }
            ],
            "value": "一名女性和两个孩子在客厅活动。"
        },
        "simpleDescribe": {
            "tags": [
                "person"
            ],
            "value": "一名女性和两个孩子在客厅活动。"
        }
    },
    "elapsedTime": 100,
    "message": "success",
    "name": "Ok",
    "clientRequestId": "332996B32A2746E99303DAD731592551",
    "serverResponseId": "7A2996B32A2746E99303DAD731592553",
    "success": true
}

响应对象字段描述

3.3.5 SDK使用方式

/**
 * 构建万物识别请求参数
 */
RecEverythingRequest recEverythingRequest = new RecEverythingRequest();
// 自定义客户端请求ID
String clientRequestId = LangUtils.getUppercaseUUID();
// 来源设备id，必填，长度小于等于32个字符
recEverythingRequest.setFromDeviceId("001");
// 标准附件列表
recEverythingRequest
    .setStandardAttachments(Stream.of(new RecEverythingAttachment("0CABCE2482B74C2BA4917977A871CDAB",
        AttachmentType.OBJECT_URL, "https://hisign.com/abc.jpg")).collect(Collectors.toList()));
// m3u8附件列表
recEverythingRequest.setM3u8UrlAttachments("https://hisign.com/index.m3u8");
// 自定义提示词
recEverythingRequest.setCustomPrompt(null);
// 启用系统提示词
recEverythingRequest.setEnableSystemPrompt(true);
// 附件事件发生时间：注意实际情况不是当前时间
recEverythingRequest.setEventTimestampStart(System.currentTimeMillis());
recEverythingRequest.setEventTimestampEnd(System.currentTimeMillis());
// 附件事件发生时区：东八区
recEverythingRequest.setEventTimeZone(new UTCOffset(TimeZone.EASTERN_ZONE, 8, 0));
// 响应语言
recEverythingRequest.setResponseLanguage(Language.zh);
// 系统提示词响应的类型
recEverythingRequest.setSystemPromptResponseType(RecEverythingReponseType.DETAILED_DESCRIBE);

/**
 * 请求并返回消息
 */
Request<RecEverythingRequest> request = new Request<>(clientRequestId, recEverythingRequest);
Response<RecEverythingResponse> response = privacyApi.videoRecEverythingV2(request);

// 响应体
System.out.println(JSON.toJSONString(response));

// 如果该响应体返回值为null，表示发生错误，或无数据返回
System.out.println(JSON.toJSONString(response.getData()));