Skip to main content
POST
/
analyze-frame
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid base64 frame data: Incorrect padding",
    "remediation": "Ensure frame_b64 is valid base64-encoded JPEG data"
  }
}

{
  "answer": "Yes, there is a person visible in the center of the frame.",
  "triggered": true,
  "latency_ms": 1250,
  "frame_b64": null
}
Analyze a pre-captured image frame with VLM. Use this when you have your own frame capture mechanism (like TrioClaw) and just need VLM analysis — no stream URL validation or capture required.

​
How It Differs From Other Endpoints

  • POST /analyze-frame — Accepts raw base64 frame, no stream URL
  • POST /check-once — Captures frame from stream URL, validates liveness
  • POST /live-monitor — Creates continuous monitoring job

​
Use Cases

  • TrioClaw — Desktop app that captures frames locally and needs VLM analysis
  • Custom pipelines — Your own frame capture (RTSP, screenshots, etc.)
  • Batch processing — Analyze many pre-captured images without stream overhead

​
Question Styles

Supports two question types:

​
Yes/No Conditions

"Is there a person?"
"Is the traffic light red?"
"Are cars moving?"
Response includes triggered: true/false.

​
Open-Ended Questions

"What do you see?"
"Describe the weather conditions."
"What is the text in this image?"
Response includes answer with full description, triggered: null.

​
Request

​
Response

{
  "answer": "Yes, there is a person visible in the center of the frame.",
  "triggered": true,
  "latency_ms": 1250,
  "frame_b64": null
}

{
  "answer": "The image shows a blue sky with scattered white clouds.",
  "triggered": null,
  "latency_ms": 890,
  "frame_b64": "/9j/4AAQSkZJRg..."
}

​
Error Handling

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid base64 frame data: Incorrect padding",
    "remediation": "Ensure frame_b64 is valid base64-encoded JPEG data"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Frame data too small — expected a JPEG image",
    "remediation": "Ensure the base64 data represents a valid JPEG image"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request for analyzing a pre-captured image frame.

​
frame_b64
string
required

Base64-encoded JPEG image (raw base64, no data: URI prefix)

Minimum string length: 1
​
question
string
required

Question or condition about the image

Required string length: 1 - 1000
​
include_frame
boolean
default:false

Include the analyzed frame back in the response

Response

Successful Response

Response for frame analysis.

​
answer
string
required

VLM analysis result

​
latency_ms
integer
required

VLM processing time in milliseconds

​
triggered
boolean | null

Whether the condition was met (null for open-ended questions)

​
frame_b64
string | null

Base64-encoded frame (only if include_frame was true)