Examples

Server and models

These requests need no video. Use them to check that a server is up, which formats it renders and which models it can reach with the keys it has.

Health

GET/api/v1/healthCheck the server

Version, runtime, formats, and every provider and rung with whether it is enabled.

bash
curl https://vid2context.com/api/v1/health
Recorded response: 200 OK, 6 ms, 2026-11-14
content-type application/json
{
  "ok": true,
  "name": "vid2context",
  "version": "0.1.0",
  "runtime": "node",
  "formats": [
    {
      "id": "text",
      "description": "Plain transcript text. With timestamps, one \"[m:ss] line\" per caption.",
      "mimeType": "text/plain; charset=utf-8"
    },
    {
      "id": "json",
      "description": "The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.",
      "mimeType": "application/json"
    },
    {
      "id": "markdown",
      "description": "Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.",
      "mimeType": "text/markdown; charset=utf-8"
    },
    {
      "id": "srt",
      "description": "SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.",
      "mimeType": "application/x-subrip; charset=utf-8"
    },
    {
      "id": "vtt",
      "description": "WebVTT (.vtt) captions for the HTML <track> element, with speaker voice tags when known.",
      "mimeType": "text/vtt; charset=utf-8"
    },
    {
      "id": "pack",
      "description": "Context pack: one Markdown file for one or many videos, written for an AI model to read, with citation instructions. Options: maxTokens, includeComments, includeVisual, linkTimestamps.",
      "mimeType": "text/markdown; charset=utf-8"
    }
  ],
  "providers": [
    {
      "id": "bilibili",
      "kind": "source",
      "name": "Bilibili",
      "enabled": true
    },
    {
      "id": "bilibili-captions",
      "kind": "captions",
      "name": "Bilibili subtitles",
      "enabled": true
    },
    {
      "id": "cloudflare-ai-stt",
      "kind": "stt",
      "name": "Cloudflare Workers AI speech-to-text",
      "rungs": [
        {
          "id": "stt/cloudflare-binding/@cf/openai/whisper-large-v3-turbo",
          "service": "cloudflare-binding",
          "model": "@cf/openai/whisper-large-v3-turbo",
          "tier": "free",
          "enabled": false,
          "requires": [
            "CLOUDFLARE_AI_BINDING"
          ]
        },
        {
          "id": "stt/cloudflare-binding/@cf/openai/whisper",
          "service": "cloudflare-binding",
          "model": "@cf/openai/whisper",
          "tier": "free",
          "enabled": false,
          "requires": [
            "CLOUDFLARE_AI_BINDING"
          ]
        },
        {
          "id": "stt/cloudflare/@cf/openai/whisper-large-v3-turbo",
          "service": "cloudflare",
          "model": "@cf/openai/whisper-large-v3-turbo",
          "tier": "free",

841 more lines not shown. Run it to see the whole response.

enabled on a rung means its credentials are present and its tier is allowed. Keyless rungs need nothing, so a fresh server can already transcribe and answer questions.

Readiness

/healthz is for container probes. Without deep it only says the process is up, which is what a liveness probe wants. With deep=1 it checks everything a request needs and answers 503 when a required check fails, so a readiness probe holds traffic until the server can serve it.

GET/api/v1/healthzReadiness for a container probe

Without deep it only says the process is up. With deep=1 it checks storage, rungs, disk, yt-dlp, ffmpeg and the network, and answers 503 when a required check fails.

bash
curl -G https://vid2context.com/api/v1/healthz \
  --data-urlencode deep=1
Recorded response: 200 OK, 917 ms, 2026-11-15
content-type application/json
{
  "ok": true,
  "status": "ok",
  "checkedAt": "2026-11-15T15:29:16.862Z",
  "checks": [
    {
      "id": "storage",
      "status": "ok",
      "detail": "sqlite: write, read and delete ok",
      "required": true
    },
    {
      "id": "rungs",
      "status": "ok",
      "detail": "4 speech-to-text and 7 LLM rungs enabled, first stt/cloudflare/@cf/openai/whisper-large-v3-turbo and llm/cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "required": true
    },
    {
      "id": "disk",
      "status": "ok",
      "detail": "774948 MB free in the data directory",
      "required": true
    },
    {
      "id": "yt-dlp",
      "status": "ok",
      "detail": "2026.10.26",
      "required": false
    },
    {
      "id": "ffmpeg",
      "status": "ok",
      "detail": "7.0.2-static",
      "required": false
    },
    {
      "id": "network",
      "status": "ok",
      "detail": "oai.endpoints.kepler.ai.cloud.ovh.net answered HTTP 200",
      "required": false
    }
  ],
  "version": "0.1.0"
}

Formats

GET/api/v1/formatsList the output formats
bash
curl https://vid2context.com/api/v1/formats
Recorded response: 200 OK, 3 ms, 2026-11-14
content-type application/json
{
  "formats": [
    {
      "id": "text",
      "description": "Plain transcript text. With timestamps, one \"[m:ss] line\" per caption.",
      "mimeType": "text/plain; charset=utf-8",
      "extension": "txt"
    },
    {
      "id": "json",
      "description": "The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.",
      "mimeType": "application/json",
      "extension": "json"
    },
    {
      "id": "markdown",
      "description": "Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.",
      "mimeType": "text/markdown; charset=utf-8",
      "extension": "md"
    },
    {
      "id": "srt",
      "description": "SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.",
      "mimeType": "application/x-subrip; charset=utf-8",
      "extension": "srt"
    },
    {
      "id": "vtt",
      "description": "WebVTT (.vtt) captions for the HTML <track> element, with speaker voice tags when known.",
      "mimeType": "text/vtt; charset=utf-8",
      "extension": "vtt"
    },
    {
      "id": "pack",
      "description": "Context pack: one Markdown file for one or many videos, written for an AI model to read, with citation instructions. Options: maxTokens, includeComments, includeVisual, linkTimestamps.",
      "mimeType": "text/markdown; charset=utf-8",
      "extension": "md"
    }
  ]
}

Models

GET/api/v1/modelsList the models

Every rung, enabled or not. requires names env vars, never their values.

bash
curl -G https://vid2context.com/api/v1/models \
  --data-urlencode kind=stt
Recorded response: 200 OK, 3 ms, 2026-11-14
content-type application/json
{
  "models": [
    {
      "id": "stt/cloudflare-binding/@cf/openai/whisper-large-v3-turbo",
      "kind": "stt",
      "label": "whisper-large-v3-turbo",
      "service": "cloudflare-binding",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper-large-v3-turbo",
      "tier": "free",
      "quality": 4,
      "capabilities": [
        "segments",
        "words",
        "language-detect",
        "prompt"
      ],
      "enabled": false,
      "requires": [
        "CLOUDFLARE_AI_BINDING"
      ]
    },
    {
      "id": "stt/cloudflare-binding/@cf/openai/whisper",
      "kind": "stt",
      "label": "whisper",
      "service": "cloudflare-binding",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper",
      "tier": "free",
      "quality": 2,
      "capabilities": [
        "segments",
        "words"
      ],
      "enabled": false,
      "requires": [
        "CLOUDFLARE_AI_BINDING"
      ]
    },
    {
      "id": "stt/cloudflare/@cf/openai/whisper-large-v3-turbo",
      "kind": "stt",
      "label": "whisper-large-v3-turbo",
      "service": "cloudflare",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper-large-v3-turbo",
      "tier": "free",
      "quality": 4,
      "capabilities": [
        "segments",
        "words",
        "language-detect",
        "prompt"
      ],
      "enabled": true,
      "requires": [
        "CLOUDFLARE_ACCOUNT_ID",
        "CLOUDFLARE_API_TOKEN"
      ]
    },
    {
      "id": "stt/cloudflare/@cf/openai/whisper",
      "kind": "stt",
      "label": "whisper",
      "service": "cloudflare",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper",
      "tier": "free",
      "quality": 2,
      "capabilities": [
        "segments",
        "words"
      ],
      "enabled": true,
      "requires": [
        "CLOUDFLARE_ACCOUNT_ID",
        "CLOUDFLARE_API_TOKEN"
      ]
    },

179 more lines not shown. Run it to see the whole response.

Pick a kind to narrow the list. The same rows, grouped by tier, are in Providers and rungs.

Where examples run

Any vid2context server: your own deployment, or one started from a clone of the repo with VID2CONTEXT_CORS_ORIGINS=this origin npm run start:server (it listens on http://127.0.0.1:8787). The CORS variable lets this page read its responses.

Only for servers that set VID2CONTEXT_API_KEYS. Sent as Authorization: Bearer, kept in this tab's session storage, and never written into the snippets (they read $VID2CONTEXT_API_KEY).