目标检测¶

POST /api/v5/detect/yolo

该接口用于目标检测，使用 YOLO 模型对图片进行物体识别，识别图片中的物体并返回检测结果，包括边界框坐标、类别及置信度等信息，同时支持配置模型权重、输入尺寸、置信度阈值和交并比阈值等参数。

访问令牌支持说明¶

AtomGit 用户访问令牌（AtomGit user access tokens）

是否允许匿名访问¶

此接口允许匿名访问

请求参数¶

参数名	位置	类型	必填	说明
`Authorization`	header	string	是	用户个人令牌，可用于鉴权（匿名访问时不强制携带）

Request Body:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "description": "yolo11 模型权重文件名称，枚举：`yolo11n.pt` / `yolo11s.pt` / `yolo11m.pt` / `yolo11l.pt` / `yolo11x.pt`",
      "type": "string",
      "enum": ["yolo11n.pt", "yolo11s.pt", "yolo11m.pt", "yolo11l.pt", "yolo11x.pt"],
      "examples": ["yolo11n.pt"]
    },
    "source": {
      "description": "待检测图片 base64 编码字符串（Data URL）",
      "type": "string",
      "examples": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQXXXXXXX"]
    },
    "imgsz": {
      "description": "输入图像的尺寸，有效范围 32 ~ 1280 像素",
      "type": "integer",
      "minimum": 32,
      "maximum": 1280,
      "examples": [640]
    },
    "conf": {
      "description": "预测的置信度阈值，有效范围 0.01 ~ 1.0",
      "type": "number",
      "minimum": 0.01,
      "maximum": 1,
      "examples": [0.5]
    },
    "iou": {
      "description": "交并比（IoU）阈值，有效范围 0.0 ~ 0.95",
      "type": "number",
      "minimum": 0,
      "maximum": 0.95,
      "examples": [0.45]
    }
  },
  "required": ["model", "source", "imgsz", "conf", "iou"]
}

响应参数¶

字段	类型	必返	可为空	说明
`images`	object[]	是	否	检测结果图片列表
`metadata`	object	是	否	元数据信息

`images` 数组项对象¶

字段	类型	必返	可为空	说明
`images[].results`	object[]	是	否	检测结果列表
`images[].shape`	integer[]	是	否	图片尺寸 `[width, height]`
`images[].speed`	object	是	否	处理速度信息

`images[].results` 数组项对象¶

字段	类型	必返	可为空	说明
`images[].results[].box`	object	是	否	边界框坐标
`images[].results[].class`	integer	否	是	类别 ID，示例 `0`
`images[].results[].confidence`	number	是	否	置信度，示例 `0.83583`
`images[].results[].name`	string	是	否	类别名称，示例 `person`

`images[].results[].box` 对象¶

字段	类型	必返	可为空	说明
`images[].results[].box.x1`	number	是	否	左上角 x 坐标，示例 `14.55554`
`images[].results[].box.x2`	number	是	否	右下角 x 坐标，示例 `72.45978`
`images[].results[].box.y1`	number	是	否	左上角 y 坐标，示例 `116.72369`
`images[].results[].box.y2`	number	是	否	右下角 y 坐标，示例 `268.92963`

`images[].speed` 对象¶

字段	类型	必返	可为空	说明
`images[].speed.inference`	number	是	否	推理时间（ms），示例 `56.13449`
`images[].speed.postprocess`	number	是	否	后处理时间（ms），示例 `0.05426`
`images[].speed.preprocess`	number	是	否	预处理时间（ms），示例 `21.20275`

`metadata` 对象¶

字段	类型	必返	可为空	说明
`metadata.functionTimeAlive`	number	否	是	函数存活时间（ms），示例 `163779.863`
`metadata.functionTimeCall`	number	否	是	函数调用时间（ms），示例 `0.57`
`metadata.imageCount`	integer	否	是	图片数量，示例 `1`
`metadata.model`	string	否	是	模型名称，示例 `yolo11n-cls.pt`
`metadata.version`	object	是	否	版本信息

`metadata.version` 对象¶

字段	类型	必返	可为空	说明
`metadata.version.python`	string	是	否	Python 版本，示例 `3.11.14`
`metadata.version.torch`	string	否	是	PyTorch 版本，示例 `2.9.1+cpu`
`metadata.version.torchvision`	string	否	是	torchvision 版本，示例 `0.24.1+cpu`
`metadata.version.ultralytics`	string	是	否	ultralytics 版本，示例 `8.3.228`

失败响应¶

401 未认证

{
  "error": "unauthorized",
  "message": "缺少或无效的访问令牌"
}

400 参数错误

{
  "error": "invalid_request",
  "message": "参数 model 不能为空"
}

HTTP 响应状态码¶

状态码	说明
`200`	成功（OK）
`400`	参数错误或请求无法解析
`401`	需要认证（Requires authentication）
`403`	禁止访问（Forbidden）
`500`	系统内部错误

请求示例¶

参数说明¶

<token> 替换为你的 AtomGit 用户访问令牌（匿名调用时可省略）。

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/detect/yolo' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "model": "yolo11n.pt",
    "source": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQXXXXXXX",
    "imgsz": 640,
    "conf": 0.5,
    "iou": 0.45
  }'

JavaScript¶

// 原生 fetch (Node.js 18+ / 浏览器)
const response = await fetch("https://api.atomgit.com/api/v5/detect/yolo", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer <YOUR-TOKEN>",
  },
  body: JSON.stringify({
    model: "yolo11n.pt",
    source: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQXXXXXXX",
    imgsz: 640,
    conf: 0.5,
    iou: 0.45,
  }),
});

if (!response.ok) {
  throw new Error(`请求失败: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/detect/yolo",
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Bearer <YOUR-TOKEN>",
    },
    json={
        "model": "yolo11n.pt",
        "source": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQXXXXXXX",
        "imgsz": 640,
        "conf": 0.5,
        "iou": 0.45,
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

响应示例¶

状态码： 200

{
  "images": [
    {
      "results": [
        {
          "box": {
            "x1": 14.55554,
            "x2": 72.45978,
            "y1": 116.72369,
            "y2": 268.92963
          },
          "class": 0,
          "confidence": 0.83583,
          "name": "person"
        }
      ],
      "shape": [203, 320],
      "speed": {
        "inference": 56.13449,
        "postprocess": 0.05426,
        "preprocess": 21.20275
      }
    }
  ],
  "metadata": {
    "functionTimeAlive": 163779.863,
    "functionTimeCall": 0.57,
    "imageCount": 1,
    "model": "yolo11n-cls.pt",
    "version": {
      "python": "3.11.14",
      "torch": "2.9.1+cpu",
      "torchvision": "0.24.1+cpu",
      "ultralytics": "8.3.228"
    }
  }
}

错误码¶

错误码	说明
`401`	未认证或凭证无效（缺少/无效的访问凭证）
`400`	参数错误或请求无法解析
`404`	请求路径不存在
`405`	请求方法不支持
`429`	请求过于频繁，触发限流
`500`	系统内部错误

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 gitcode-dev/atomgit-api-doc