一、导读
工业视觉项目中，TVA 视觉智能体是目前自动化质检、视觉定位场景的主流落地方案。API 接口是打通智能体、上位机、机械手、MES 系统的唯一桥梁。 很多刚入行的开发者上手就直接调用接口，因不了解整体架构、鉴权规则、接口分类，导致调试效率极低。本文结合私有化项目实战经验，从零拆解 TVA 视觉智能体全套 API 体系，划分接口集群、详解通用规则与鉴权逻辑，帮你建立完整的接口知识体系。
二、TVA 视觉智能体 API 整体架构（核心知识点）
TVA 官方对外 API 基于 HTTP/HTTPS 协议设计，按照业务流转顺序可划分为四大核心接口集群，覆盖视觉业务全生命周期：
💡 重点提醒：对外公开 API 仅开放业务能力，后台深度配置接口属于私有接口，后文会单独讲解适配方案。
三、通用请求规范与公共参数（必掌握）
3.1 基础访问地址格式
私有化部署通用地址模板：
plaintext
http://{TVA服务IP}:{端口}/tva/vision/api/{接口路由}
示例：http://192.168.1.88:8090/tva/vision/api/detect/object
3.2 全局公共请求头（所有接口通用）
表格
| Authorization | 身份鉴权 Token | 是 |
| Content-Type | 数据格式，固定application/json | 是 |
| Device-Id | 视觉点位 / 相机唯一编码 | 是 |
| Timestamp | 时间戳，防请求篡改 | 可选（私有化内网建议开启） |
3.3 统一返回数据格式
所有接口返回标准 JSON 结构，字段含义固定：
- code：状态码，200 = 成功，非 200 = 异常
- msg：状态描述信息
- data：业务返回数据体
四、Token 鉴权机制详解
TVA 视觉智能体采用登录获取 Token + 全局令牌鉴权模式，流程如下：
📌 实战踩坑点：现场调试 80% 的接口报错，根源都是 Token 失效、未携带 Device-Id。
