Video in, your JSON out.

Create an account and generate a key in the dashboard. Keys look like fv_live_…. A new account starts with 30 free minutes and no card, which is enough to answer the only question that matters: does it work on your footage.

Give it to an agent

Fovea is a tool an agent reaches for, so this is the shortest path in. One line adds an extract tool your agent can call whenever it has a video and knows what it wants out of it.

claude mcp add --transport http fovea https://api.fovea.run/v1/mcp \
  --header "Authorization: Bearer $FOVEA_KEY"

export FOVEA_KEY=fv_live_xxxxx

codex mcp add fovea --url https://api.fovea.run/v1/mcp \
  --bearer-token-env-var FOVEA_KEY

{
  "mcpServers": {
    "fovea": {
      "type": "http",
      "url": "https://api.fovea.run/v1/mcp",
      "headers": { "Authorization": "Bearer ${FOVEA_KEY}" }
    }
  }
}

Or call it yourself

A file, a schema, an Authorization header. There is no SDK, and there is nothing to install.

curl https://api.fovea.run/v1/extract \
  -H "Authorization: Bearer $FOVEA_KEY" \
  -F video=@standup-2026-08-04.mp4 \
  -F schema='{ "decisions": [{ "at": "timestamp", "text": "string" }] }'

import json, os, requests

schema = {"decisions": [{"at": "timestamp", "text": "string"}]}

response = requests.post(
    "https://api.fovea.run/v1/extract",
    headers={"Authorization": f"Bearer {os.environ['FOVEA_KEY']}"},
    files={"video": open("standup-2026-08-04.mp4", "rb")},
    data={"schema": json.dumps(schema)},
    timeout=600,
)
response.raise_for_status()

for decision in response.json()["data"]["decisions"]:
    print(decision["at"], decision["text"])

import { openAsBlob } from "node:fs";

const form = new FormData();
form.set("video", await openAsBlob("standup-2026-08-04.mp4"));
form.set(
  "schema",
  JSON.stringify({ decisions: [{ at: "timestamp", text: "string" }] }),
);

