ExtractRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/framefetch-net/json-schema/framefetch-net-extract-request-schema.json",
  "title": "ExtractRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/framefetch-net-openapi.json#/components/schemas/ExtractRequest",
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "metadata",
          "insights",
          "transcript",
          "frames",
          "text_overlay",
          "digest",
          "audio_digest",
          "structured",
          "comments",
          "comment_sentiment",
          "delta"
        ]
      },
      "default": [
        "metadata"
      ],
      "description": "digest (LLM summary of the transcript) auto-includes transcript and degrades gracefully if none is available. audio_digest (a spoken mp3 briefing synthesized from the digest gist) auto-includes digest (and thus transcript); it returns a time-limited signed URL plus the voice/provider used, is billed per estimated spoken second only when the mp3 is actually produced, and degrades to a warning (never charged, never a hard error) when no TTS provider is configured or the requested language isn't supported by the only configured provider. When translate is also set, the digest is generated directly in that target language so the audio speaks it too — combine audio_digest with translate for a foreign-language briefing from one call. structured (typed JSON understanding of the video: chapters, entities, products_shown, claims, key_moments) auto-includes transcript and also triggers the engine's own keyframe pass over the source video, so it works even on caption-less sources; a single gpt-4o-mini vision call over the transcript plus up to 12 sampled keyframes, run at temperature 0 so the result is deterministic and cacheable; a flat $0.03 per video, charged only when the analysis is actually produced (a download/VLM/parse failure omits the field with a warning and is NOT charged — see StructuredError codes STRUCTURED_UNAVAILABLE, STRUCTURED_PROVIDER_ERROR, STRUCTURED_PARSE_ERROR on VideoStructured below). comments returns up to comments_cap top-level comments per video ({ items: [{ text, author?, like_count?, reply_count? }], total_fetched, cap_applied, sort:\"top\" }); it is INDEPENDENT of the transcript (no download) and available on YouTube only — Reddit's unauthenticated comment API was deprecated on 2026-05-28 and now returns a hard 403, so Reddit omits the field exactly like TikTok/Instagram/Pinterest, with a warning and never a charge (see GET /v1/platforms and COMMENTS_UNSUPPORTED on VideoComments below). Author is a display handle only (no user ids/urls). Flat $0.0045 per call, charged only when comments were actually produced. comment_sentiment (aggregated audience sentiment: percentages, themes, summary — ONE LLM pass over the comments) auto-includes comments (its input; same YouTube-only availability, Reddit's source having been deprecated) and needs at least 5 fetched comments — fewer, or a model/parse failure, omits it with a warning and is never charged (see CommentSentiment below). Flat $0.006 per call, on top of the comments call it rides on. No competitor offers this rollup. delta (change vs the most-recent prior fetch of the same url: engagement velocity per hour + title/thumbnail-change flags) is never cached and returns hasPrior:false the first time a url is seen. text_overlay (on-screen text via OCR) requires frames to also be requested, with a frames spec. Auto-skipped with a warning above 200 estimated frames."
    },
    "frames": {
      "$ref": "#/$defs/FrameSpec"
    },
    "verbosity": {
      "type": "string"
    },
    "translate": {
      "type": "string",
      "description": "Optional ISO-639-1 target language code (e.g. \"es\", \"de\", \"ja\") to also translate the transcript into, surfaced as transcript_translated (with timings preserved when the source transcript had them). Requires \"transcript\" in fields (or \"digest\", which pulls transcript in). Billed per audio-minute like transcription — even for caption-sourced transcripts, since the translation is a separate LLM pass. Supported: en, es, de, fr, pt, it, nl, pl, tr, ru, uk, ar, hi, id, vi, th, ja, ko, zh, sv, da, no, fi, cs, ro (25 languages)."
    },
    "voice": {
      "type": "string",
      "enum": [
        "alloy",
        "echo",
        "fable",
        "onyx",
        "nova",
        "shimmer",
        "Fritz-PlayAI"
      ],
      "default": "alloy",
      "description": "Spoken voice for the \"audio_digest\" field: the six OpenAI gpt-4o-mini-tts voices (alloy, echo, fable, onyx, nova, shimmer — multilingual) plus Groq/PlayAI's \"Fritz-PlayAI\" (English/Arabic-only fallback, used when no OpenAI key is configured). Defaults to \"alloy\". Inert unless \"audio_digest\" is requested; an unlisted value is a typed 400 that echoes this allowlist."
    },
    "comments_cap": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 30,
      "description": "Max number of top-level comments the \"comments\" field returns (1–200, default 30). Inert unless \"comments\" (or \"comment_sentiment\", which auto-includes it) is requested; a value outside 1–200 is a 400 INVALID_PARAMS."
    },
    "publish": {
      "type": "boolean",
      "default": false,
      "description": "Opt in to a public, shareable per-video SEO page at /v/<id> (a stable hash of the url). Publishes ONLY public metadata plus a short fair-use transcript excerpt — never the full transcript or a signed frame URL. Pages carry VideoObject structured data and are listed in /sitemap-videos.xml. Best-effort; never affects the API response."
    }
  },
  "$defs": {
    "FrameSpec": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "all",
            "every_n",
            "fps",
            "range"
          ]
        },
        "n": {
          "type": "integer",
          "minimum": 1
        },
        "fps": {
          "type": "number",
          "maximum": 60
        },
        "from": {
          "type": "number"
        },
        "to": {
          "type": "number"
        },
        "format": {
          "type": "string",
          "enum": [
            "jpg",
            "png",
            "webp"
          ]
        },
        "width": {
          "type": "integer",
          "minimum": 16,
          "maximum": 7680
        }
      }
    }
  }
}