VisionForge SDK使用教程04-AI打电话检测API调用说明文档

本文使用的是 VisionForge SDK，支持C#和Python的SDK调用，项目见
git开源地址：https://gitee.com/51diysoft/VisionForgeSDK，
支持常见的目标检测：火灾监测识别系统、垃圾监测识别系统、人脸识别、智慧工地监测系统：实时监控施工场景，头盔监测识别系统：头盔佩戴等，口罩识别；

1. 接口概述

本文档介绍AI打电话检测API的调用方法、参数说明、返回结果格式及使用示例。该API用于检测图片中的人员打电话行为，并返回检测结果。通过专用的打电话检测算法，能够在各种场景下实现高精度的打电话行为识别。

原始图片（图片来源于互联网）：

检测后结果：

多图合并检测效果：

2. API基本信息

• 接口URL: http://127.0.0.1:18001/api/ai/detect
• 请求方法: POST
• 请求类型: multipart/form-data
• 功能描述: 上传图片进行打电话检测
• 模型编码: 004callPhone

3. 请求参数

参数名	类型	必填	描述
file	file	是	要检测的图片文件，支持常见图片格式（JPG、PNG等）
model_code	string	是	模型编码，固定为 004callPhone

4. 返回结果格式说明

API返回JSON格式的数据，包含以下字段：

{
  "original_url": "原图访问URL",
  "detected_url": "检测结果图访问URL",
  "detections": [
    {
      "class": "目标类别",
      "class_id": 类别ID,
      "confidence": 置信度,
      "bbox": {
        "xmin": 左上角X坐标,
        "ymin": 左上角Y坐标,
        "xmax": 右下角X坐标,
        "ymax": 右下角Y坐标
      }
    }
  ],
  "image_size": {
    "width": 图片宽度,
    "height": 图片高度
  },
  "model_used": {
    "code": "004callPhone",
    "name": "打电话检测",
    "is_fallback": false
  },
  "message": "使用模型: 打电话检测 (004callPhone)"
}

字段含义解释

字段	中文含义	数据类型	说明
original_url	原图访问地址	字符串	服务器保存的原始图片访问URL
detected_url	检测结果图访问地址	字符串	带检测框的结果图片访问URL
detections	检测到的目标列表	数组	包含所有检测到的打电话人员信息
detections[0].class	目标类别名称	字符串	检测到的目标类型，值为callPhone（打电话）
detections[0].class_id	目标类别ID	整数	目标类别的数字标识符，打电话检测固定为0
detections[0].confidence	检测置信度	浮点数	目标检测的可信度，范围0-1，值越高越可靠
detections[0].bbox	边界框坐标	对象	打电话人员在图片中的位置信息
detections[0].bbox.xmin	左上角X坐标	浮点数	边界框左上角水平坐标
detections[0].bbox.ymin	左上角Y坐标	浮点数	边界框左上角垂直坐标
detections[0].bbox.xmax	右下角X坐标	浮点数	边界框右下角水平坐标
detections[0].bbox.ymax	右下角Y坐标	浮点数	边界框右下角垂直坐标
image_size	图片尺寸信息	对象	原始图片的尺寸信息
image_size.width	图片宽度	整数	图片的像素宽度
image_size.height	图片高度	整数	图片的像素高度
model_used	使用的模型信息	对象	包含模型编码、名称和是否为备选模型的信息
model_used.code	模型编码	字符串	当前使用的模型编码
model_used.name	模型名称	字符串	当前使用的模型名称
model_used.is_fallback	是否为备选模型	布尔值	指示是否使用了备选模型
message	提示信息	字符串	提供当前使用模型的提示信息

5. 错误响应格式

当请求失败时，API会返回HTTP状态码和错误信息：

{
  "detail": "错误信息描述"
}

常见错误码：

• 400 Bad Request: 无效的请求参数，如上传的文件不是图片
• 500 Internal Server Error: 服务器内部错误，如处理图片时发生异常

6. 调用示例

Python调用示例

import requests
import json
import os

# 图片文件路径
image_path = "E:\PyProject_yywl\01ultralytics-main-garbage\SDKDemo\CSharp\AiProjectCSharp\AiProjectCSharp\bin\Debug\TestImg\004打电话识别004callPhone\打电话1.jpg"

# API URL
url = "http://127.0.0.1:18001/api/ai/detect"

# 检查图片文件是否存在
if not os.path.exists(image_path):
    print(f"错误: 图片文件不存在 - {image_path}")
    exit(1)

print(f"正在上传图片: {image_path}")
print(f"目标API: {url}")
print(f"使用模型编码: 004callPhone")

# 准备文件数据
with open(image_path, 'rb') as f:
    files = {
        'file': (os.path.basename(image_path), f, 'image/jpeg')
    }
    
    # 表单数据，指定模型编码
    data = {
        'model_code': '004callPhone'
    }
    
    try:
        # 发送POST请求
        response = requests.post(url, files=files, data=data)
        
        # 检查响应状态
        response.raise_for_status()
        
        # 解析JSON响应
        result = response.json()
        
        # 打印检测结果
        print(f"\n检测结果:")
        print(f"原始图片URL: {result['original_url']}")
        print(f"检测结果URL: {result['detected_url']}")
        print(f"图片尺寸: {result['image_size']['width']}x{result['image_size']['height']}")
        print(f"使用模型: {result['model_used']['name']} ({result['model_used']['code']})")
        print(f"检测到的打电话人员数量: {len(result['detections'])}")
        
        # 打印检测到的打电话人员信息
        print("\n打电话人员信息:")
        for i, detection in enumerate(result['detections'], 1):
            print(f"\n人员 {i}:")
            print(f"  类别: {detection['class']}")
            print(f"  类别ID: {detection['class_id']}")
            print(f"  置信度: {detection['confidence']:.2f}")
            print(f"  位置: ({detection['bbox']['xmin']:.0f}, {detection['bbox']['ymin']:.0f}) - ({detection['bbox']['xmax']:.0f}, {detection['bbox']['ymax']:.0f})")
            print(f"  尺寸: 宽{detection['bbox']['xmax']-detection['bbox']['xmin']:.0f} × 高{detection['bbox']['ymax']-detection['bbox']['ymin']:.0f}")
    
    except requests.exceptions.RequestException as e:
        print(f"请求出错: {e}")
    except json.JSONDecodeError:
        print(f"警告: 无法解析响应为JSON，原始响应内容: {response.text}")
    except Exception as e:
        print(f"发生错误: {e}")

