MetaVision Lite - API Documentation

Introduction

MetaVision is an advanced, high-performance Multi-Modal AI analysis engine.

Unlike traditional computer vision APIs that return static labels, MetaVision allows you to define flexible Analysis Categories or use Custom Prompts to extract structured intelligence from media (Images, Videos, and Audio).

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Core Analysis

The primary endpoint handles image, video, and audio analysis.

Request Structure

Send a JSON body with the media content and configuration.

Required Parameters

Optional Parameters

Response Structure

The API returns a JSON object divided into metadata and data results.

{
"meta": {
  "timestamp": "2024-03-20T10:00:00.000Z",
  "model_id": "8f32e9...",
  "model_name": "general-v2",
  "execution_time": 2.45,
  "successful_categories": 2,
  "failed_categories": 0,
  "total_tokens_in": 1500,
  "total_tokens_out": 300,
  "total_tokens_reasoning": 0,
  "total_tokens_cached": 0,
  "cost": 0.0045
},
"data": {
  "title": {
    "result": "Sunset over a mountain range"
  },
  "custom_analysis": {
    "result": "The mood is serene and peaceful."
  }
}
}

Meta Object

Analysis Categories

Categories define specific tasks for the engine. You can select specific categories in your request to tailor the analysis output.

Available Models

Use the UUID below in the model parameter to force a specific agent. If no model is forced, requests use the default strategy which selects the recommended default model automatically.

Advanced Options

Additional Context

The optional context parameter lets you supply supporting information (metadata, transcripts, prior moderation notes, business rules, etc.) that the model should take into account while analyzing the media.

Limits and behaviour:

{
"media": "https://example.com/image.jpg",
"categories": ["description"],
"context": "Uploaded by user #4213 in the 'fitness' channel. Previous uploads were flagged for nudity."
}

Agent Selection

By default (agent_strategy: "default"), MetaVision routes requests to a recommended, well-balanced default model. You can override this behavior with random for load balancing across all capable agents, best to always select the highest reliability score, or by forcing a specific model UUID.

Agent Consistency

MetaVision ensures consistency by using a single Agent for all categories within a single request. This prevents conflicting interpretations of the media across different analysis tasks.

Audio Analysis

MetaVision supports audio files (MP3, WAV, OGG). The engine listens to speech, tone, and background audio to perform the analysis. Max file size: 10MB.

Video Analysis

MetaVision supports video files (MP4, MOV, WebM). The engine samples frames from the video to perform the analysis.

Usage & Cost

MetaVision enables provider usage accounting on every upstream call, so token counts and the cost returned in meta come directly from the provider that served the request.

• cost is expressed in USD and is the sum of the per-category costs reported for the request.
• When a request runs through a bring-your-own-key route, the upstream inference cost reported by the provider is included in the total.
• Requests are billed per category: selecting three categories performs three model calls, each with its own token usage.
• If a provider does not return usage accounting for a call, MetaVision falls back to the per-million-token rates configured for the agent.
• Failed or timed-out categories report zero tokens and zero cost.

Error Handling

Errors can occur at the request level (4xx/5xx status codes) or at the individual category level.

API Errors

Code Examples

import requests

API_KEY = "your_api_key"
API_URL = "https://metavision.api.efficientstack.com/api/v1/analyze"

payload = {
  "media": "https://example.com/image.jpg",
  "categories": ["title", "description"],
  "custom_prompt": "Describe the emotion.",
  "context": "Uploaded by user #4213. Channel: fitness. Locale: fr-CA.",
  # "model": "8f32e9...", # Optional UUID override
  "agent_strategy": "default"
}

headers = {
  "Authorization": f"Bearer {API_KEY}",
  "Content-Type": "application/json"
}

response = requests.post(API_URL, json=payload, headers=headers)
data = response.json()
print(data["meta"]["cost"], data["data"])

const API_KEY = 'your_api_key';
const API_URL = 'https://metavision.api.efficientstack.com/api/v1/analyze';

async function analyzeMedia() {
const response = await fetch(API_URL, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    media: "https://example.com/audio.mp3", // Audio supported
    categories: ["title"],
    custom_prompt: "Transcribe the speech and describe tone.",
    context: "Podcast episode 42. Speakers: host (male), guest (female).",
    agent_strategy: "default" // Uses the recommended default model
  })
});

const result = await response.json();
console.log(result.meta.cost, result.data);
}

analyzeMedia();

curl -X POST "https://metavision.api.efficientstack.com/api/v1/analyze" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "media": "https://example.com/image.jpg",
  "custom_prompt": "List all colors present.",
  "context": "Product photo for SKU 88213, studio lighting.",
  "agent_strategy": "default"
}'