/api/v1/live/sessions/{id}The session. For url sessions also the samples checked since after (poll with the last seq you saw). Polling keeps the session paid and notices when the stream ends. Camera sessions return entries: []: their results come back from each frame.
Path parameters#
| Parameter | Type | Description |
|---|---|---|
id required |
integer |
Session id. |
Query parameters#
| Parameter | Type | Description |
|---|---|---|
after |
integer |
Return only samples with a seq greater than this. Default: 0. |
Responses#
200#
The session and new samples.
-
sessionobject (LiveSession) requiredThe session, as it is now.
-
entriesarray of LiveEntry requiredSamples checked since
after(stream sessions only). -
latestFrameobjectStream URL sessions: the newest sample's picture, so a live view needs no second request. Absent when no new sample has a picture.
session (LiveSession)
-
idinteger requiredSession id.
-
sourcestring requiredOne of:
url,camera.url(a stream watched by our servers) orcamera(frames you send). -
urlstring or null requiredThe stream address;
nullfor camera sessions. -
fpsnumber requiredFrames checked per second.
-
modestring requiredOne of:
detect,capture,censor.detect,captureorcensor. -
censorStylestring or null requiredOne of:
blur,pixelate,box,null. How the moments' censored copies hide what was found;nullunlessmodeiscensor. -
trackingboolean requiredWhether findings are followed from frame to frame (see
trackingwhen starting). -
frameSideinteger requiredLong side, in pixels, of the pictures kept.
-
momentEveryinteger requiredSeconds at least between two kept moments.
-
statusstring requiredOne of:
running,stopped,ended,failed.stopped: by you or when the credits ran out.ended: the stream ended.failed: the stream could not be watched. -
reasonstring or null requiredWhy the session is no longer running.
-
framesCheckedinteger requiredFrames checked so far.
-
framesFlaggedinteger requiredFrames that raised at least one flag.
-
momentsinteger requiredFlagged frames kept, with their picture, in your moderation history.
-
creditsChargedinteger requiredCredits taken from your balance for the session. While it runs this includes the minute held ahead; when it ends, what its frames did not use goes back and this is what the session cost.
-
creditsUsedinteger requiredWhat the frames checked so far cost: each frame costs
costPerMinute / (60 x fps), rounded up to whole credits for the session, and never more thancreditsCharged. Equal tocreditsChargedonce the session has ended. -
costPerMinuteinteger requiredWhat a minute at the session's rate costs: the credits held ahead each minute.
-
startedAtinteger requiredUnix time, seconds.
-
endedAtinteger or number or null requiredUnix time, seconds;
nullwhile running. -
jobIdinteger or null requiredThe session's entry in your moderation history.
-
widthintegerStream sessions while running: the stream's width.
-
heightintegerStream sessions while running: the stream's height.
-
flagsarray or null requiredThe flags checked on every frame, as chosen at the start;
null: every flag. -
metadataobjectThe session's
metadata, unchanged, when you sent one.
entries[] (LiveEntry)
-
seqinteger requiredSample number, increasing.
-
tnumber requiredSeconds since the stream started.
-
atnumber requiredUnix time, seconds.
-
frameboolean requiredtruewhen its picture can be fetched with Get a stream sample's picture. -
flaggedboolean requiredtruewhen the sample raised at least one flag. -
flagsarray of FlagResult requiredThe flags raised, as in a moderation result.
-
uncheckedarray of string requiredFlags that could not be checked for this sample.
-
momentintegerSet when this sample was kept as a moment: the moment's id in your history.
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.
latestFrame
-
seqinteger requiredThe sample the picture belongs to.
-
jpegstring requiredThe picture, base64-encoded JPEG (the newest checked sample of the stream).
401#
Missing, unknown, revoked or expired API key, or the account is not active.
{
"error": "unauthorized",
"message": "The API key is not valid."
}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."
}429#
Too many requests in a minute. Wait Retry-After seconds. See Rate limits.
Header Retry-After: Seconds to wait.
{
"error": "too_many_requests",
"message": "Too many requests. Try again in a minute."
}Request
curl -X GET https://api.detectivision.ai/api/v1/live/sessions/{id} \
-H "Api-Key: $DETECTIVISION_API_KEY"import os, requests
r = requests.get(
"https://api.detectivision.ai/api/v1/live/sessions/{id}",
headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
)
print(r.status_code, r.json())const res = await fetch("https://api.detectivision.ai/api/v1/live/sessions/{id}", {
method: "GET",
headers: {
"Api-Key": process.env.DETECTIVISION_API_KEY,
},
});
console.log(res.status, await res.json());Response 200
{
"session": {
"id": 31,
"source": "url",
"url": "rtsp://cams.example.com/live",
"fps": 1,
"mode": "capture",
"censorStyle": null,
"tracking": false,
"frameSide": 1280,
"momentEvery": 3,
"status": "running",
"reason": null,
"framesChecked": 13,
"framesFlagged": 1,
"moments": 1,
"creditsCharged": 2,
"creditsUsed": 1,
"costPerMinute": 2,
"startedAt": 1790505000,
"endedAt": null,
"jobId": 2210,
"width": 1920,
"height": 1080
},
"entries": [
{
"seq": 12,
"t": 11.02,
"at": 1790505012.4,
"frame": true,
"flagged": false,
"flags": [],
"unchecked": []
},
{
"seq": 13,
"t": 12.01,
"at": 1790505013.4,
"frame": true,
"flagged": true,
"flags": [
{
"flag": "smoking",
"confidence": 0.84,
"detections": [
{
"label": "smoking",
"confidence": 0.84,
"bbox": [
410,
220,
520,
330
]
}
]
}
],
"unchecked": [],
"moment": 2231
}
]
}