mirror of
https://github.com/THU-MIG/yolov10.git
synced 2025-05-24 06:14:55 +08:00
ddb354ce5e
Co-authored-by: Ayush Chaurasia <ayush.chaurarsia@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: 李际朝 <tubkninght@gmail.com> Co-authored-by: Danny Kim <imbird0312@gmail.com>
460 lines
14 KiB
Markdown
460 lines
14 KiB
Markdown
---
|
||
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:
|
||
|
||
```commandline
|
||
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.
|
||
|
||
| Argument | Default | Type | Notes |
|
||
|--------------|---------|---------|-----------------------------------------|
|
||
| `size` | `640` | `int` | allowable range is `32` - `1280` pixels |
|
||
| `confidence` | `0.25` | `float` | allowable range is `0.01` - `1.0` |
|
||
| `iou` | `0.45` | `float` | allowable range is `0.0` - `0.95` |
|
||
| `url` | `''` | `str` | |
|
||
| `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"
|
||
```commandline
|
||
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"
|
||
```commandline
|
||
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"
|
||
```commandline
|
||
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
|
||
...
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
``` |