Video grounding — locate objects or events in video

post/ground/video

Scans a video clip for objects or events matching query.

kind: "object" — returns temporal intervals where the object appears, with optional per-frame bounding boxes (the spatio-temporal tube).
kind: "event" — returns the onset timestamp of a happening.

Maximum clip size is 200 MB.

Body ParametersExpand Collapse

query: string

What to find in the video.

video: object { b64, max_edge, mime, url }

A video clip. Provide url or b64. Maximum 200 MB.

b64: optional string

Base64-encoded video bytes.

max_edge: optional number

Downscale frame long edge to this size before processing.

minimum64

maximum1792

mime: optional string

url: optional string

Public HTTP(S) video URL.

allow_abstain: optional boolean

boxes_on_hits: optional boolean

Whether to return per-frame bounding boxes on hit intervals.

coarse_step: optional number

Seconds between coarse scan samples.

exclusiveMinimum0

fine_resolution: optional number

Seconds between fine scan samples within detected intervals.

exclusiveMinimum0

kind: optional "object" or "event"

object — find temporal intervals where the object appears, with bounding boxes. event — find the onset timestamp of a happening.

Accepts one of the following:

"object"

"event"

max_probes: optional number

Maximum number of frames to probe.

minimum1

ReturnsExpand Collapse

VideoGroundDecision = object { duration_s, hits, kind, 6 more }

duration_s: number

Total clip duration in seconds.

hits: array of unknown

For kind: "object" — each hit has start, end, peak_t, confidence, and optional boxes (array of GroundRegion). For kind: "event" — each hit has onset_t and confidence.

kind: "object" or "event"

Accepts one of the following:

"object"

"event"

type: "video_ground"

Accepts one of the following:

"video_ground"

billable_tokens: optional number

image_tokens: optional number

input_tokens: optional number

scanned: optional number

Number of frames probed.

truncated: optional boolean

Whether scanning was truncated by max_probes.

Video grounding — locate objects or events in video

curl https://api.articul8.ai/bivia/ground/video \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "query": "the red car",
          "video": {
            "url": "https://example.com/clip.mp4"
          }
        }'

{
  "duration_s": 0,
  "hits": [
    {}
  ],
  "kind": "object",
  "type": "video_ground",
  "billable_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "scanned": 0,
  "truncated": true
}

Returns Examples

{
  "duration_s": 0,
  "hits": [
    {}
  ],
  "kind": "object",
  "type": "video_ground",
  "billable_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "scanned": 0,
  "truncated": true
}