API Reference / Start a live session
API Reference

Start a live session

POST/api/v1/live/sessions

Starts 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.

  • source string required

    One of: url, camera. url: our servers watch a stream. camera: you send frames.

  • url string

    Required for url: an RTSP, RTMP, HLS (.m3u8), HTTP or SRT address that is reachable from the internet. At most 2000 characters.

  • fps number

    Frames 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.

  • mode string

    One of: detect, capture, censor. detect: flags only. capture: also boxes. censor: boxes, and every kept moment also gets a censored copy (see censorStyle), at GET /api/v1/moderation/{moment}/censored. Default: "capture".

  • censorStyle string

    One of: blur, pixelate, box. censor only: how the moments' censored copies hide what was found. Default: "blur".

  • frameSide integer

    Stream 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.

  • momentEvery integer

    At most one flagged frame is kept as a moment every this many seconds. Default: 3. From 1 to 600.

  • flags array of string

    The 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).

  • tracking boolean

    Follow 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.

  • metadata object

    Your 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.

  • id integer required

    Session id.

  • source string required

    One of: url, camera. url (a stream watched by our servers) or camera (frames you send).

  • url string or null required

    The stream address; null for camera sessions.

  • fps number required

    Frames checked per second.

  • mode string required

    One of: detect, capture, censor. detect, capture or censor.

  • censorStyle string or null required

    One of: blur, pixelate, box, null. How the moments' censored copies hide what was found; null unless mode is censor.

  • tracking boolean required

    Whether findings are followed from frame to frame (see tracking when starting).

  • frameSide integer required

    Long side, in pixels, of the pictures kept.

  • momentEvery integer required

    Seconds at least between two kept moments.

  • status string required

    One 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.

  • reason string or null required

    Why the session is no longer running.

  • framesChecked integer required

    Frames checked so far.

  • framesFlagged integer required

    Frames that raised at least one flag.

  • moments integer required

    Flagged frames kept, with their picture, in your moderation history.

  • creditsCharged integer required

    Credits 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.

  • creditsUsed integer required

    What the frames checked so far cost: each frame costs costPerMinute / (60 x fps), rounded up to whole credits for the session, and never more than creditsCharged. Equal to creditsCharged once the session has ended.

  • costPerMinute integer required

    What a minute at the session's rate costs: the credits held ahead each minute.

  • startedAt integer required

    Unix time, seconds.

  • endedAt integer or number or null required

    Unix time, seconds; null while running.

  • jobId integer or null required

    The session's entry in your moderation history.

  • width integer

    Stream sessions while running: the stream's width.

  • height integer

    Stream sessions while running: the stream's height.

  • flags array or null required

    The flags checked on every frame, as chosen at the start; null: every flag.

  • metadata object

    The 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
}