VisionForge SDK调用示例

使用提供的VisionForge SDK可以更方便地调用API：

from VisionForge_SDK_python import detect_and_save_result

# 打电话检测图片路径
callphone_image_path = r"E:\PyProject_yywl\01ultralytics-main-garbage\SDKDemo\CSharp\AiProjectCSharp\AiProjectCSharp\bin\Debug\TestImg\004打电话识别004callPhone\打电话1.jpg"

# 调用SDK进行检测并保存结果
detection_result = detect_and_save_result(callphone_image_path, model_code="004callPhone")

VisionForge SDK异步调用示例

使用VisionForge SDK的异步方法进行检测：

import asyncio
from VisionForge_SDK_python import detect_image, print_detection_result

async def run_callphone_detection():
    # 打电话检测图片路径
    callphone_image_path = r"E:\PyProject_yywl\01ultralytics-main-garbage\SDKDemo\CSharp\AiProjectCSharp\AiProjectCSharp\bin\Debug\TestImg\004打电话识别004callPhone\打电话1.jpg"
    
    # 使用异步方法检测打电话行为
    result = await detect_image(callphone_image_path, model_code="004callPhone")
    
    # 打印检测结果
    print_detection_result(result)

# 运行异步检测
asyncio.run(run_callphone_detection())

7. 返回结果示例解析

以下是一个实际打电话检测结果的中文解析：

{
  "original_url": "http://127.0.0.1:18001/uploads/20251023/source/9ff306309a5441d39062eb739971ae83.jpg",
  "detected_url": "http://127.0.0.1:18001/uploads/20251023/out/detected_9ff306309a5441d39062eb739971ae83.jpg",
  "detections": [
    {
      "class": "callPhone",
      "class_id": 0,
      "confidence": 0.98,
      "bbox": {
        "xmin": 435.0,
        "ymin": 295.0,
        "xmax": 491.0,
        "ymax": 351.0
      }
    }
  ],
  "image_size": {
    "width": 1920,
    "height": 1080
  },
  "model_used": {
    "code": "004callPhone",
    "name": "打电话检测",
    "is_fallback": false
  },
  "message": "使用模型: 打电话检测 (004callPhone)"
}

中文解析说明：

1. 图片信息：

   • 原始图片已保存并可通过URL访问
   • 带检测框的结果图片可通过URL访问
   • 图片尺寸为 1920×1080 像素

2. 检测到的目标：

   • 使用了专用的打电话检测模型(004callPhone)
   • 总共检测到1个打电话行为的人员

3. 打电话人员信息：

   • 类别：callPhone（打电话）
   • 类别ID：0
   • 置信度：98%（0.98）
   • 位置：左上角坐标(435, 295)，右下角坐标(491, 351)
   • 尺寸：宽56像素 × 高56像素

8. 注意事项

1. 图片大小不宜过大，建议控制在10MB以内以提高处理速度
2. 打电话检测算法对正面、清晰的人体姿态识别效果最佳
3. 在光线较暗或人体角度过大的情况下，检测准确率可能会下降
4. 模型返回的置信度值通常都在0.7以上，表示检测结果可靠性强
5. 为保证服务稳定性，请勿频繁发送大量请求
6. 服务器端会定期清理历史图片数据，请及时保存重要数据
7. 当检测到多个人员时，会返回所有检测到的打电话人员信息

9. 故障排查

如果遇到API调用问题，可以从以下几个方面排查：

1. 确认服务是否正常运行（检查端口18001是否被占用）
2. 验证API URL是否正确（包含/api前缀）
3. 检查图片文件格式是否支持
4. 确保正确设置了model_code参数为"004callPhone"
5. 查看服务器日志获取详细错误信息

10. VisionForge SDK使用说明

VisionForge SDK提供了更便捷的方式来调用AI检测API。SDK的主要功能包括：

1. upload_image_for_detection：上传图片并获取检测结果
2. print_detection_result：格式化打印检测结果
3. detect_and_save_result：检测图片并将结果保存到JSON文件
4. detect_image：异步检测图片并返回结果

使用SDK的优势：

• 简化了API调用过程
• 提供了错误处理和重试机制
• 自动保存检测结果到文件系统
• 格式化输出检测结果，便于查看
• 支持异步调用，提高效率

SDK中可以通过设置model_code参数为"004callPhone"来使用打电话检测模型。

11. 相关资料

您的关注就是我们前进的动力！一起学习进步！

VisionForgeSDK: VisionForge SDK 为用户提供新一代人工智能解决方案，释放数据的真正潜力；
1、火灾监测识别系统：可用于森林、厂区等防火区域；
2、垃圾监测识别系统：支持常见垃圾监测；
3、人脸轨迹提取系统：根据视频画面提取人员的时间活动轨迹，追踪目标；
4、智慧工地监测系统：实时监控施工场景，保障工人安全，提高管理效率；
5、头盔监测识别系统：头盔佩戴等
项目地址： https://gitee.com/51diysoft/VisionForgeSDK