const response = await fetch("https://api.fovea.run/v1/extract", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FOVEA_KEY}` },
  body: form,
});

const body = await response.json();
if (!response.ok) throw new Error(body.error.code);

console.log(body.data.decisions);

What comes back:

{
  "id": "b6f1c0f2-8a5e-4c3d-9f1a-2e7d4c8b0a31",
  "data": {
    "decisions": [
      { "at": "04:12", "text": "Ship the importer behind a flag" },
      { "at": "09:47", "text": "Postpone the pricing change to Q4" }
    ]
  },
  "video": { "duration_seconds": 90 },
  "billed_seconds": 90
}

The MCP endpoint is the same product as the REST endpoint — same key, same metering, same guarantees. It is a surface, not a separate service. Point any MCP client at it and the agent gets a tool called extract that it can choose a schema for on its own.

POST https://api.fovea.run/v1/mcp

The extract tool

Tool calls carry JSON arguments rather than file bytes, which is why the tool takes a URL. An agent holding a local file should post it to /v1/extract as multipart instead.

The whole contract, exactly as a client receives it from tools/list. That call needs a key, so this is the only way to read it before you have an account — and it is generated from the same definitions the server registers, so it cannot describe a tool we do not serve.

{
  "name": "extract",
  "title": "Extract structured data from a video",
  "description": "Analyse a video and return JSON matching a schema you supply. Accepts a full JSON Schema or a loose sketch of the shape. Videos up to 10 minutes. Billed per second of video with a one-minute minimum, against the account that owns the API key. The extraction comes back under `data`. Runs synchronously and takes roughly half a minute for a short clip, longer for a long one — if the call is cut off, use `recent_extractions` rather than calling this again.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "video_url": {
        "type": "string",
        "format": "uri",
        "description": "A publicly reachable URL to the video to analyse."
      },
      "schema": {
        "type": "string",
        "description": "The shape you want back, as a JSON string. Either a JSON Schema, or a loose sketch such as {\"decisions\":[{\"at\":\"timestamp\",\"text\":\"string\"}]}. Any field named for a time comes back as a timecode."
      },
      "instructions": {
        "description": "Optional extra context. It never overrides the schema.",
        "type": "string",
        "maxLength": 2000
      }
    },
    "required": [
      "video_url",
      "schema"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "data": {
        "description": "The extraction, matching the schema you supplied."
      },
      "job_id": {
        "type": "string",
        "description": "This extraction's id. Pass it to `recent_extractions` to read it again."
      },
      "billed_seconds": {
        "type": "number",
        "description": "Seconds charged, after the one-minute minimum."
      },
      "duration_seconds": {
        "type": "number",
        "description": "Measured length of the video."
      }
    },
    "required": [
      "data",
      "job_id",
      "billed_seconds",
      "duration_seconds"
    ],
    "additionalProperties": false
  }
}

What the agent sees

• The extraction JSON, already validated against whatever schema the agent asked for. There is no separate conformance step for it to do.
• Failures arrive as tool errors carrying the same stable code the REST endpoint returns, so out_of_minutes is something an agent can recognise and report rather than retry blindly.
• Minutes are spent from the same balance as everything else. An agent with your key can spend your minutes — treat it accordingly.

Authorization: Bearer fv_live_xxxxx

Create and revoke keys in the dashboard. We store a hash rather than the key, so a key is shown once, at creation — if you lose it, make another and revoke the old one. Every surface takes the same key: REST and MCP alike.

A missing, malformed or revoked key returns unauthorised. Keys are account credentials that spend real minutes, so they belong on a server or in your shell environment, never in a browser or a mobile app.

multipart/form-data. Send the video as a file or as a URL, and the schema as a JSON string.

The response

Extraction happens while the request is open, so the JSON comes back on the same call. There is nothing to poll and no webhook to configure — at launch every video is under ten minutes, which is short enough to answer live.

Two forms are accepted and both are enforced identically. Whichever you send is the thing your answer is validated against — the instruction to the model and the guarantee to you are compiled from one object, so they cannot drift apart.

A sketch

Write the answer you want as though it were an example response, putting a type word where each value would go.

{
  "title": "string",
  "sentiment": "positive|neutral|negative",
  "decisions": [
    {
      "at": "timestamp",
      "text": "string — what was decided, in one sentence",
      "owner": "string?"
    }
  ],
  "action_items": 0
}

You can describe any leaf while still naming its type by putting the description after a separator — "string — what was decided". An em dash, --, -, // or : all separate.

• Key order is kept. The order you write the keys in is the order they come back in — a sketch is read top to bottom, so the answer is too.
• Objects are strict. Every key is required unless you mark it optional, and nothing extra is ever added to the result.

A real JSON Schema

Send one and it passes through untouched. We never improve a contract you wrote deliberately.

{
  "type": "object",
  "properties": {
    "decisions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "at": { "type": "string", "pattern": "^\\d{1,2}:[0-5]\\d$" },
          "text": { "type": "string" }
        },
        "required": ["at", "text"]
      }
    }
  },
  "required": ["decisions"]
}

We tell the two apart by looking for JSON Schema’s own vocabulary at the root: $schema, properties, $defs, type, items, enum, anyOf, oneOf, allOf or $ref. Anything else is read as a sketch. The test is generous on purpose — misreading a real schema as a sketch would silently rewrite your contract, so we would rather err the other way.

Which to use

• Sketch for almost everything, and for anything you are still working out. It is faster to write, faster to read in a diff, and it gives you timestamps for free.
• JSON Schema when you already have one — generated from your types, or shared with the rest of your stack — or when you need constraints a sketch cannot express: minimum, maxItems, pattern, $ref.

This is the part a transcript-plus-LLM pipeline gets wrong. Ask for a moment and you get a real position in the video, measured from the start, in the same response as the data it belongs to.

{
  "chapters": [
    { "start": "string", "end": "string", "heading": "string" }
  ],
  "first_mention_of_pricing": "timestamp"
}

In a sketch, a field becomes a timestamp two ways:

• The value says so. "at": "timestamp", or any of time, at, when, clock.
• The key says so. A field named at, time, timestamp, start, end, startsAt, endsAt, start_time or end_time is treated as a timestamp even when its value just says "string".

The format is MM:SS, and it is enforced by the same validator that enforces the rest of your shape rather than requested politely in a prompt. Videos an hour or longer would use HH:MM:SS; nothing is that long at launch.

A timestamp marks the moment the thing you asked about first becomes true, not the moment it finishes. If you want a span, ask for one: start and end are both timestamp keys.

Every non-2xx response has one shape.

{
  "error": {
    "code": "video_too_long",
    "message": "Videos are limited to 10 minutes for now.",
    "details": []
  }
}

• code is the contract. Switch on it. It never changes meaning, and it never names or leaks the model underneath — you should not be able to tell which one ran, and you should not have to change your error handling on the day we swap it.
• message is for a human reading a log. Do not parse it.
• details appears when there is something specific to say — most usefully on schema_invalid and extraction_failed, where it lists exactly which parts of your schema the answer failed to satisfy.

How a job is priced

• Duration is probed from the file we received, with ffprobe. Never from a field you send us — duration is the whole billing input, so a client-supplied one is a client-supplied invoice.
• Billing is per second with a one-minute minimum per job. A 12-second clip costs a minute; a 90-second clip costs 90 seconds, not two minutes.
• Your balance is the sum of an append-only ledger, not a counter someone decrements. Every debit carries the job that caused it, so a balance can always be explained.
• A job that would overdraw refuses to start. You get out_of_minutes before any model time is spent, not a surprise afterwards.

Top-ups

Prepaid minutes at $5, $25 and $100 — 20 minutes to the dollar, or $0.05 a video minute, carried over and never expiring — are coming soon and are not live. Nothing charges today. Pressing a price registers interest and says so. Free minutes are the only currency at launch.

• Videos are deleted when the job finishes. Success and failure alike, including failures we did not anticipate — deletion is in the path that always runs, not a line at the end of the happy one. The copy handed to the analysis service goes with it.
• Nothing you send to Fovea trains anything. Not your video, not your schema, not the result.
• The job row stays. Your schema, the JSON we returned, the duration and the charge. That is what GET /v1/jobs/{id} reads, and what makes a line on your balance explainable.