API Reference / Send a camera frame
API Reference

Send a camera frame

POST/api/v1/live/sessions/{id}/frames

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

  • seq integer required

    Frame number, increasing.

  • t number required

    Seconds since the session started.

  • flagged boolean required

    true when the frame raised at least one flag.

  • flags array of FlagResult required

    The flags raised, as in a moderation result.

  • checked array of string required

    Flags that were checked.

  • unchecked array of string required

    Flags that could not be checked.

  • moment integer

    Set when this frame was kept as a moment.

  • creditsUsed integer required

    What the session has cost so far, this frame included (see creditsUsed of a session).

flags[] (FlagResult)

  • flag string required

    The flag's key, one of those GET /api/v1/flags lists. See Flags.

  • confidence number required

    The highest confidence among the flag's detections. From 0 to 1.

  • detections array of Detection

    The flag's findings, strongest first. Not present in detect mode. For text and image flags they have no position.

detections[] (Detection)

  • label string required

    The model's own label for the finding (informational; may change). Use flag for decisions.

  • confidence number required

    How sure the model is. From 0 to 1.

  • bbox array of number

    Images and videos, for a flag with positions: the box [x1, y1, x2, y2] in pixels of the original image or video frame.

  • polygon array of array of number

    Images and videos, when the model outlines the finding: its outline as [x, y] points in original pixels.

  • t number

    Videos, for a flag with positions: seconds from the start of the video.

  • frame integer

    Videos, for a flag with positions: the index of the sampled frame.

  • track integer

    With tracking: the object this finding belongs to. The same object keeps the same number across frames. From 1.

  • tracked boolean

    With tracking: true when a model missed the object in this frame and tracking carried it over. Its confidence is the object's best.

  • start number

    Text: start of the span, a Unicode code point index (inclusive). Audio: seconds.

  • end number

    Text: end of the span, a Unicode code point index (exclusive). Audio: seconds.

  • text string

    Audio: 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.jpg
import 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
}