物联网开发平台接入指引

服务简介
TWeSee AI 视觉引擎是腾讯云物联网面向消费电子与泛安防行业推出的端到端智能视觉解决方案。产品基于腾讯自研的消费电子行业模型，通过深度场景化微调，为智能摄像头、智能门锁、宠物看护、老人陪护、儿童看护等终端设备提供从“看见”到“看懂”的深度内容理解能力。
更多产品介绍，请参见 服务介绍 文档。
方式一：通过云 API 接入
您可以通过云 API 调用 TWeSee 的视觉理解能力，并且从输出参数获得视觉理解结果。
前提条件
1. 开通 TWeSee 后付费服务：操作步骤详见 开通 TWeSee 后付费服务。此操作会产生费用，费用详情请参见 计费说明，或联系销售。
2. 准备待分析的视频文件或图片文件的 HTTP URL。
3. 在腾讯云控制台 > 访问管理 中，创建（或使用现有的）云 API 密钥用于调用云 API（需具备云 API iotexplorer:InvokeTWeSeeComprehension 的调用权限）。
步骤1：开通 TWeSee 后付费服务
您可以前往腾讯云控制台 > 云 API > API Explorer，通过调用云 API 的方式开通 TWeSee 后付费服务。视频理解与图片理解两种服务类型需分别开通。
视频理解
图片理解
1. 前往 API Explorer 的物联网开发平台 > TWeSee新版相关接口 > 开通 TWeSee 后付费服务 v2 在线调用页面。
2. 在“Region”下拉框中选择需开通服务的地域：目前支持“华南地区（广州） ap-guangzhou”以及“亚太东南（曼谷） ap-bangkok”。
3. 在“ServiceType”输入框中，填写 VID_COMP 表示开通视频理解。
4. 单击“发送请求”。
﻿
1. 前往 API Explorer 的物联网开发平台 > TWeSee新版相关接口 > 开通 TWeSee 后付费服务 v2 在线调用页面。
2. 在“Region”下拉框中选择需开通服务的地域：目前支持“华南地区（广州） ap-guangzhou”以及“亚太东南（曼谷） ap-bangkok”。
3. 在“ServiceType”输入框中，填写 IMG_COMP 表示开通图片理解。
4. 单击“发送请求”。
﻿
步骤2：调用视觉理解云 API
通过云 API 调用 TWeSee 视觉理解算法 （Action 名：InvokeTWeSeeComprehension）可调用 TWeSee 的视觉理解能力，并且从输出参数获得视觉理解结果。
注意：
通过云 API 开通 TWeSee 后付费服务后，按照下述步骤调用 TWeSee 功能，将会产生日结后付费费用，请谨慎使用。详情请参见 TWeSee 计费说明 文档。
输入参数
下面列出视觉理解 API 的关键参数。完整的参数列表详见 接口文档。
参数名
参数类型
参数说明与示例值
ServiceType
Int64
算法服务类型。支持传入的值：
VID_COMP：视频理解。
IMG_COMP：图片理解。
﻿
示例值：VID_COMP
InputURL
String
视频文件或图片文件的 HTTP URL。
视频理解：支持 MP4、FLV、M3U8 视频格式；支持 H.264、H.265 视频编码。
图片理解：支持 JPEG、PNG 图片格式。
﻿
示例值：https://example.com/video.mp4
ComprehensionConfig
﻿SeeComprehensionConfig﻿
视觉理解配置项。
ComprehensionConfig.DetectTypes
Array of String
可选，额外启用的目标检测、事件检测标签。支持的取值详见 数据结构 - SeeComprehensionConfig。
﻿
示例值：["crowd"]
ComprehensionConfig.EnableSearch
Boolean
使该视频录入搜索库，后续可进行搜索。仅当 ServiceType = VID_COMP 时可指定为 true。
﻿
注意：TWeSee 视觉理解后付费的视频搜索为高级功能，开启视频搜索将会产生视频理解高级功能的日结后付费费用。
﻿
示例值：true
输出参数
参数名
参数类型
参数说明与示例值
Status
String
任务状态。可能取值：
1：内部错误。
2：因输入文件读取失败导致无结果（此时可在 ComprehensionResult 字段取得错误码）。
3：已完成（此时可在 ComprehensionResult 字段取得结果）。
4：处理中。
﻿
示例值：3
CostBasic
Int64
完成该视觉理解任务所产生的基础功能次数用量。
﻿
示例值：1
CostAdvanced
Int64
完成该视觉理解任务所产生的高级功能次数用量。
﻿
示例值：1
ComprehensionResult
﻿SeeComprehensionResult﻿
视觉理解结果。（仅当 Status = 3 时有值）
ComprehensionResult.DetectedClassifications
Array of String
目标检测、事件检测匹配到的标签列表。可能取值详见 数据结构 - SeeComprehensionResult。
﻿
示例值：["person", "cat"]
ComprehensionResult.Summary
String
对输入的视频文件/图片文件内容的一句话描述。
﻿
示例值：一只猫坐在吉他盒里，旁边有只小鸟飞过。
调用示例
视频理解
图片理解
请求示例
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InvokeTWeSeeComprehension
<公共请求参数>
﻿
{
  "InputURL": "https://example.com/video.mp4",
  "ServiceType": "VID_COMP"
}
﻿
响应示例
﻿
{
  "Response": {
    "ComprehensionResult": {
      "DetectedClassifications": [
        "person"
      ],
      "Summary": "穿浅色衣物的人在湿滑路边行走"
    },
    "CostAdvanced": 0,
    "CostBasic": 1,
    "Status": 3,
    "TaskId": "comp-8c47f42e-c9fd-3e6a-a0c5-64da344c013d",
    "RequestId": "2d126014-5991-490d-8f4a-75991ad5871e"
  }
}
请求示例
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InvokeTWeSeeComprehension
<公共请求参数>
﻿
{
  "InputURL": "https://example.com/image.jpg",
  "ServiceType": "IMG_COMP"
}
﻿
响应示例
{
  "Response": {
    "ComprehensionResult": {
      "DetectedClassifications": [
        "cat"
      ],
      "Summary": "一只猫坐在吉他盒里，旁边有只小鸟飞过"
    },
    "CostAdvanced": 0,
    "CostBasic": 1,
    "Status": 3,
    "TaskId": "comp-12e89917-c932-c27d-977f-bd16cc5c3b92",
    "RequestId": "2063f9bf-ecad-499c-8f03-220c911385e9"
  }
}
通过 API Explorer 在线调用
您可以通过 API Explorer 在线调试 调用 TWeSee 视觉理解算法 接口，并获得相应的代码示例。
﻿
方式二：通过 IoT 云存接入
您可以为物联网开发平台音视频产品下的 IoT 设备开通 TWeSee 包月套餐（预付费计费模式）。开通订阅后，该设备的视频云存事件会自动触发 TWeSee 的视觉理解。设备所上传云存视频的分析结果，可通过云 API 查询 TWeSee 任务列表 查询。
前提条件
1. 已创建音视频产品下的设备，且该设备开通了视频云存服务。
2. 该设备可正常上传云存录像，并且可以上报云存事件。
3. 在 腾讯云控制台 > 访问管理 中，创建（或使用现有的）云 API 密钥用于调用云 API（需具备云 API iotexplorer:CreateTWeSeeSubscription 、iotexplorer:ModifyTWeSeeSubscription 以及 iotexplorer:ListTWeSeeTasks 的调用权限）。
注意：
未开通 IoT 云存服务的设备，无法通过 IoT 云存的方式接入 TWeSee 服务，也无法使用 TWeSee 包月套餐计费模式（预付费）。
步骤1：调用云 API 为设备开通 TWeSee 包月套餐
调用云 API 开通 TWeSee 预付费订阅 （Action 名：CreateTWeSeeSubscription）可以为指定设备开通 TWeSee 包月套餐。
参数说明
下面列出该 API 的关键参数。完整的参数列表详见 接口文档。
参数名
参数类型
参数说明与示例值
ProductId
String
产品 ID。
﻿
示例值：4AHMY9X89Y
DeviceName
String
设备名称。
﻿
示例值：dev002
ServiceType
String
算法服务类型。支持传入的值：
VID_COMP：视频理解。
﻿
示例值：VID_COMP
ServiceTier
String
套餐规格。支持传入的值：
BASIC：基础版。适用于视频理解。（当同时传入 ServiceType = VID_COMP 以及 ServiceTier = BASIC 时，表示开通视频理解基础版）
﻿
示例值：BASIC
Period
Int64
开通的月份数。允许的取值范围：1 ~ 60。
﻿
示例值：1
请求示例
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateTWeSeeSubscription
<公共请求参数>
﻿
{
  "ProductId": "4AHMY9X89Y",
  "DeviceName": "dev002",
  "ServiceType": "VID_COMP",
  "ServiceTier": "BASIC",
  "Period": 1
}
响应示例
﻿
{
  "Response": {
    "Currency": "CNY",
    "DiscountPrice": "****",
    "OrderId": "20260420*********550201",
    "OriginalPrice": "****",
    "ResourceId": "twesee-753yd29x30********jqww1",
    "Status": "DELIVERED",
    "RequestId": "6f7647ba-757c-439c-8781-c187b5a561f3"
  }
}
步骤2：调用云 API 为设备设置 TWeSee 视觉理解配置
调用云 API 修改 TWeSee 预付费订阅 （Action 名：ModifyTWeSeeSubscription）可以修改指定设备的 TWeSee 视觉理解功能配置。
参数说明
下面列出该 API 的关键参数。完整的参数列表，以及更多的请求示例，详见 接口文档。
参数名
参数类型
参数说明与示例值
ProductId
String
产品 ID。
﻿
示例值：4AHMY9X89Y
DeviceName
String
设备名称。
﻿
示例值：dev002
ServiceType
String
算法服务类型。支持传入的值：
VID_COMP：视频理解。
﻿
示例值：VID_COMP
ComprehensionConfig
﻿SeeComprehensionConfig﻿
视觉理解配置项。
ComprehensionConfig.DetectTypes
Array of String
可选，额外启用的目标检测、事件检测标签。支持的取值详见 数据结构 - SeeComprehensionConfig。
﻿
示例值：["crowd"]
ComprehensionConfig.EnableSearch
Boolean
使该视频录入搜索库，后续可进行搜索。仅当 ServiceType = VID_COMP 时可指定为 true。
﻿
示例值：true
请求示例
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyTWeSeeSubscription
<公共请求参数>
﻿
{
  "ProductId": "4AHMY9X89Y",
  "DeviceName": "dev002",
  "ServiceType": "VID_COMP",
  "ChannelId": 0,
  "ComprehensionConfig": {
    "DetectTypes": [
      "crowd"
    ]
  }
}
响应示例
{
  "Response": {
    "RequestId": "1b32234f-60bb-48dc-9791-2fffc690b035"
  }
}
步骤3：设备上传云存录像并且上报云存事件
开通订阅后，该设备上传到云端的视频云存事件会自动触发 TWeSee 的视觉理解。详见 云存接入指南。
说明：
云存事件需要成对上报“事件开始”和“事件结束”，TWeSee 将在“事件结束”上报时触发视觉理解任务。
步骤4：调用云 API 查询设备的云存事件视频分析结果列表
设备所上传云存视频的分析结果，可通过云 API 查询 TWeSee 任务列表 （Action 名：ListTWeSeeTasks）查询。
参数说明
下面列出该 API 的关键参数。完整的参数列表，以及更多的请求示例，详见 接口文档。
参数名
参数类型
参数说明与示例值
ProductId
String
产品 ID。
﻿
示例值：4AHMY9X89Y
DeviceName
String
设备名称。
﻿
示例值：dev002
ServiceCategory
String
算法服务大类。支持传入的值：
COMPREHENSION：视觉理解（包含视频理解以及图片理解）。
﻿
示例值：COMPREHENSION
Offset
Int64
分页偏移量。
﻿
示例值：0
Limit
Int64
分页页长。
﻿
示例值：10
请求示例
﻿
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ListTWeSeeTasks
<公共请求参数>
﻿
{
  "ProductId": "4AHMY9X89Y",
  "DeviceName": "dev002",
  "ServiceCategory": "COMPREHENSION",
  "Limit": 10,
  "Offset": 0
}
响应示例
{
  "Response": {
    "Tasks": [
      {
        "ComprehensionResult": {
          "DetectedClassifications": [
            "person"
          ],
          "Summary": "穿白色衣裤的人在湿滑的人行道上行走"
        },
        "CostAdvanced": 0,
        "CostBasic": 2,
        "CreateTime": 1776629116,
        "Files": [],
        "FilesInfo": [],
        "Metadata": {
          "ChannelId": 0,
          "CustomId": "_sys_id1_data",
          "DeviceName": "dev002",
          "EndTimeMs": 1776629110000,
          "ProductId": "4AHMY9X89Y",
          "StartTimeMs": 1776629102000
        },
        "ServiceCategory": "COMPREHENSION",
        "ServiceTier": "BASIC",
        "ServiceType": "VID_COMP",
        "Status": 3,
        "TaskId": "comp-d57939bb-b155-5623-c7e7-1fb8dd0654dd",
        "UpdateTime": 1776629119
      }
    ],
    "Total": 1,
    "RequestId": "5e24e488-7948-4ff6-9bd1-76eb3a0cd112"
  }
}
使用自然语言搜索视频
设备的视觉理解配置中，若配置了 EnableSearch 为 true，则后续设备触发了 TWeSee 视频理解的视频可通过云 API 视频语义搜索 （Action 名：InvokeAISearchService）输入自然语言进行检索。
参数说明
下面列出该 API 的关键参数。完整的参数列表，以及更多的请求示例，详见 接口文档。
参数名
参数类型
参数说明与示例值
ProductId
String
产品 ID。
﻿
示例值：4AHMY9X89Y
DeviceName
String
设备名称。
﻿
示例值：dev002
Query
String
自然语言查询
﻿
示例值：穿黑色衣服的人
请求示例
﻿
POST / HTTP/1.1
Host: iotexplorer.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InvokeAISearchService
<公共请求参数>
﻿
{
  "ProductId": "4AHMY9X89Y",
  "DeviceName": "dev001",
  "Query": "有人走过"
}
响应示例
﻿
{
  "Response": {
    "Summary": "共1段视频：雨后路滑，浅色路人正小心行走。安全起见，请防滑慢行哦！",
    "Targets": [
      {
        "ChannelId": 0,
        "DeviceName": "dev001",
        "EndTimeMs": 1777357077918,
        "EventId": "_sys_id1_data",
        "Id": "019dd2bc-****-****-acd3-b7e88473c32d_1",
        "ProductId": "4AHMY9X89Y",
        "StartTimeMs": 1777357076918,
        "Summary": "穿浅色衣物的人在雨后湿滑的路边行走",
        "Thumbnail": "/1000*****/*****.jpg"
      }
    ],
    "VideoURL": "https://125********.vod2.myqcloud.com/timeshift/live/***/timeshift.m3u8",
    "RequestId": "5485cc1a-5c7a-4d86-98f9-da7bba179f6c"
  }
}
使用智能视觉服务（TWeSee）的特别说明
1. 本服务不得用于未经授权的大规模人群监控、侵犯个人隐私等违规用途。
2. 使用智能视觉服务（TWeSee）时，您应：
2.1 遵守《互联网信息服务深度合成管理规定》、《生成式人工智能服务管理暂行办法》等相关法律法规。
2.2 对 AI 生成的内容（如视频摘要、图片描述等）进行显著标识。
2.3 确保使用本服务处理的数据已获得相关主体的合法授权。
2.4 不得利用本服务生成违反法律法规或侵犯第三方合法权益的内容。
2.5 智能视觉服务（TWeSee）提供的视频理解、图片理解等功能，基于人工智能技术实现。我们致力于提供安全、稳定、持续的服务，以保障您的正常使用，但由于大模型技术发展的局限性，我们无法完全保证：
2.5.1 本服务或算法模型将符合您的实际或特定需求或目的；
2.5.2 本服务或算法模型百分百准确可靠、功能可用、持续稳定、不存在故障；
3. AI 生成的内容（包括但不限于视频摘要、图片描述、事件检测结果等）仅供参考，实际结果可能因场景复杂性、数据质量、环境因素等原因而存在偏差。您不应将 AI 识别结果作为唯一决策依据，尤其是在涉及人身安全、财产保护等重要场景时，请结合其他方式进行验证。

参数名	参数类型	参数说明与示例值
ServiceType	Int64	算法服务类型。支持传入的值： VID_COMP：视频理解。 IMG_COMP：图片理解。示例值：VID_COMP
InputURL	String	视频文件或图片文件的 HTTP URL。视频理解：支持 MP4、FLV、M3U8 视频格式；支持 H.264、H.265 视频编码。图片理解：支持 JPEG、PNG 图片格式。示例值：https://example.com/video.mp4
ComprehensionConfig	SeeComprehensionConfig	视觉理解配置项。
ComprehensionConfig.DetectTypes	Array of String	可选，额外启用的目标检测、事件检测标签。支持的取值详见数据结构 - SeeComprehensionConfig。示例值：["crowd"]
ComprehensionConfig.EnableSearch	Boolean	使该视频录入搜索库，后续可进行搜索。仅当 ServiceType = VID_COMP 时可指定为 true。注意：TWeSee 视觉理解后付费的视频搜索为高级功能，开启视频搜索将会产生视频理解高级功能的日结后付费费用。示例值：true

接入指引

本页目录：

服务简介

方式一：通过云 API 接入

前提条件

步骤1：开通 TWeSee 后付费服务

步骤2：调用视觉理解云 API

输入参数

输出参数

调用示例

通过 API Explorer 在线调用

方式二：通过 IoT 云存接入

前提条件

步骤1：调用云 API 为设备开通 TWeSee 包月套餐

参数说明

请求示例

响应示例

步骤2：调用云 API 为设备设置 TWeSee 视觉理解配置

参数说明

请求示例

响应示例

步骤3：设备上传云存录像并且上报云存事件

步骤4：调用云 API 查询设备的云存事件视频分析结果列表

参数说明

请求示例

响应示例

使用自然语言搜索视频

参数说明

请求示例

响应示例

使用智能视觉服务（TWeSee）的特别说明