/api/v1/live/sessions/{id}/framesCamera sessions: send one frame as the raw request body (not multipart) and get its result. Send at the session's fps; frames arriving faster than twice that rate are refused with 429.
Path parameters#
| Parameter | Type | Description |
|---|---|---|
id required |
integer |
Session id. |
Request body#
Content type: image/jpeg. The image, at most 2 MB.
Request body#
Content type: image/png. The image, at most 2 MB.
Request body#
Content type: image/webp. The image, at most 2 MB.
Responses#
200#
The frame's result.
-
seqinteger requiredFrame number, increasing.
-
tnumber requiredSeconds since the session started.
-
flaggedboolean requiredtruewhen the frame raised at least one flag. -
flagsarray of FlagResult requiredThe flags raised, as in a moderation result.
-
checkedarray of string requiredFlags that were checked.
-
uncheckedarray of string requiredFlags that could not be checked.
-
momentintegerSet when this frame was kept as a moment.
-
creditsUsedinteger requiredWhat the session has cost so far, this frame included (see
creditsUsedof a session).
flags[] (FlagResult)
-
flagstring requiredThe flag's key, one of those
GET /api/v1/flagslists. See Flags. -
confidencenumber requiredThe highest confidence among the flag's detections. From 0 to 1.
-
detectionsarray of DetectionThe flag's findings, strongest first. Not present in
detectmode. For text and image flags they have no position.
detections[] (Detection)
-
labelstring requiredThe model's own label for the finding (informational; may change). Use
flagfor decisions. -
confidencenumber requiredHow sure the model is. From 0 to 1.
-
bboxarray of numberImages and videos, for a flag with positions: the box
[x1, y1, x2, y2]in pixels of the original image or video frame. -
polygonarray of array of numberImages and videos, when the model outlines the finding: its outline as
[x, y]points in original pixels. -
tnumberVideos, for a flag with positions: seconds from the start of the video.
-
frameintegerVideos, for a flag with positions: the index of the sampled frame.
-
trackintegerWith
tracking: the object this finding belongs to. The same object keeps the same number across frames. From 1. -
trackedbooleanWith
tracking:truewhen a model missed the object in this frame and tracking carried it over. Its confidence is the object's best. -
startnumberText: start of the span, a Unicode code point index (inclusive). Audio: seconds.
-
endnumberText: end of the span, a Unicode code point index (exclusive). Audio: seconds.
-
textstringAudio: the words.
400#
Empty frame.
{
"error": "invalid_input",
"message": "The frame is empty."
}401#
Missing, unknown, revoked or expired API key, or the account is not active.
{
"error": "unauthorized",
"message": "The API key is not valid."
}402#
The session stopped because the credits ran out.
{
"error": "insufficient_quota",
"message": "Out of live stream credits."
}403#
The key may not do this: a read key on a write endpoint, or a restricted key.
{
"error": "forbidden",
"message": "This API key does not have write permission"
}404#
No session with this id for this account.
{
"error": "not_found",
"message": "No such live session."
}409#
Not a camera session, or the session is no longer running.
{
"error": "conflict",
"message": "This session has stopped."
}413#
The frame is larger than 2 MB.
{
"error": "payload_too_large",
"message": "A frame may be at most 2 MB."
}415#
Not a JPEG, PNG or WebP body.
{
"error": "unsupported_media_type",
"message": "Send frames as JPEG, PNG or WebP."
}429#
Frames are arriving faster than twice the session's fps.
{
"error": "too_many_requests",
"message": "Frames are coming faster than the session's rate."
}Request
curl -X POST https://api.detectivision.ai/api/v1/live/sessions/{id}/frames \
-H "Api-Key: $DETECTIVISION_API_KEY" \
-H "Content-Type: image/jpeg" \
--data-binary @frame.jpgimport os, requests
with open("frame.jpg", "rb") as f:
r = requests.post(
"https://api.detectivision.ai/api/v1/live/sessions/{id}/frames",
headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"], "Content-Type": "image/jpeg"},
data=f.read(),
)
print(r.status_code, r.json())import { readFile } from "node:fs/promises";
const res = await fetch("https://api.detectivision.ai/api/v1/live/sessions/{id}/frames", {
method: "POST",
headers: { "Api-Key": process.env.DETECTIVISION_API_KEY, "Content-Type": "image/jpeg" },
body: await readFile("frame.jpg"),
});
console.log(res.status, await res.json());Response 200
{
"seq": 8,
"t": 7.013,
"flagged": true,
"flags": [
{
"flag": "smoking",
"confidence": 0.84,
"detections": [
{
"label": "smoking",
"confidence": 0.84,
"bbox": [
410,
220,
520,
330
]
}
]
}
],
"checked": [
"nudity",
"explicit_nudity",
"sexual_objects",
"smoking"
],
"unchecked": [],
"moment": 2231,
"creditsUsed": 1
}