|
|
---
|
|
|
comments: true
|
|
|
---
|
|
|
|
|
|
# 🚧 Page Under Construction ⚒
|
|
|
|
|
|
This page is currently under construction!️ 👷Please check back later for updates. 😃🔜
|
|
|
|
|
|
|
|
|
# YOLO Inference API
|
|
|
|
|
|
The YOLO Inference API allows you to access the YOLOv8 object detection capabilities via a RESTful API. This enables you to run object detection on images without the need to install and set up the YOLOv8 environment locally.
|
|
|
|
|
|
## API URL
|
|
|
|
|
|
The API URL is the address used to access the YOLO Inference API. In this case, the base URL is:
|
|
|
|
|
|
```
|
|
|
https://api.ultralytics.com/v1/predict
|
|
|
```
|
|
|
|
|
|
## Example Usage in Python
|
|
|
|
|
|
To access the YOLO Inference API with the specified model and API key using Python, you can use the following code:
|
|
|
|
|
|
```python
|
|
|
import requests
|
|
|
|
|
|
# API URL, use actual MODEL_ID
|
|
|
url = f"https://api.ultralytics.com/v1/predict/MODEL_ID"
|
|
|
|
|
|
# Headers, use actual API_KEY
|
|
|
headers = {"x-api-key": "API_KEY"}
|
|
|
|
|
|
# Inference arguments (optional)
|
|
|
data = {"size": 640, "confidence": 0.25, "iou": 0.45}
|
|
|
|
|
|
# Load image and send request
|
|
|
with open("path/to/image.jpg", "rb") as image_file:
|
|
|
files = {"image": image_file}
|
|
|
response = requests.post(url, headers=headers, files=files, data=data)
|
|
|
|
|
|
print(response.json())
|
|
|
```
|
|
|
|
|
|
In this example, replace `API_KEY` with your actual API key, `MODEL_ID` with the desired model ID, and `path/to/image.jpg` with the path to the image you want to analyze.
|
|
|
|
|
|
|
|
|
## Example Usage with CLI
|
|
|
|
|
|
You can use the YOLO Inference API with the command-line interface (CLI) by utilizing the `curl` command. Replace `API_KEY` with your actual API key, `MODEL_ID` with the desired model ID, and `image.jpg` with the path to the image you want to analyze:
|
|
|
|
|
|
```bash
|
|
|
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
|
|
|
-H "x-api-key: API_KEY" \
|
|
|
-F "image=@/path/to/image.jpg" \
|
|
|
-F "size=640" \
|
|
|
-F "confidence=0.25" \
|
|
|
-F "iou=0.45"
|
|
|
```
|
|
|
|
|
|
## Passing Arguments
|
|
|
|
|
|
This command sends a POST request to the YOLO Inference API with the specified `MODEL_ID` in the URL and the `API_KEY` in the request `headers`, along with the image file specified by `@path/to/image.jpg`.
|
|
|
|
|
|
Here's an example of passing the `size`, `confidence`, and `iou` arguments via the API URL using the `requests` library in Python:
|
|
|
|
|
|
```python
|
|
|
import requests
|
|
|
|
|
|
# API URL, use actual MODEL_ID
|
|
|
url = f"https://api.ultralytics.com/v1/predict/MODEL_ID"
|
|
|
|
|
|
# Headers, use actual API_KEY
|
|
|
headers = {"x-api-key": "API_KEY"}
|
|
|
|
|
|
# Inference arguments (optional)
|
|
|
data = {"size": 640, "confidence": 0.25, "iou": 0.45}
|
|
|
|
|
|
# Load image and send request
|
|
|
with open("path/to/image.jpg", "rb") as image_file:
|
|
|
files = {"image": image_file}
|
|
|
response = requests.post(url, headers=headers, files=files, data=data)
|
|
|
|
|
|
print(response.json())
|
|
|
```
|
|
|
|
|
|
In this example, the `data` dictionary contains the query arguments `size`, `confidence`, and `iou`, which tells the API to run inference at image size 640 with confidence and IoU thresholds of 0.25 and 0.45.
|
|
|
|
|
|
This will send the query parameters along with the file in the POST request. See the table below for a full list of available inference arguments.
|
|
|
|
|
|
| Inference Argument | Default | Type | Notes |
|
|
|
|--------------------|---------|---------|------------------------------------------------|
|
|
|
| `size` | `640` | `int` | valid range is `32` - `1280` pixels |
|
|
|
| `confidence` | `0.25` | `float` | valid range is `0.01` - `1.0` |
|
|
|
| `iou` | `0.45` | `float` | valid range is `0.0` - `0.95` |
|
|
|
| `url` | `''` | `str` | optional image URL if not image file is passed |
|
|
|
| `normalize` | `False` | `bool` | |
|
|
|
|
|
|
## Return JSON format
|
|
|
|
|
|
The YOLO Inference API returns a JSON list with the detection results. The format of the JSON list will be the same as the one produced locally by the `results[0].tojson()` command.
|
|
|
|
|
|
The JSON list contains information about the detected objects, their coordinates, classes, and confidence scores.
|
|
|
|
|
|
### Detect Model Format
|
|
|
|
|
|
YOLO detection models, such as `yolov8n.pt`, can return JSON responses from local inference, CLI API inference, and Python API inference. All of these methods produce the same JSON response format.
|
|
|
|
|
|
!!! example "Detect Model JSON Response"
|
|
|
|
|
|
=== "Local"
|
|
|
```python
|
|
|
from ultralytics import YOLO
|
|
|
|
|
|
# Load model
|
|
|
model = YOLO('yolov8n.pt')
|
|
|
|
|
|
# Run inference
|
|
|
results = model('image.jpg')
|
|
|
|
|
|
# Print image.jpg results in JSON format
|
|
|
print(results[0].tojson())
|
|
|
```
|
|
|
|
|
|
=== "CLI API"
|
|
|
```bash
|
|
|
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
|
|
|
-H "x-api-key: API_KEY" \
|
|
|
-F "image=@/path/to/image.jpg" \
|
|
|
-F "size=640" \
|
|
|
-F "confidence=0.25" \
|
|
|
-F "iou=0.45"
|
|
|
```
|
|
|
|
|
|
=== "Python API"
|
|
|
```python
|
|
|
import requests
|
|
|
|
|
|
# API URL, use actual MODEL_ID
|
|
|
url = f"https://api.ultralytics.com/v1/predict/MODEL_ID"
|
|
|
|
|
|
# Headers, use actual API_KEY
|
|
|
headers = {"x-api-key": "API_KEY"}
|
|
|
|
|
|
# Inference arguments (optional)
|
|
|
data = {"size": 640, "confidence": 0.25, "iou": 0.45}
|
|
|
|
|
|
# Load image and send request
|
|
|
with open("path/to/image.jpg", "rb") as image_file:
|
|
|
files = {"image": image_file}
|
|
|
response = requests.post(url, headers=headers, files=files, data=data)
|
|
|
|
|
|
print(response.json())
|
|
|
```
|
|
|
|
|
|
=== "JSON Response"
|
|
|
```json
|
|
|
{
|
|
|
"success": True,
|
|
|
"message": "Inference complete.",
|
|
|
"data": [
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.8359682559967041,
|
|
|
"box": {
|
|
|
"x1": 0.08974208831787109,
|
|
|
"y1": 0.27418340047200523,
|
|
|
"x2": 0.8706787109375,
|
|
|
"y2": 0.9887352837456598
|
|
|
}
|
|
|
},
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.8189555406570435,
|
|
|
"box": {
|
|
|
"x1": 0.5847355842590332,
|
|
|
"y1": 0.05813225640190972,
|
|
|
"x2": 0.8930277824401855,
|
|
|
"y2": 0.9903111775716146
|
|
|
}
|
|
|
},
|
|
|
{
|
|
|
"name": "tie",
|
|
|
"class": 27,
|
|
|
"confidence": 0.2909725308418274,
|
|
|
"box": {
|
|
|
"x1": 0.3433395862579346,
|
|
|
"y1": 0.6070465511745877,
|
|
|
"x2": 0.40964522361755373,
|
|
|
"y2": 0.9849439832899306
|
|
|
}
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### Segment Model Format
|
|
|
|
|
|
YOLO segmentation models, such as `yolov8n-seg.pt`, can return JSON responses from local inference, CLI API inference, and Python API inference. All of these methods produce the same JSON response format.
|
|
|
|
|
|
!!! example "Segment Model JSON Response"
|
|
|
|
|
|
=== "Local"
|
|
|
```python
|
|
|
from ultralytics import YOLO
|
|
|
|
|
|
# Load model
|
|
|
model = YOLO('yolov8n-seg.pt')
|
|
|
|
|
|
# Run inference
|
|
|
results = model('image.jpg')
|
|
|
|
|
|
# Print image.jpg results in JSON format
|
|
|
print(results[0].tojson())
|
|
|
```
|
|
|
|
|
|
=== "CLI API"
|
|
|
```bash
|
|
|
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
|
|
|
-H "x-api-key: API_KEY" \
|
|
|
-F "image=@/path/to/image.jpg" \
|
|
|
-F "size=640" \
|
|
|
-F "confidence=0.25" \
|
|
|
-F "iou=0.45"
|
|
|
```
|
|
|
|
|
|
=== "Python API"
|
|
|
```python
|
|
|
import requests
|
|
|
|
|
|
# API URL, use actual MODEL_ID
|
|
|
url = f"https://api.ultralytics.com/v1/predict/MODEL_ID"
|
|
|
|
|
|
# Headers, use actual API_KEY
|
|
|
headers = {"x-api-key": "API_KEY"}
|
|
|
|
|
|
# Inference arguments (optional)
|
|
|
data = {"size": 640, "confidence": 0.25, "iou": 0.45}
|
|
|
|
|
|
# Load image and send request
|
|
|
with open("path/to/image.jpg", "rb") as image_file:
|
|
|
files = {"image": image_file}
|
|
|
response = requests.post(url, headers=headers, files=files, data=data)
|
|
|
|
|
|
print(response.json())
|
|
|
```
|
|
|
|
|
|
=== "JSON Response"
|
|
|
Note `segments` `x` and `y` lengths may vary from one object to another. Larger or more complex objects may have more segment points.
|
|
|
```json
|
|
|
{
|
|
|
"success": True,
|
|
|
"message": "Inference complete.",
|
|
|
"data": [
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.856913149356842,
|
|
|
"box": {
|
|
|
"x1": 0.1064866065979004,
|
|
|
"y1": 0.2798851860894097,
|
|
|
"x2": 0.8738358497619629,
|
|
|
"y2": 0.9894873725043403
|
|
|
},
|
|
|
"segments": {
|
|
|
"x": [
|
|
|
0.421875,
|
|
|
0.4203124940395355,
|
|
|
0.41718751192092896
|
|
|
...
|
|
|
],
|
|
|
"y": [
|
|
|
0.2888889014720917,
|
|
|
0.2916666567325592,
|
|
|
0.2916666567325592
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
},
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.8512625694274902,
|
|
|
"box": {
|
|
|
"x1": 0.5757311820983887,
|
|
|
"y1": 0.053943040635850696,
|
|
|
"x2": 0.8960096359252929,
|
|
|
"y2": 0.985154045952691
|
|
|
},
|
|
|
"segments": {
|
|
|
"x": [
|
|
|
0.7515624761581421,
|
|
|
0.75,
|
|
|
0.7437499761581421
|
|
|
...
|
|
|
],
|
|
|
"y": [
|
|
|
0.0555555559694767,
|
|
|
0.05833333358168602,
|
|
|
0.05833333358168602
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
},
|
|
|
{
|
|
|
"name": "tie",
|
|
|
"class": 27,
|
|
|
"confidence": 0.6485961675643921,
|
|
|
"box": {
|
|
|
"x1": 0.33911995887756347,
|
|
|
"y1": 0.6057066175672743,
|
|
|
"x2": 0.4081430912017822,
|
|
|
"y2": 0.9916408962673611
|
|
|
},
|
|
|
"segments": {
|
|
|
"x": [
|
|
|
0.37187498807907104,
|
|
|
0.37031251192092896,
|
|
|
0.3687500059604645
|
|
|
...
|
|
|
],
|
|
|
"y": [
|
|
|
0.6111111044883728,
|
|
|
0.6138888597488403,
|
|
|
0.6138888597488403
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
### Pose Model Format
|
|
|
|
|
|
YOLO pose models, such as `yolov8n-pose.pt`, can return JSON responses from local inference, CLI API inference, and Python API inference. All of these methods produce the same JSON response format.
|
|
|
|
|
|
!!! example "Pose Model JSON Response"
|
|
|
|
|
|
=== "Local"
|
|
|
```python
|
|
|
from ultralytics import YOLO
|
|
|
|
|
|
# Load model
|
|
|
model = YOLO('yolov8n-seg.pt')
|
|
|
|
|
|
# Run inference
|
|
|
results = model('image.jpg')
|
|
|
|
|
|
# Print image.jpg results in JSON format
|
|
|
print(results[0].tojson())
|
|
|
```
|
|
|
|
|
|
=== "CLI API"
|
|
|
```bash
|
|
|
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
|
|
|
-H "x-api-key: API_KEY" \
|
|
|
-F "image=@/path/to/image.jpg" \
|
|
|
-F "size=640" \
|
|
|
-F "confidence=0.25" \
|
|
|
-F "iou=0.45"
|
|
|
```
|
|
|
|
|
|
=== "Python API"
|
|
|
```python
|
|
|
import requests
|
|
|
|
|
|
# API URL, use actual MODEL_ID
|
|
|
url = f"https://api.ultralytics.com/v1/predict/MODEL_ID"
|
|
|
|
|
|
# Headers, use actual API_KEY
|
|
|
headers = {"x-api-key": "API_KEY"}
|
|
|
|
|
|
# Inference arguments (optional)
|
|
|
data = {"size": 640, "confidence": 0.25, "iou": 0.45}
|
|
|
|
|
|
# Load image and send request
|
|
|
with open("path/to/image.jpg", "rb") as image_file:
|
|
|
files = {"image": image_file}
|
|
|
response = requests.post(url, headers=headers, files=files, data=data)
|
|
|
|
|
|
print(response.json())
|
|
|
```
|
|
|
|
|
|
=== "JSON Response"
|
|
|
Note COCO-keypoints pretrained models will have 17 human keypoints. The `visible` part of the keypoints indicates whether a keypoint is visible or obscured. Obscured keypoints may be outside the image or may not be visible, i.e. a person's eyes facing away from the camera.
|
|
|
```json
|
|
|
{
|
|
|
"success": True,
|
|
|
"message": "Inference complete.",
|
|
|
"data": [
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.8439509868621826,
|
|
|
"box": {
|
|
|
"x1": 0.1125,
|
|
|
"y1": 0.28194444444444444,
|
|
|
"x2": 0.7953125,
|
|
|
"y2": 0.9902777777777778
|
|
|
},
|
|
|
"keypoints": {
|
|
|
"x": [
|
|
|
0.5058594942092896,
|
|
|
0.5103894472122192,
|
|
|
0.4920862317085266
|
|
|
...
|
|
|
],
|
|
|
"y": [
|
|
|
0.48964157700538635,
|
|
|
0.4643048942089081,
|
|
|
0.4465252459049225
|
|
|
...
|
|
|
],
|
|
|
"visible": [
|
|
|
0.8726999163627625,
|
|
|
0.653947651386261,
|
|
|
0.9130823612213135
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
},
|
|
|
{
|
|
|
"name": "person",
|
|
|
"class": 0,
|
|
|
"confidence": 0.7474289536476135,
|
|
|
"box": {
|
|
|
"x1": 0.58125,
|
|
|
"y1": 0.0625,
|
|
|
"x2": 0.8859375,
|
|
|
"y2": 0.9888888888888889
|
|
|
},
|
|
|
"keypoints": {
|
|
|
"x": [
|
|
|
0.778544008731842,
|
|
|
0.7976160049438477,
|
|
|
0.7530890107154846
|
|
|
...
|
|
|
],
|
|
|
"y": [
|
|
|
0.27595141530036926,
|
|
|
0.2378823608160019,
|
|
|
0.23644638061523438
|
|
|
...
|
|
|
],
|
|
|
"visible": [
|
|
|
0.8900790810585022,
|
|
|
0.789978563785553,
|
|
|
0.8974530100822449
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
``` |
