mirror of
https://github.com/blakeblackshear/frigate.git
synced 2026-02-08 20:25:26 +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.
|
||||
|
||||
### `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 |
|
||||
| ----------- | ---- | ------------------------------------------------------------------ |
|
||||
| `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) |
|
||||
### `POST /api/restart`
|
||||
|
||||
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
|
||||
Restarts Frigate process.
|
||||
|
||||
### `GET /api/stats`
|
||||
|
||||
@ -54,35 +24,37 @@ Sample response:
|
||||
```json
|
||||
{
|
||||
/* Per Camera Stats */
|
||||
"back": {
|
||||
/***************
|
||||
* Frames per second being consumed from your camera. If this is higher
|
||||
* than it is supposed to be, you should set -r FPS in your input_args.
|
||||
* camera_fps = process_fps + skipped_fps
|
||||
***************/
|
||||
"camera_fps": 5.0,
|
||||
/***************
|
||||
* Number of times detection is run per second. This can be higher than
|
||||
* your camera FPS because Frigate often looks at the same frame multiple times
|
||||
* or in multiple locations
|
||||
***************/
|
||||
"detection_fps": 1.5,
|
||||
/***************
|
||||
* PID for the ffmpeg process that consumes this camera
|
||||
***************/
|
||||
"capture_pid": 27,
|
||||
/***************
|
||||
* PID for the process that runs detection for this camera
|
||||
***************/
|
||||
"pid": 34,
|
||||
/***************
|
||||
* Frames per second being processed by Frigate.
|
||||
***************/
|
||||
"process_fps": 5.1,
|
||||
/***************
|
||||
* Frames per second skip for processing by Frigate.
|
||||
***************/
|
||||
"skipped_fps": 0.0
|
||||
"cameras": {
|
||||
"back": {
|
||||
/***************
|
||||
* Frames per second being consumed from your camera. If this is higher
|
||||
* than it is supposed to be, you should set -r FPS in your input_args.
|
||||
* camera_fps = process_fps + skipped_fps
|
||||
***************/
|
||||
"camera_fps": 5.0,
|
||||
/***************
|
||||
* Number of times detection is run per second. This can be higher than
|
||||
* your camera FPS because Frigate often looks at the same frame multiple times
|
||||
* or in multiple locations
|
||||
***************/
|
||||
"detection_fps": 1.5,
|
||||
/***************
|
||||
* PID for the ffmpeg process that consumes this camera
|
||||
***************/
|
||||
"capture_pid": 27,
|
||||
/***************
|
||||
* PID for the process that runs detection for this camera
|
||||
***************/
|
||||
"pid": 34,
|
||||
/***************
|
||||
* Frames per second being processed by Frigate.
|
||||
***************/
|
||||
"process_fps": 5.1,
|
||||
/***************
|
||||
* Frames per second skip for processing by Frigate.
|
||||
***************/
|
||||
"skipped_fps": 0.0
|
||||
}
|
||||
},
|
||||
/***************
|
||||
* Sum of detection_fps across all cameras and detectors.
|
||||
@ -139,18 +111,109 @@ Sample response:
|
||||
"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`
|
||||
|
||||
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`
|
||||
|
||||
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 |
|
||||
| `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`
|
||||
|
||||
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.
|
||||
|
||||
### `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`
|
||||
|
||||
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) |
|
||||
| `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 |
|
||||
| ------------ | ----- | ------------------------------------------------------------------------------------------ |
|
||||
| `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. |
|
||||
```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
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `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`
|
||||
|
||||
@ -327,62 +397,18 @@ Get recording segment details for the given timestamp range.
|
||||
| `after` | int | Unix timestamp for beginning 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.
|
||||
|
||||
| param | Type | Description |
|
||||
| ------- | ------ | ---------------------------------- |
|
||||
| `paths` | string | `,` separated list of camera paths |
|
||||
## Timeline
|
||||
|
||||
### `GET /api/<camera_name>/ptz/info`
|
||||
### `GET /api/timeline`
|
||||
|
||||
Get PTZ info for the camera.
|
||||
Timeline of key moments of an event(s) from the database. Accepts the following query string parameters:
|
||||
|
||||
### `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.
|
||||
| param | Type | Description |
|
||||
| ----------- | ---- | ----------------------------------- |
|
||||
| `camera` | str | Name of camera |
|
||||
| `source_id` | str | ID of tracked object |
|
||||
| `limit` | int | Limit the number of events returned |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user