framefetch

Extract data from ONE public social-video URL (YouTube incl. Shorts, TikTok, Instagram Reels, Pinterest, Reddit): metadata/insights/transcript/frames/digest/comments/etc — see `fields`. When NOT to use: non-video pages, private/login-walled content, or bulk crawling (one URL per call). Returns one JSON object with only the requested fields + a `cost` block (micro-USD); shapes: https://framefetch.net/docs. Cost scales with what you request (frames/transcript cost more than metadata). No key? POST /v1/keys {email} -> instant key (~100 free calls); or x402 (USDC), no account. Example: {"url":"https://www.youtube.com/watch?v=...","fields":["metadata","transcript"]}.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public video URL from a supported platform."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "metadata",
          "insights",
          "transcript",
          "frames",
          "text_overlay",
          "digest",
          "audio_digest",
          "structured",
          "comments",
          "comment_sentiment",
          "delta"
        ]
      },
      "description": "Which data to return; default [\"metadata\"]. Pulls: digest→transcript; audio_digest→digest→transcript; structured→transcript; comment_sentiment→comments. digest/audio_digest/structured/comment_sentiment: degrade to a warning, never charged, on failure. digest: gist+topics via LLM. audio_digest: mp3 of digest (signed URL, 24h); voice via `voice`; +`translate` for other-language audio. structured: chapters/entities/products_shown/claims/key_moments via vision LLM. comments: up to comments_cap; YouTube only (else warning; see GET /v1/platforms). comment_sentiment: aggregated audience sentiment (positive_pct/neutral_pct/negative_pct/summary/top_themes); needs >=5 comments; same YouTube-only limit. text_overlay: OCR per frame; requires \"frames\"; skipped above 200 frames. delta: velocity vs the previous fetch; first call seeds the baseline. Docs: https://framefetch.net/docs."
    },
    "frames": {
      "type": "object",
      "description": "Frame-sampling spec; required when \"frames\" or \"text_overlay\" is requested.",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "all",
            "every_n",
            "fps",
            "range"
          ]
        },
        "n": {
          "type": "number",
          "description": "every_n: take every Nth source frame"
        },
        "fps": {
          "type": "number",
          "description": "fps/range: frames per second (max 60)"
        },
        "from": {
          "type": "number",
          "description": "range: start second"
        },
        "to": {
          "type": "number",
          "description": "range: end second"
        },
        "format": {
          "type": "string",
          "enum": [
            "jpg",
            "png",
            "webp"
          ]
        },
        "width": {
          "type": "number",
          "description": "downscale width in px (16–7680)"
        }
      },
      "required": [
        "mode"
      ]
    },
    "translate": {
      "type": "string",
      "description": "ISO-639-1 target language (e.g. \"es\"); adds `transcript_translated` (timings kept). Requires \"transcript\" (or \"digest\"). Billed per audio-minute."
    },
    "subtitle_format": {
      "type": "string",
      "enum": [
        "srt",
        "vtt"
      ],
      "description": "Renders transcript as subtitles in `subtitles` (srt/vtt). Requires \"transcript\" (or \"digest\"); uses translated cues if \"translate\" set."
    },
    "voice": {
      "type": "string",
      "enum": [
        "alloy",
        "echo",
        "fable",
        "onyx",
        "nova",
        "shimmer",
        "Fritz-PlayAI"
      ],
      "description": "Voice for \"audio_digest\": OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) + Groq \"Fritz-PlayAI\"; default \"alloy\"."
    },
    "comments_cap": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Max top-level comments (1-200, default 30); only used with \"comments\"."
    },
    "ask": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`. No transcript (e.g. Pinterest): falls back to frames, `based_on`:[\"frames\"]."
    },
    "cache": {
      "type": "boolean",
      "description": "false forces a fresh, billed extract."
    }
  },
  "required": [
    "url"
  ]
}

JSON matrix of data types (metadata, insights, transcript, frames, comments) per platform — YouTube (+Shorts), TikTok, Instagram Reels, Pinterest, Reddit. Call before framefetch_extract to confirm support. No input.

{
  "type": "object",
  "properties": {}
}

Search YouTube by keyword (yt-dlp, no login). Returns up to `limit` hits: url/title/uploader/durationSec/uploadDate(often null)/thumbnail/views. YouTube only — use framefetch_extract on a hit's url for transcript/frames/etc. Billed ~$0.002/call (metadata-tier), regardless of `limit`.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "2-200 chars."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "Default 10."
    },
    "platform": {
      "type": "string",
      "enum": [
        "youtube"
      ]
    },
    "cache": {
      "type": "boolean",
      "description": "false = fresh, billed search."
    }
  },
  "required": [
    "query"
  ]
}

Check this account's credit balance/usage. Read-only — never charges; works at zero balance (unlike framefetch_extract). Purpose: check balance before expensive framefetch_extract calls — at session start, periodically, or after a 402. When NOT to use: before every single framefetch_extract call in a tight loop. Returns: balance_micros, spend_7d_micros, calls_7d — micro-USD (1,000,000 = $1). Low balance: top up via x402 (USDC) at POST /v1/topup, or card at POST /v1/checkout.

{
  "type": "object",
  "properties": {}
}