/api/v1/live/sessionsStarts moderating a live source: url (our servers watch a stream: RTSP, RTMP, HLS, HTTP or SRT) or camera (you send frames). A minute of credits is held at once, and another each time the held minute runs out (for a camera: when a frame comes after it). When the session ends it keeps what its frames cost and the rest goes back to your balance.
Request body#
Content type: application/json.
-
sourcestring requiredOne of:
url,camera.url: our servers watch a stream.camera: you send frames. -
urlstringRequired for
url: an RTSP, RTMP, HLS (.m3u8), HTTP or SRT address that is reachable from the internet. At most 2000 characters. -
fpsnumberFrames checked per second, above 0 and at most 30. Higher rates check more frames when the models keep up; with every flag on, about 25 frames a second is the most a server checks, and fewer categories (see
flags) go faster. Price: a minute at this rate costs the rounded-up fps x the per-frame price, and each checked frame its share of that. Default:1. Above 0, at most 30. -
modestringOne of:
detect,capture,censor.detect: flags only.capture: also boxes.censor: boxes, and every kept moment also gets a censored copy (seecensorStyle), atGET /api/v1/moderation/{moment}/censored. Default:"capture". -
censorStylestringOne of:
blur,pixelate,box.censoronly: how the moments' censored copies hide what was found. Default:"blur". -
frameSideintegerStream sessions: the long side, in pixels, of the pictures kept for moments and samples (640 SD, 1280 HD, 1920 Full HD). For HLS the rendition closest to this size is watched. Default:
1280. From 240 to 1920. -
momentEveryintegerAt most one flagged frame is kept as a moment every this many seconds. Default:
3. From 1 to 600. -
flagsarray of stringThe flags to check on every frame. Only these are checked and reported, and models that feed none of them are not run, so frames are checked faster. Leave it out to check every flag live streams offer. A flag they do not check is refused (400).
-
trackingbooleanFollow each finding from frame to frame. A frame where a model misses it still carries it (marked
tracked) for about a second, or two frames at low rates, so a blur never blinks off. An object is followed once seen in two frames in a row. Only frames where a model saw something become moments. Free. Default:false. -
metadataobjectYour own JSON (an object of at most 16 KB), sent back unchanged in answers and webhooks. See /docs/actions.
Responses#
201#
The session is running.
-
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.
400#
The request is invalid, or the stream URL was refused.
{
"error": "invalid_request",
"message": "Invalid live session request",
"details": [
{
"code": "too_big",
"path": [
"fps"
],
"message": "Too big: expected number to be <=5"
}
]
}{
"error": "invalid_input",
"message": "The stream URL was refused: use rtsp, rtmp, http(s) or srt with a public address."
}401#
Missing, unknown, revoked or expired API key, or the account is not active.
{
"error": "unauthorized",
"message": "The API key is not valid."
}402#
Not enough live stream credits for the first minute.
{
"error": "insufficient_quota",
"message": "A live session costs 2 credits a minute; not enough 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"
}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."
}503#
A session could not start. temporarily_unavailable means it cannot start right now; try again in a minute. not_available_yet means live stream moderation cannot be served right now; do not retry. Nothing is charged.
{
"error": "not_available_yet",
"message": "Live stream moderation cannot be served right now."
}{
"error": "temporarily_unavailable",
"message": "All live stream slots are taken; try again in a minute."
}Request
curl -X POST https://api.detectivision.ai/api/v1/live/sessions \
-H "Api-Key: $DETECTIVISION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": "url",
"url": "rtsp://cams.example.com/live",
"fps": 1,
"mode": "capture",
"frameSide": 1280,
"momentEvery": 3
}'import os, requests
r = requests.post(
"https://api.detectivision.ai/api/v1/live/sessions",
headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
json={
"source": "url",
"url": "rtsp://cams.example.com/live",
"fps": 1,
"mode": "capture",
"frameSide": 1280,
"momentEvery": 3
},
)
print(r.status_code, r.json())const res = await fetch("https://api.detectivision.ai/api/v1/live/sessions", {
method: "POST",
headers: {
"Api-Key": process.env.DETECTIVISION_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"source": "url",
"url": "rtsp://cams.example.com/live",
"fps": 1,
"mode": "capture",
"frameSide": 1280,
"momentEvery": 3
}),
});
console.log(res.status, await res.json());Response 201
{
"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": 0,
"framesFlagged": 0,
"moments": 0,
"creditsCharged": 2,
"creditsUsed": 0,
"costPerMinute": 2,
"startedAt": 1790505000,
"endedAt": null,
"jobId": 2210
}