You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
17 KiB
17 KiB
| comments | description | keywords |
|---|---|---|
| true | Learn how to run inference using the Ultralytics HUB Inference API. Includes examples in Python and cURL for quick integration. | Ultralytics, HUB, Inference API, Python, cURL, REST API, YOLO, image processing, machine learning, AI integration |
Ultralytics HUB Inference API
After you train a model, you can use the Shared Inference API for free. If you are a Pro user, you can access the Dedicated Inference API. The Ultralytics HUB Inference API allows you to run inference through our REST API without the need to install and set up the Ultralytics YOLO environment locally.
Watch: Ultralytics HUB Inference API Walkthrough
Dedicated Inference API
In response to high demand and widespread interest, we are thrilled to unveil the Ultralytics HUB Dedicated Inference API, offering single-click deployment in a dedicated environment for our Pro users!
!!! note
We are excited to offer this feature FREE during our public beta as part of the [Pro Plan](./pro.md), with paid tiers possible in the future.
- Global Coverage: Deployed across 38 regions worldwide, ensuring low-latency access from any location. See the full list of Google Cloud regions.
- Google Cloud Run-Backed: Backed by Google Cloud Run, providing infinitely scalable and highly reliable infrastructure.
- High Speed: Sub-100ms latency is possible for YOLOv8n inference at 640 resolution from nearby regions based on Ultralytics testing.
- Enhanced Security: Provides robust security features to protect your data and ensure compliance with industry standards. Learn more about Google Cloud security.
To use the Ultralytics HUB Dedicated Inference API, click on the Start Endpoint button. Next, use the unique endpoint URL as described in the guides below.
!!! tip
Choose the region with the lowest latency for the best performance as described in the [documentation](https://docs.ultralytics.com/reference/hub/google/__init__/).
To shut down the dedicated endpoint, click on the Stop Endpoint button.
Shared Inference API
To use the Ultralytics HUB Shared Inference API, follow the guides below.
Free users have the following usage limits:
- 100 calls / hour
- 1000 calls / month
Pro users have the following usage limits:
- 1000 calls / hour
- 10000 calls / month
Python
To access the Ultralytics HUB Inference API using Python, use the following code:
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
!!! note
Replace `MODEL_ID` with the desired model ID, `API_KEY` with your actual API key, and `path/to/image.jpg` with the path to the image you want to run inference on.
If you are using our [Dedicated Inference API](#dedicated-inference-api), replace the `url` as well.
cURL
To access the Ultralytics HUB Inference API using cURL, use the following code:
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
!!! note
Replace `MODEL_ID` with the desired model ID, `API_KEY` with your actual API key, and `path/to/image.jpg` with the path to the image you want to run inference on.
If you are using our [Dedicated Inference API](#dedicated-inference-api), replace the `url` as well.
Arguments
See the table below for a full list of available inference arguments.
| Argument | Default | Type | Description |
|---|---|---|---|
file |
file |
Image or video file to be used for inference. | |
imgsz |
640 |
int |
Size of the input image, valid range is 32 - 1280 pixels. |
conf |
0.25 |
float |
Confidence threshold for predictions, valid range 0.01 - 1.0. |
iou |
0.45 |
float |
Intersection over Union (IoU) threshold, valid range 0.0 - 0.95. |
Response
The Ultralytics HUB Inference API returns a JSON response.
Classification
!!! example "Classification Model"
=== "`ultralytics`"
```python
from ultralytics import YOLO
# Load model
model = YOLO("yolov8n-cls.pt")
# Run inference
results = model("image.jpg")
# Print image.jpg results in JSON format
print(results[0].tojson())
```
=== "cURL"
```bash
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
```
=== "Python"
```python
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "Response"
```json
{
"images": [
{
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92
}
],
"shape": [
750,
600
],
"speed": {
"inference": 200.8,
"postprocess": 0.8,
"preprocess": 2.8
}
}
],
"metadata": ...
}
```
Detection
!!! example "Detection Model"
=== "`ultralytics`"
```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())
```
=== "cURL"
```bash
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
```
=== "Python"
```python
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "Response"
```json
{
"images": [
{
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {
"x1": 118,
"x2": 416,
"y1": 112,
"y2": 660
}
}
],
"shape": [
750,
600
],
"speed": {
"inference": 200.8,
"postprocess": 0.8,
"preprocess": 2.8
}
}
],
"metadata": ...
}
```
OBB
!!! example "OBB Model"
=== "`ultralytics`"
```python
from ultralytics import YOLO
# Load model
model = YOLO("yolov8n-obb.pt")
# Run inference
results = model("image.jpg")
# Print image.jpg results in JSON format
print(results[0].tojson())
```
=== "cURL"
```bash
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
```
=== "Python"
```python
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "Response"
```json
{
"images": [
{
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {
"x1": 374.85565,
"x2": 392.31824,
"x3": 412.81805,
"x4": 395.35547,
"y1": 264.40704,
"y2": 267.45728,
"y3": 150.0966,
"y4": 147.04634
}
}
],
"shape": [
750,
600
],
"speed": {
"inference": 200.8,
"postprocess": 0.8,
"preprocess": 2.8
}
}
],
"metadata": ...
}
```
Segmentation
!!! example "Segmentation Model"
=== "`ultralytics`"
```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())
```
=== "cURL"
```bash
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
```
=== "Python"
```python
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "Response"
```json
{
"images": [
{
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {
"x1": 118,
"x2": 416,
"y1": 112,
"y2": 660
},
"segments": {
"x": [
266.015625,
266.015625,
258.984375,
...
],
"y": [
110.15625,
113.67188262939453,
120.70311737060547,
...
]
}
}
],
"shape": [
750,
600
],
"speed": {
"inference": 200.8,
"postprocess": 0.8,
"preprocess": 2.8
}
}
],
"metadata": ...
}
```
Pose
!!! example "Pose Model"
=== "`ultralytics`"
```python
from ultralytics import YOLO
# Load model
model = YOLO("yolov8n-pose.pt")
# Run inference
results = model("image.jpg")
# Print image.jpg results in JSON format
print(results[0].tojson())
```
=== "cURL"
```bash
curl -X POST "https://api.ultralytics.com/v1/predict/MODEL_ID" \
-H "x-api-key: API_KEY" \
-F "file=@/path/to/image.jpg" \
-F "imgsz=640" \
-F "conf=0.25" \
-F "iou=0.45"
```
=== "Python"
```python
import requests
# API URL, use actual MODEL_ID
url = "https://api.ultralytics.com/v1/predict/MODEL_ID"
# Headers, use actual API_KEY
headers = {"x-api-key": "API_KEY"}
# Inference arguments (optional)
data = {"imgsz": 640, "conf": 0.25, "iou": 0.45}
# Load image and send request
with open("path/to/image.jpg", "rb") as image_file:
files = {"file": image_file}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "Response"
```json
{
"images": [
{
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {
"x1": 118,
"x2": 416,
"y1": 112,
"y2": 660
},
"keypoints": {
"visible": [
0.9909399747848511,
0.8162999749183655,
0.9872099757194519,
...
],
"x": [
316.3871765136719,
315.9374694824219,
304.878173828125,
...
],
"y": [
156.4207763671875,
148.05775451660156,
144.93240356445312,
...
]
}
}
],
"shape": [
750,
600
],
"speed": {
"inference": 200.8,
"postprocess": 0.8,
"preprocess": 2.8
}
}
],
"metadata": ...
}
```