> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machinefi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Frame

> Analyze a single image frame with VLM. Accepts a base64-encoded JPEG and a question — no stream URL needed.

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

<ParamField name="frame_b64" type="string" required>
  Base64-encoded JPEG image (raw base64, no `data:` URI prefix).
</ParamField>

<ParamField name="question" type="string" required>
  Question or condition about the image (max 1000 characters).
</ParamField>

<ParamField name="include_frame" type="boolean" default="false">
  Include the analyzed frame back in the response.
</ParamField>

## Response

<ResponseExample>
  ```json theme={null}
  {
    "answer": "Yes, there is a person visible in the center of the frame.",
    "triggered": true,
    "latency_ms": 1250,
    "frame_b64": null
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json theme={null}
  {
    "answer": "The image shows a blue sky with scattered white clouds.",
    "triggered": null,
    "latency_ms": 890,
    "frame_b64": "/9j/4AAQSkZJRg..."
  }
  ```
</ResponseExample>

## Error Handling

<RequestExample>
  ```json theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid base64 frame data: Incorrect padding",
      "remediation": "Ensure frame_b64 is valid base64-encoded JPEG data"
    }
  }
  ```
</RequestExample>

<RequestExample>
  ```json theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Frame data too small — expected a JPEG image",
      "remediation": "Ensure the base64 data represents a valid JPEG image"
    }
  }
  ```
</RequestExample>

## Related

* Monitoring workflows: [Live Monitor](/api-reference/live-monitor)
* Stream validation: [Validate Stream](/api-reference/streams-validate)
* Single check: [Check Once](/api-reference/check-once)


## OpenAPI

````yaml POST /analyze-frame
openapi: 3.1.0
info:
  title: Trio API
  description: Reality as an API - Monitor YouTube Live streams with vision models
  version: 1.0.0
servers:
  - url: https://trio.machinefi.com/api
security: []
paths:
  /analyze-frame:
    post:
      tags:
        - Analysis
      summary: Analyze Frame
      description: >-
        Analyze a single image frame with VLM. Accepts a base64-encoded JPEG and
        a question — no stream URL needed.
      operationId: analyze_frame_analyze_frame_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeFrameRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeFrameResponse'
        '400':
          description: Invalid frame data or analysis failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    AnalyzeFrameRequest:
      properties:
        frame_b64:
          type: string
          minLength: 1
          title: Frame B64
          description: 'Base64-encoded JPEG image (raw base64, no data: URI prefix)'
        question:
          type: string
          maxLength: 1000
          minLength: 1
          title: Question
          description: >-
            Question or condition about the image (e.g., 'what do you see?' or
            'is there a person?')
        include_frame:
          type: boolean
          title: Include Frame
          description: Include the frame back in the response
          default: false
      type: object
      required:
        - frame_b64
        - question
      title: AnalyzeFrameRequest
      description: |-
        Request to analyze a single image frame with VLM.

        Used by TrioClaw and other clients that capture their own frames
        and just need VLM analysis — no stream URL or live validation needed.
    AnalyzeFrameResponse:
      properties:
        answer:
          type: string
          title: Answer
          description: VLM's analysis of the image
        triggered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Triggered
          description: Whether a yes/no condition was met (null for open-ended questions)
        latency_ms:
          type: integer
          title: Latency Ms
          description: Total processing time in milliseconds
        frame_b64:
          anyOf:
            - type: string
            - type: 'null'
          title: Frame B64
          description: The analyzed frame (only if include_frame was true)
      type: object
      required:
        - answer
        - latency_ms
      title: AnalyzeFrameResponse
      description: Response from frame analysis.
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorResponse
      description: Wrapper for error responses.
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        remediation:
          type: string
          title: Remediation
      type: object
      required:
        - code
        - message
        - remediation
      title: ErrorDetail
      description: Standardized error response for better DX.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````