mirror of
https://github.com/blakeblackshear/frigate.git
synced 2026-02-09 04:35:25 +03:00
reorganize api docs into sections
This commit is contained in:
Nicolas Mowen
parent
ed99be0856
commit
9a46cf8a49
@ -5,45 +5,15 @@ title: HTTP API
|
|||||||
|
|
||||||
A web server is available on port 5000 with the following endpoints.
|
A web server is available on port 5000 with the following endpoints.
|
||||||
|
|
||||||
### `GET /api/<camera_name>`
|
## Management & Information
|
||||||
|
|
||||||
An mjpeg stream for debugging. Keep in mind the mjpeg endpoint is for debugging only and will put additional load on the system when in use.
|
### `GET /api/config`
|
||||||
|
|
||||||
Accepts the following query string parameters:
|
A json representation of your configuration
|
||||||
|
|
||||||
| param | Type | Description |
|
### `POST /api/restart`
|
||||||
| ----------- | ---- | ------------------------------------------------------------------ |
|
|
||||||
| `fps` | int | Frame rate |
|
|
||||||
| `h` | int | Height in pixels |
|
|
||||||
| `bbox` | int | Show bounding boxes for detected objects (0 or 1) |
|
|
||||||
| `timestamp` | int | Print the timestamp in the upper left (0 or 1) |
|
|
||||||
| `zones` | int | Draw the zones on the image (0 or 1) |
|
|
||||||
| `mask` | int | Overlay the mask on the image (0 or 1) |
|
|
||||||
| `motion` | int | Draw blue boxes for areas with detected motion (0 or 1) |
|
|
||||||
| `regions` | int | Draw green boxes for areas where object detection was run (0 or 1) |
|
|
||||||
|
|
||||||
You can access a higher resolution mjpeg stream by appending `h=height-in-pixels` to the endpoint. For example `http://localhost:5000/api/back?h=1080`. You can also increase the FPS by appending `fps=frame-rate` to the URL such as `http://localhost:5000/api/back?fps=10` or both with `?fps=10&h=1000`.
|
Restarts Frigate process.
|
||||||
|
|
||||||
### `GET /api/<camera_name>/latest.jpg[?h=300]`
|
|
||||||
|
|
||||||
The most recent frame that Frigate has finished processing. It is a full resolution image by default.
|
|
||||||
|
|
||||||
Accepts the following query string parameters:
|
|
||||||
|
|
||||||
| param | Type | Description |
|
|
||||||
| ----------- | ---- | ------------------------------------------------------------------ |
|
|
||||||
| `h` | int | Height in pixels |
|
|
||||||
| `bbox` | int | Show bounding boxes for detected objects (0 or 1) |
|
|
||||||
| `timestamp` | int | Print the timestamp in the upper left (0 or 1) |
|
|
||||||
| `zones` | int | Draw the zones on the image (0 or 1) |
|
|
||||||
| `mask` | int | Overlay the mask on the image (0 or 1) |
|
|
||||||
| `motion` | int | Draw blue boxes for areas with detected motion (0 or 1) |
|
|
||||||
| `regions` | int | Draw green boxes for areas where object detection was run (0 or 1) |
|
|
||||||
| `quality` | int | Jpeg encoding quality (0-100). Defaults to 70. |
|
|
||||||
|
|
||||||
Example parameters:
|
|
||||||
|
|
||||||
- `h=300`: resizes the image to 300 pixels tall
|
|
||||||
|
|
||||||
### `GET /api/stats`
|
### `GET /api/stats`
|
||||||
|
|
||||||
@ -54,6 +24,7 @@ Sample response:
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
/* Per Camera Stats */
|
/* Per Camera Stats */
|
||||||
|
"cameras": {
|
||||||
"back": {
|
"back": {
|
||||||
/***************
|
/***************
|
||||||
* Frames per second being consumed from your camera. If this is higher
|
* Frames per second being consumed from your camera. If this is higher
|
||||||
@ -83,6 +54,7 @@ Sample response:
|
|||||||
* Frames per second skip for processing by Frigate.
|
* Frames per second skip for processing by Frigate.
|
||||||
***************/
|
***************/
|
||||||
"skipped_fps": 0.0
|
"skipped_fps": 0.0
|
||||||
|
}
|
||||||
},
|
},
|
||||||
/***************
|
/***************
|
||||||
* Sum of detection_fps across all cameras and detectors.
|
* Sum of detection_fps across all cameras and detectors.
|
||||||
@ -139,18 +111,109 @@ Sample response:
|
|||||||
"mnt_type": "tmpfs"
|
"mnt_type": "tmpfs"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"cpu_usages": {
|
||||||
|
"pid": {
|
||||||
|
"cmdline": "ffmpeg...",
|
||||||
|
"cpu": "5.0",
|
||||||
|
"cpu_average": "3.0",
|
||||||
|
"mem": "0.5",
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"gpu_usages": {
|
||||||
|
"gpu-type": {
|
||||||
|
"gpu": "17%",
|
||||||
|
"mem": "18%",
|
||||||
|
},
|
||||||
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### `GET /api/config`
|
|
||||||
|
|
||||||
A json representation of your configuration
|
|
||||||
|
|
||||||
### `GET /api/version`
|
### `GET /api/version`
|
||||||
|
|
||||||
Version info
|
Version info
|
||||||
|
|
||||||
|
### `GET /api/ffprobe`
|
||||||
|
|
||||||
|
Get ffprobe output for camera feed paths.
|
||||||
|
|
||||||
|
| param | Type | Description |
|
||||||
|
| ------- | ------ | ---------------------------------- |
|
||||||
|
| `paths` | string | `,` separated list of camera paths |
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/ptz/info`
|
||||||
|
|
||||||
|
Get PTZ info for the camera.
|
||||||
|
|
||||||
|
## Camera Media
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>`
|
||||||
|
|
||||||
|
An mjpeg stream for debugging. Keep in mind the mjpeg endpoint is for debugging only and will put additional load on the system when in use.
|
||||||
|
|
||||||
|
Accepts the following query string parameters:
|
||||||
|
|
||||||
|
| param | Type | Description |
|
||||||
|
| ----------- | ---- | ------------------------------------------------------------------ |
|
||||||
|
| `fps` | int | Frame rate |
|
||||||
|
| `h` | int | Height in pixels |
|
||||||
|
| `bbox` | int | Show bounding boxes for detected objects (0 or 1) |
|
||||||
|
| `timestamp` | int | Print the timestamp in the upper left (0 or 1) |
|
||||||
|
| `zones` | int | Draw the zones on the image (0 or 1) |
|
||||||
|
| `mask` | int | Overlay the mask on the image (0 or 1) |
|
||||||
|
| `motion` | int | Draw blue boxes for areas with detected motion (0 or 1) |
|
||||||
|
| `regions` | int | Draw green boxes for areas where object detection was run (0 or 1) |
|
||||||
|
|
||||||
|
You can access a higher resolution mjpeg stream by appending `h=height-in-pixels` to the endpoint. For example `http://localhost:5000/api/back?h=1080`. You can also increase the FPS by appending `fps=frame-rate` to the URL such as `http://localhost:5000/api/back?fps=10` or both with `?fps=10&h=1000`.
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/latest.jpg[?h=300]`
|
||||||
|
|
||||||
|
The most recent frame that Frigate has finished processing. It is a full resolution image by default.
|
||||||
|
|
||||||
|
Accepts the following query string parameters:
|
||||||
|
|
||||||
|
| param | Type | Description |
|
||||||
|
| ----------- | ---- | ------------------------------------------------------------------ |
|
||||||
|
| `h` | int | Height in pixels |
|
||||||
|
| `bbox` | int | Show bounding boxes for detected objects (0 or 1) |
|
||||||
|
| `timestamp` | int | Print the timestamp in the upper left (0 or 1) |
|
||||||
|
| `zones` | int | Draw the zones on the image (0 or 1) |
|
||||||
|
| `mask` | int | Overlay the mask on the image (0 or 1) |
|
||||||
|
| `motion` | int | Draw blue boxes for areas with detected motion (0 or 1) |
|
||||||
|
| `regions` | int | Draw green boxes for areas where object detection was run (0 or 1) |
|
||||||
|
| `quality` | int | Jpeg encoding quality (0-100). Defaults to 70. |
|
||||||
|
|
||||||
|
Example parameters:
|
||||||
|
|
||||||
|
- `h=300`: resizes the image to 300 pixels tall
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/<label>/thumbnail.jpg`
|
||||||
|
|
||||||
|
Returns the thumbnail from the latest event for the given camera and label combo. Using `any` as the label will return the latest thumbnail regardless of type.
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/<label>/clip.mp4`
|
||||||
|
|
||||||
|
Returns the clip from the latest event for the given camera and label combo. Using `any` as the label will return the latest clip regardless of type.
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/<label>/snapshot.jpg`
|
||||||
|
|
||||||
|
Returns the snapshot image from the latest event for the given camera and label combo. Using `any` as the label will return the latest thumbnail regardless of type.
|
||||||
|
|
||||||
|
### `GET /api/<camera_name>/grid.jpg`
|
||||||
|
|
||||||
|
Returns the latest camera image with the regions grid overlaid.
|
||||||
|
|
||||||
|
| param | Type | Description |
|
||||||
|
| ------------ | ----- | ------------------------------------------------------------------------------------------ |
|
||||||
|
| `color` | str | The color of the grid (red,green,blue,black,white). Defaults to "green". |
|
||||||
|
| `font_scale` | float | Font scale. Can be used to increase font size on high resolution cameras. Defaults to 0.5. |
|
||||||
|
|
||||||
|
### `GET /clips/<camera>-<id>.jpg`
|
||||||
|
|
||||||
|
JPG snapshot for the given camera and event id.
|
||||||
|
|
||||||
|
## Events
|
||||||
|
|
||||||
### `GET /api/events`
|
### `GET /api/events`
|
||||||
|
|
||||||
Events from the database. Accepts the following query string parameters:
|
Events from the database. Accepts the following query string parameters:
|
||||||
@ -175,16 +238,6 @@ Events from the database. Accepts the following query string parameters:
|
|||||||
| `min_length` | float | Minimum length of the event |
|
| `min_length` | float | Minimum length of the event |
|
||||||
| `max_length` | float | Maximum length of the event |
|
| `max_length` | float | Maximum length of the event |
|
||||||
|
|
||||||
### `GET /api/timeline`
|
|
||||||
|
|
||||||
Timeline of key moments of an event(s) from the database. Accepts the following query string parameters:
|
|
||||||
|
|
||||||
| param | Type | Description |
|
|
||||||
| ----------- | ---- | ----------------------------------- |
|
|
||||||
| `camera` | str | Name of camera |
|
|
||||||
| `source_id` | str | ID of tracked object |
|
|
||||||
| `limit` | int | Limit the number of events returned |
|
|
||||||
|
|
||||||
### `GET /api/events/summary`
|
### `GET /api/events/summary`
|
||||||
|
|
||||||
Returns summary data for events in the database. Used by the Home Assistant integration.
|
Returns summary data for events in the database. Used by the Home Assistant integration.
|
||||||
@ -233,14 +286,6 @@ Sub labels must be 100 characters or shorter.
|
|||||||
|
|
||||||
Returns a thumbnail for the event id optimized for notifications. Works while the event is in progress and after completion. Passing `?format=android` will convert the thumbnail to 2:1 aspect ratio.
|
Returns a thumbnail for the event id optimized for notifications. Works while the event is in progress and after completion. Passing `?format=android` will convert the thumbnail to 2:1 aspect ratio.
|
||||||
|
|
||||||
### `GET /api/<camera_name>/<label>/thumbnail.jpg`
|
|
||||||
|
|
||||||
Returns the thumbnail from the latest event for the given camera and label combo. Using `any` as the label will return the latest thumbnail regardless of type.
|
|
||||||
|
|
||||||
### `GET /api/<camera_name>/<label>/clip.mp4`
|
|
||||||
|
|
||||||
Returns the clip from the latest event for the given camera and label combo. Using `any` as the label will return the latest clip regardless of type.
|
|
||||||
|
|
||||||
### `GET /api/events/<id>/clip.mp4`
|
### `GET /api/events/<id>/clip.mp4`
|
||||||
|
|
||||||
Returns the clip for the event id. Works after the event has ended.
|
Returns the clip for the event id. Works after the event has ended.
|
||||||
@ -259,26 +304,51 @@ Accepts the following query string parameters, but they are only applied when an
|
|||||||
| `crop` | int | Crop the snapshot to the (0 or 1) |
|
| `crop` | int | Crop the snapshot to the (0 or 1) |
|
||||||
| `quality` | int | Jpeg encoding quality (0-100). Defaults to 70. |
|
| `quality` | int | Jpeg encoding quality (0-100). Defaults to 70. |
|
||||||
|
|
||||||
### `GET /api/<camera_name>/<label>/snapshot.jpg`
|
### `POST /api/events/<camera_name>/<label>/create`
|
||||||
|
|
||||||
Returns the snapshot image from the latest event for the given camera and label combo. Using `any` as the label will return the latest thumbnail regardless of type.
|
Create a manual event with a given `label` (ex: doorbell press) to capture a specific event besides an object being detected.
|
||||||
|
|
||||||
### `GET /api/<camera_name>/recordings/<frame_time>/snapshot.png`
|
:::caution
|
||||||
|
|
||||||
Returns the snapshot image from the specific point in that cameras recordings.
|
Recording retention config still applies to manual events, if frigate is configured with `mode: motion` then the manual event will only keep recording segments when motion occurred.
|
||||||
|
|
||||||
### `GET /api/<camera_name>/grid.jpg`
|
:::
|
||||||
|
|
||||||
Returns the latest camera image with the regions grid overlaid.
|
**Optional Body:**
|
||||||
|
|
||||||
| param | Type | Description |
|
```json
|
||||||
| ------------ | ----- | ------------------------------------------------------------------------------------------ |
|
{
|
||||||
| `color` | str | The color of the grid (red,green,blue,black,white). Defaults to "green". |
|
"sub_label": "some_string", // add sub label to event
|
||||||
| `font_scale` | float | Font scale. Can be used to increase font size on high resolution cameras. Defaults to 0.5. |
|
"duration": 30, // predetermined length of event (default: 30 seconds) or can be to null for indeterminate length event
|
||||||
|
"include_recording": true, // whether the event should save recordings along with the snapshot that is taken
|
||||||
|
"draw": {
|
||||||
|
// optional annotations that will be drawn on the snapshot
|
||||||
|
"boxes": [
|
||||||
|
{
|
||||||
|
"box": [0.5, 0.5, 0.25, 0.25], // box consists of x, y, width, height which are on a scale between 0 - 1
|
||||||
|
"color": [255, 0, 0], // color of the box, default is red
|
||||||
|
"score": 100 // optional score associated with the box
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### `GET /clips/<camera>-<id>.jpg`
|
**Success Response:**
|
||||||
|
|
||||||
JPG snapshot for the given camera and event id.
|
```json
|
||||||
|
{
|
||||||
|
"event_id": "1682970645.13116-1ug7ns",
|
||||||
|
"message": "Successfully created event.",
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `PUT /api/events/<event_id>/end`
|
||||||
|
|
||||||
|
End a specific manual event without a predetermined length.
|
||||||
|
|
||||||
|
## Recordings
|
||||||
|
|
||||||
### `GET /vod/<year>-<month>/<day>/<hour>/<camera>/master.m3u8`
|
### `GET /vod/<year>-<month>/<day>/<hour>/<camera>/master.m3u8`
|
||||||
|
|
||||||
@ -327,62 +397,18 @@ Get recording segment details for the given timestamp range.
|
|||||||
| `after` | int | Unix timestamp for beginning of range |
|
| `after` | int | Unix timestamp for beginning of range |
|
||||||
| `before` | int | Unix timestamp for end of range |
|
| `before` | int | Unix timestamp for end of range |
|
||||||
|
|
||||||
### `GET /api/ffprobe`
|
### `GET /api/<camera_name>/recordings/<frame_time>/snapshot.png`
|
||||||
|
|
||||||
Get ffprobe output for camera feed paths.
|
Returns the snapshot image from the specific point in that cameras recordings.
|
||||||
|
|
||||||
|
## Timeline
|
||||||
|
|
||||||
|
### `GET /api/timeline`
|
||||||
|
|
||||||
|
Timeline of key moments of an event(s) from the database. Accepts the following query string parameters:
|
||||||
|
|
||||||
| param | Type | Description |
|
| param | Type | Description |
|
||||||
| ------- | ------ | ---------------------------------- |
|
| ----------- | ---- | ----------------------------------- |
|
||||||
| `paths` | string | `,` separated list of camera paths |
|
| `camera` | str | Name of camera |
|
||||||
|
| `source_id` | str | ID of tracked object |
|
||||||
### `GET /api/<camera_name>/ptz/info`
|
| `limit` | int | Limit the number of events returned |
|
||||||
|
|
||||||
Get PTZ info for the camera.
|
|
||||||
|
|
||||||
### `POST /api/events/<camera_name>/<label>/create`
|
|
||||||
|
|
||||||
Create a manual event with a given `label` (ex: doorbell press) to capture a specific event besides an object being detected.
|
|
||||||
|
|
||||||
:::caution
|
|
||||||
|
|
||||||
Recording retention config still applies to manual events, if frigate is configured with `mode: motion` then the manual event will only keep recording segments when motion occurred.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
**Optional Body:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"sub_label": "some_string", // add sub label to event
|
|
||||||
"duration": 30, // predetermined length of event (default: 30 seconds) or can be to null for indeterminate length event
|
|
||||||
"include_recording": true, // whether the event should save recordings along with the snapshot that is taken
|
|
||||||
"draw": {
|
|
||||||
// optional annotations that will be drawn on the snapshot
|
|
||||||
"boxes": [
|
|
||||||
{
|
|
||||||
"box": [0.5, 0.5, 0.25, 0.25], // box consists of x, y, width, height which are on a scale between 0 - 1
|
|
||||||
"color": [255, 0, 0], // color of the box, default is red
|
|
||||||
"score": 100 // optional score associated with the box
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Success Response:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"event_id": "1682970645.13116-1ug7ns",
|
|
||||||
"message": "Successfully created event.",
|
|
||||||
"success": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `PUT /api/events/<event_id>/end`
|
|
||||||
|
|
||||||
End a specific manual event without a predetermined length.
|
|
||||||
|
|
||||||
### `POST /api/restart`
|
|
||||||
|
|
||||||
Restarts Frigate process.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user