Object detection¶

POST /api/v5/detect/yolo

Performs object detection with a YOLO model on an image and returns the detections, including bounding box coordinates, classes, and confidences. You can also configure the model weights, input size, confidence threshold, and IoU threshold.

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint allows anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`Authorization`	header	string	Yes	User personal token used for authentication (not mandatory for anonymous access)

Request Body:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "description": "Name of the yolo11 model weight file; enum: `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-encoded image to detect (Data URL)",
      "type": "string",
      "examples": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQXXXXXXX"]
    },
    "imgsz": {
      "description": "Input image size; valid range is 32 to 1280 pixels",
      "type": "integer",
      "minimum": 32,
      "maximum": 1280,
      "examples": [640]
    },
    "conf": {
      "description": "Prediction confidence threshold; valid range is 0.01 to 1.0",
      "type": "number",
      "minimum": 0.01,
      "maximum": 1,
      "examples": [0.5]
    },
    "iou": {
      "description": "Intersection-over-union (IoU) threshold; valid range is 0.0 to 0.95",
      "type": "number",
      "minimum": 0,
      "maximum": 0.95,
      "examples": [0.45]
    }
  },
  "required": ["model", "source", "imgsz", "conf", "iou"]
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`images`	object[]	Yes	No	List of detection result images
`metadata`	object	Yes	No	Metadata information

`images` array item object¶

Field	Type	Always returned	Nullable	Description
`images[].results`	object[]	Yes	No	List of detections
`images[].shape`	integer[]	Yes	No	Image size `[width, height]`
`images[].speed`	object	Yes	No	Processing speed information

`images[].results` array item object¶

Field	Type	Always returned	Nullable	Description
`images[].results[].box`	object	Yes	No	Bounding box coordinates
`images[].results[].class`	integer	No	Yes	Class ID, for example `0`
`images[].results[].confidence`	number	Yes	No	Confidence, for example `0.83583`
`images[].results[].name`	string	Yes	No	Class name, for example `person`

`images[].results[].box` object¶

Field	Type	Always returned	Nullable	Description
`images[].results[].box.x1`	number	Yes	No	Top-left x coordinate, for example `14.55554`
`images[].results[].box.x2`	number	Yes	No	Bottom-right x coordinate, for example `72.45978`
`images[].results[].box.y1`	number	Yes	No	Top-left y coordinate, for example `116.72369`
`images[].results[].box.y2`	number	Yes	No	Bottom-right y coordinate, for example `268.92963`

`images[].speed` object¶

Field	Type	Always returned	Nullable	Description
`images[].speed.inference`	number	Yes	No	Inference time (ms), for example `56.13449`
`images[].speed.postprocess`	number	Yes	No	Post-processing time (ms), for example `0.05426`
`images[].speed.preprocess`	number	Yes	No	Pre-processing time (ms), for example `21.20275`

`metadata` object¶

Field	Type	Always returned	Nullable	Description
`metadata.functionTimeAlive`	number	No	Yes	Function alive time (ms), for example `163779.863`
`metadata.functionTimeCall`	number	No	Yes	Function call time (ms), for example `0.57`
`metadata.imageCount`	integer	No	Yes	Number of images, for example `1`
`metadata.model`	string	No	Yes	Model name, for example `yolo11n-cls.pt`
`metadata.version`	object	Yes	No	Version information

`metadata.version` object¶

Field	Type	Always returned	Nullable	Description
`metadata.version.python`	string	Yes	No	Python version, for example `3.11.14`
`metadata.version.torch`	string	No	Yes	PyTorch version, for example `2.9.1+cpu`
`metadata.version.torchvision`	string	No	Yes	torchvision version, for example `0.24.1+cpu`
`metadata.version.ultralytics`	string	Yes	No	ultralytics version, for example `8.3.228`

Error response¶

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "Parameter model cannot be empty"
}

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters or the request cannot be parsed
`401`	Authentication required (Requires authentication)
`403`	Access forbidden (Forbidden)
`500`	Internal system error

Request example¶

Parameter notes¶

Replace <token> with your AtomGit user access token (can be omitted for anonymous calls).

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¶

// Native fetch (Node.js 18+ / browsers)
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(`Request failed: ${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())

Response example¶

Status code: 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"
    }
  }
}

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`400`	Invalid parameters or the request cannot be parsed
`404`	Request path does not exist
`405`	Request method not supported
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc