MetaVision Insight API

MetaVision is a high-performance multi-modal AI analysis engine.

Unlike traditional computer vision APIs that return static labels, MetaVision lets you define flexible analysis categories or use custom prompts to extract structured intelligence from media: images, videos, audio, and raw text.

Every analysis request requires an API key sent as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

The public category and model listings used on this page do not require authentication.

The primary endpoint handles image, video, audio, and text analysis. Only POST is accepted.

Request structure

Send a JSON body with the media content and configuration.

Required parameters

Optional parameters

Media types

The media type is detected from the media value in the following order. It determines which agents are capable and which timeout applies.

Response structure

The API returns a JSON object divided into metadata and per-category 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."
    }
  }
}

A category that fails or times out is still present under its output key, as { "error": "..." }, and is counted in failed_categories.

Meta object

Categories define specific analysis tasks. Pass their IDs in categories; each result is returned under the listed output key.

Use the UUID below in the model parameter to force a specific agent. If no model is forced, the default strategy selects general-v2 automatically.

Additional context

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

{
  "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 the recommended default model, general-v2. Use best to always select the highest reliability score, or force a specific model UUID.

Agent consistency

A single agent handles every category within a request. This prevents conflicting interpretations of the media across different analysis tasks.

Audio analysis

MetaVision supports MP3, WAV, and OGG audio. The engine listens to speech, tone, and background audio. Send audio as a Base64 data URI; maximum file size is 10 MB.

Video analysis

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

Timeouts

Each category runs as its own model call, in parallel. Each call has the following time limit; a call that exceeds it is reported as Timeout.

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.

Errors can occur at the request level (4xx/5xx status codes) or at the individual category level. Request-level errors return this body:

{
  "error": true,
  "message": "Invalid API key.",
  "code": "invalid_api_key"
}

API errors