framefetch

Previous value: -"Max top-level comments (1-200, default 100); only used with \"comments\"."New value: +"Max top-level comments (1-200, default 30); only used with \"comments\"."

Removed value: -{
-  "enum": [
-    "concise",
-    "detailed"
-  ],
-  "type": "string"
-}

Added value: +{
+  "description": "false forces a fresh, billed extract.",
+  "type": "boolean"
+}

Previous value: -"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`."New value: +"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\"]."

Previous value: -"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."New value: +"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`."

Previous value: -"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+Reddit 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+Reddit 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."New value: +"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."

Previous value: -"A question about the video (3-500 chars); returns a <=500-token answer grounded in the transcript with timestamped supporting quotes ({ answer, quotes: [{ t_sec, text }], confidence, based_on }) instead of a full transcript dump, auto-including \"transcript\" as its input, never served from the cache (a fresh answer every call, even when the underlying extraction is otherwise cached), and degrading gracefully (omitted, never charged) if no transcript is available or the model fails."New value: +"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."

Previous value: -"Max number of top-level comments the \"comments\" field returns (1–200, default 100). Inert unless \"comments\" is requested."New value: +"Max top-level comments (1-200, default 100); only used with \"comments\"."

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"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 and Reddit only — TikTok/Instagram/Pinterest return it as a warning, never a charge (check GET /v1/platforms). Author is a display handle only (no user ids/urls). \"comment_sentiment\" is aggregated audience sentiment: percentages, themes, summary — ONE LLM pass over the comments returns { positive_pct, neutral_pct, negative_pct (they sum to 100), summary (2-3 English sentences), top_themes (up to 5), representative { positive?, negative? } }. It automatically pulls in \"comments\" (its input; same YouTube/Reddit-only availability) and needs at least 5 comments — fewer, or a model failure, omits it with a warning and is never charged. No competitor offers this rollup. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"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+Reddit 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+Reddit 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."

Previous value: -"If set, also render the transcript as a subtitle file and add it as a top-level \"subtitles\" string (\"srt\" = SubRip, \"vtt\" = WebVTT). Requires \"transcript\" in fields (or \"digest\", which pulls it in); uses the translated cues when \"translate\" is set. Does not change any other field or the cost."New value: +"Renders transcript as subtitles in `subtitles` (srt/vtt). Requires \"transcript\" (or \"digest\"); uses translated cues if \"translate\" set."

Previous value: -"ISO-639-1 target language (e.g. \"es\", \"de\", \"ja\"); adds transcript_translated (the transcript translated into that language, with timings preserved). Requires \"transcript\" in fields (or \"digest\", which pulls transcript in). Billed per audio-minute like transcription, even for caption-sourced transcripts."New value: +"ISO-639-1 target language (e.g. \"es\"); adds `transcript_translated` (timings kept). Requires \"transcript\" (or \"digest\"). Billed per audio-minute."

Previous value: -"Spoken voice for the \"audio_digest\" field. The six OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) plus Groq/PlayAI's \"Fritz-PlayAI\". Defaults to \"alloy\". Inert unless \"audio_digest\" is requested."New value: +"Voice for \"audio_digest\": OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) + Groq \"Fritz-PlayAI\"; default \"alloy\"."

Added value: +{
+  "description": "A question about the video (3-500 chars); returns a <=500-token answer grounded in the transcript with timestamped supporting quotes ({ answer, quotes: [{ t_sec, text }], confidence, based_on }) instead of a full transcript dump, auto-including \"transcript\" as its input, never served from the cache (a fresh answer every call, even when the underlying extraction is otherwise cached), and degrading gracefully (omitted, never charged) if no transcript is available or the model fails.",
+  "maxLength": 500,
+  "minLength": 3,
+  "type": "string"
+}

Added value: +{
+  "description": "Max number of top-level comments the \"comments\" field returns (1–200, default 100). Inert unless \"comments\" is requested.",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"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 and Reddit only — TikTok/Instagram/Pinterest return it as a warning, never a charge (check GET /v1/platforms). Author is a display handle only (no user ids/urls). \"comment_sentiment\" is aggregated audience sentiment: percentages, themes, summary — ONE LLM pass over the comments returns { positive_pct, neutral_pct, negative_pct (they sum to 100), summary (2-3 English sentences), top_themes (up to 5), representative { positive?, negative? } }. It automatically pulls in \"comments\" (its input; same YouTube/Reddit-only availability) and needs at least 5 comments — fewer, or a model failure, omits it with a warning and is never charged. No competitor offers this rollup. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."

Previous value: -[
-  "metadata",
-  "insights",
-  "transcript",
-  "frames",
-  "text_overlay",
-  "digest",
-  "audio_digest",
-  "structured",
-  "delta"
-]New value: +[
+  "metadata",
+  "insights",
+  "transcript",
+  "frames",
+  "text_overlay",
+  "digest",
+  "audio_digest",
+  "structured",
+  "comments",
+  "comment_sentiment",
+  "delta"
+]

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."

Previous value: -[
-  "metadata",
-  "insights",
-  "transcript",
-  "frames",
-  "text_overlay",
-  "digest",
-  "audio_digest",
-  "delta"
-]New value: +[
+  "metadata",
+  "insights",
+  "transcript",
+  "frames",
+  "text_overlay",
+  "digest",
+  "audio_digest",
+  "structured",
+  "delta"
+]

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."

Previous value: -[
-  "metadata",
-  "insights",
-  "transcript",
-  "frames",
-  "text_overlay",
-  "digest",
-  "delta"
-]New value: +[
+  "metadata",
+  "insights",
+  "transcript",
+  "frames",
+  "text_overlay",
+  "digest",
+  "audio_digest",
+  "delta"
+]

Added value: +{
+  "description": "Spoken voice for the \"audio_digest\" field. The six OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) plus Groq/PlayAI's \"Fritz-PlayAI\". Defaults to \"alloy\". Inert unless \"audio_digest\" is requested.",
+  "enum": [
+    "alloy",
+    "echo",
+    "fable",
+    "onyx",
+    "nova",
+    "shimmer",
+    "Fritz-PlayAI"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "If set, also render the transcript as a subtitle file and add it as a top-level \"subtitles\" string (\"srt\" = SubRip, \"vtt\" = WebVTT). Requires \"transcript\" in fields (or \"digest\", which pulls it in); uses the translated cues when \"translate\" is set. Does not change any other field or the cost.",
+  "enum": [
+    "srt",
+    "vtt"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "ISO-639-1 target language (e.g. \"es\", \"de\", \"ja\"); adds transcript_translated (the transcript translated into that language, with timings preserved). Requires \"transcript\" in fields (or \"digest\", which pulls transcript in). Billed per audio-minute like transcription, even for caption-sourced transcripts.",
+  "type": "string"
+}

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."

Previous value: -[
-  "metadata",
-  "insights",
-  "transcript",
-  "frames",
-  "text_overlay"
-]New value: +[
+  "metadata",
+  "insights",
+  "transcript",
+  "frames",
+  "text_overlay",
+  "digest",
+  "delta"
+]

Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it."

Previous value: -[
-  "metadata",
-  "insights",
-  "transcript",
-  "frames"
-]New value: +[
+  "metadata",
+  "insights",
+  "transcript",
+  "frames",
+  "text_overlay"
+]

Previous value: -"Frame-sampling spec; required when \"frames\" is requested."New value: +"Frame-sampling spec; required when \"frames\" or \"text_overlay\" is requested."