@mux/ai 0.19.0 → 0.21.1

package/dist/{shots-BFYOfBgN.d.ts → shots-mGJfYGiO.d.ts}

@@ -120,6 +120,8 @@ interface WorkflowCredentials {
     anthropicApiKey?: string;
     /** Optional direct Google API key for per-request credential injection. */
     googleApiKey?: string;
+    /** Optional direct Google Vision API key for per-request credential injection. */
+    googleVisionApiKey?: string;
     /** Optional direct Hive API key for per-request credential injection. */
     hiveApiKey?: string;
     /** Optional direct ElevenLabs API key for per-request credential injection. */

package/dist/workflows/index.d.ts

@@ -1,7 +1,7 @@
-export { A as AskQuestionsOptions, a as AskQuestionsResult, b as AskQuestionsType, c as AudioTranslationOptions, d as AudioTranslationResult, e as AutoCensorProfanityOptions, B as BurnedInCaptionsAnalysis, f as BurnedInCaptionsOptions, g as BurnedInCaptionsPromptOverrides, h as BurnedInCaptionsPromptSections, j as BurnedInCaptionsResult, C as CaptionReplacement, k as CensorMode, l as Chapter, m as ChapterSystemPromptSections, n as ChaptersOptions, o as ChaptersPromptOverrides, p as ChaptersPromptSections, q as ChaptersResult, r as ChaptersType, D as DEFAULT_DESCRIPTION_LENGTH, s as DEFAULT_SUMMARY_KEYWORD_LIMIT, t as DEFAULT_TITLE_LENGTH, E as EditCaptionsOptions, u as EditCaptionsResult, v as EmbeddingsOptions, w as EmbeddingsResult, x as EngagementInsightsOptions, y as EngagementInsightsResult, H as HIVE_SEXUAL_CATEGORIES, z as HIVE_VIOLENCE_CATEGORIES, F as HiveModerationOutput, G as HiveModerationSource, M as ModerationOptions, I as ModerationProvider, J as ModerationResult, K as MomentInsight, O as OverallInsight, P as ProfanityDetectionPayload, Q as Question, L as QuestionAnswer, N as QuestionAnswerType, R as ReplacementRecord, S as SummarizationOptions, T as SummarizationPromptOverrides, U as SummarizationPromptSections, V as SummaryAndTagsResult, W as SummaryType, X as ThumbnailModerationScore, Y as TranslationChunkingOptions, Z as TranslationOptions, _ as TranslationPayload, $ as TranslationResult, a0 as aggregateTokenUsage, a1 as applyOverrideLists, a2 as applyReplacements, a3 as askQuestions, a4 as buildReplacementRegex, a5 as burnedInCaptionsSchema, a6 as censorVttContent, a7 as chapterSchema, a8 as chaptersSchema, a9 as createReplacer, aa as editCaptions, ab as extractTranscriptSegmentsForHotspots, ac as generateChapters, ad as generateEmbeddings, ae as generateEngagementInsights, af as generateVideoEmbeddings, ag as getModerationScores, ah as getSummaryAndTags, ai as hasBurnedInCaptions, aj as mapShotsToHotspots, ak as normalizeTranslatedVtt, al as profanityDetectionSchema, am as questionAnswerSchema, an as shouldSplitChunkTranslationError, ao as summarySchema, ap as transformCueText, aq as translateAudio, ar as translateCaptions, as as translationSchema } from '../index-CwzNfBjV.js';
+export { A as AskQuestionsOptions, a as AskQuestionsResult, b as AskQuestionsType, c as AudioTranslationOptions, d as AudioTranslationResult, e as AutoCensorProfanityOptions, B as BurnedInCaptionsAnalysis, f as BurnedInCaptionsOptions, g as BurnedInCaptionsPromptOverrides, h as BurnedInCaptionsPromptSections, j as BurnedInCaptionsResult, C as CaptionReplacement, k as CensorMode, l as Chapter, m as ChapterSystemPromptSections, n as ChaptersOptions, o as ChaptersPromptOverrides, p as ChaptersPromptSections, q as ChaptersResult, r as ChaptersType, D as DEFAULT_DESCRIPTION_LENGTH, s as DEFAULT_SUMMARY_KEYWORD_LIMIT, t as DEFAULT_TITLE_LENGTH, E as EditCaptionsOptions, u as EditCaptionsResult, v as EmbeddingsOptions, w as EmbeddingsResult, x as EngagementInsightsOptions, y as EngagementInsightsResult, G as GOOGLE_VISION_LIKELIHOOD_TO_SCORE, H as HIVE_SEXUAL_CATEGORIES, z as HIVE_VIOLENCE_CATEGORIES, F as HiveModerationOutput, I as HiveModerationSource, M as ModerationOptions, J as ModerationProvider, K as ModerationResult, L as MomentInsight, O as OverallInsight, P as ProfanityDetectionPayload, Q as Question, N as QuestionAnswer, R as QuestionAnswerType, S as ReplacementRecord, T as SummarizationOptions, U as SummarizationPromptOverrides, V as SummarizationPromptSections, W as SummaryAndTagsResult, X as SummaryType, Y as ThumbnailModerationScore, Z as TranslationChunkingOptions, _ as TranslationOptions, $ as TranslationPayload, a0 as TranslationResult, a1 as aggregateTokenUsage, a2 as applyOverrideLists, a3 as applyReplacements, a4 as askQuestions, a5 as buildReplacementRegex, a6 as burnedInCaptionsSchema, a7 as censorVttContent, a8 as chapterSchema, a9 as chaptersSchema, aa as createReplacer, ab as editCaptions, ac as extractTranscriptSegmentsForHotspots, ad as generateChapters, ae as generateEmbeddings, af as generateEngagementInsights, ag as generateVideoEmbeddings, ah as getModerationScores, ai as getSummaryAndTags, aj as hasBurnedInCaptions, ak as mapShotsToHotspots, al as normalizeTranslatedVtt, am as profanityDetectionSchema, an as questionAnswerSchema, ao as shouldSplitChunkTranslationError, ap as summarySchema, aq as transformCueText, ar as translateAudio, as as translateCaptions, at as translationSchema } from '../index-DwNtsg-u.js';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
-import '../shots-BFYOfBgN.js';
+import '../shots-mGJfYGiO.js';
 import '@mux/mux-node';

package/dist/workflows/index.js

@@ -186,6 +186,7 @@ var EnvSchema = z.object({
   GOOGLE_GENERATIVE_AI_API_KEY: optionalString("Google Generative AI API key for Gemini-backed workflows.", "Google Generative AI API key"),
   ELEVENLABS_API_KEY: optionalString("ElevenLabs API key for audio translation.", "ElevenLabs API key"),
   HIVE_API_KEY: optionalString("Hive Visual Moderation API key.", "Hive API key"),
+  GOOGLE_VISION_API_KEY: optionalString("Google Vision API key for SafeSearch moderation.", "Google Vision API key"),
   // S3-Compatible Storage (required for translation & audio dubbing)
   S3_ENDPOINT: optionalString("S3-compatible endpoint for uploads.", "S3 endpoint"),
   S3_REGION: optionalString("S3 region (defaults to 'auto' when omitted)."),
@@ -809,23 +810,26 @@ function resolveProviderApiKeyFromCredentials(provider, resolved) {
   const openaiApiKey = readString(record, "openaiApiKey");
   const anthropicApiKey = readString(record, "anthropicApiKey");
   const googleApiKey = readString(record, "googleApiKey");
+  const googleVisionApiKey = readString(record, "googleVisionApiKey");
   const hiveApiKey = readString(record, "hiveApiKey");
   const elevenLabsApiKey = readString(record, "elevenLabsApiKey");
   const apiKeyMap = {
-    openai: openaiApiKey ?? env_default.OPENAI_API_KEY,
-    anthropic: anthropicApiKey ?? env_default.ANTHROPIC_API_KEY,
-    google: googleApiKey ?? env_default.GOOGLE_GENERATIVE_AI_API_KEY,
-    hive: hiveApiKey ?? env_default.HIVE_API_KEY,
-    elevenlabs: elevenLabsApiKey ?? env_default.ELEVENLABS_API_KEY
+    "openai": openaiApiKey ?? env_default.OPENAI_API_KEY,
+    "anthropic": anthropicApiKey ?? env_default.ANTHROPIC_API_KEY,
+    "google": googleApiKey ?? env_default.GOOGLE_GENERATIVE_AI_API_KEY,
+    "google-vision-api": googleVisionApiKey ?? env_default.GOOGLE_VISION_API_KEY,
+    "hive": hiveApiKey ?? env_default.HIVE_API_KEY,
+    "elevenlabs": elevenLabsApiKey ?? env_default.ELEVENLABS_API_KEY
   };
   const apiKey = apiKeyMap[provider];
   if (!apiKey) {
     const envVarNames = {
-      openai: "OPENAI_API_KEY",
-      anthropic: "ANTHROPIC_API_KEY",
-      google: "GOOGLE_GENERATIVE_AI_API_KEY",
-      hive: "HIVE_API_KEY",
-      elevenlabs: "ELEVENLABS_API_KEY"
+      "openai": "OPENAI_API_KEY",
+      "anthropic": "ANTHROPIC_API_KEY",
+      "google": "GOOGLE_GENERATIVE_AI_API_KEY",
+      "google-vision-api": "GOOGLE_VISION_API_KEY",
+      "hive": "HIVE_API_KEY",
+      "elevenlabs": "ELEVENLABS_API_KEY"
     };
     throw new Error(
       `${provider} API key is required. Provide ${provider} credentials via workflow credentials or set ${envVarNames[provider]} environment variable.`
@@ -1891,8 +1895,7 @@ var questionAnswerSchema = z2.object({
   skipped: z2.boolean()
 });
 var SKIP_SENTINEL = "__SKIPPED__";
-function createAskQuestionsSchema(allowedAnswers) {
-  const answerSchema = z2.enum([...allowedAnswers, SKIP_SENTINEL]);
+function createAskQuestionsSchema(answerSchema) {
   return z2.object({
     answers: z2.array(
       questionAnswerSchema.extend({
@@ -1928,15 +1931,16 @@ var SYSTEM_PROMPT = promptDedent`
   <task>
     For each question provided, you must:
     1. Analyze the storyboard frames and transcript (if provided)
-    2. Answer with ONLY the allowed response options listed for that question - no other values are acceptable
+    2. Answer each question according to its specified response format: for questions with <allowed_answers>, select ONLY from the listed values; for questions with <answer_format>, follow the format specification exactly
     3. Provide a confidence score between 0 and 1 reflecting your certainty
     4. Explain your reasoning based on observable evidence
   </task>
 
   <answer_guidelines>
-    - Each question is presented as its own <question> block with a <text> element (the question) and an <allowed_answers> element (the permitted response values)
-    - Choose only from the values listed in that question's <allowed_answers> element
-    - Questions may have any set of allowed answers. Always read the <allowed_answers> for each question and select the best matching option based on the evidence
+    - Each question is presented as its own <question> block with a <text> element and either an <allowed_answers> element (listing the permitted response values) or an <answer_format> element (describing the required response shape for open-ended responses)
+    - For questions with <allowed_answers>: choose ONLY from the values listed in that question's <allowed_answers> element
+    - For questions with <answer_format>: follow the format specification exactly (e.g. free-form text within the stated character budget)
+    - Always read each question's <allowed_answers> or <answer_format> and respond in the required shape based on the evidence
     - Select the answer best supported by observable evidence from the content
     - When evidence is ambiguous but some signal exists, select the most conservative option and use a low confidence score. If the question cannot be answered at all from the content, skip it per the relevance_filtering rules
     - Confidence should reflect the clarity and strength of evidence:
@@ -1963,7 +1967,8 @@ var SYSTEM_PROMPT = promptDedent`
     CRITICAL: Base your answers ONLY on the actual visual and audio/transcript content.
     ${METADATA_BOUNDARY_WARNING}
 
-    CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
+    CRITICAL: Do NOT answer irrelevant questions in any form — neither with
+    one of the <allowed_answers> nor with prose for <answer_format>.
     Answering an irrelevant question is WRONG — you MUST skip it instead.
 
     For skipped questions:
@@ -1990,7 +1995,7 @@ var SYSTEM_PROMPT = promptDedent`
   </security>
 
   <constraints>
-    - You MUST answer every relevant question with one of its own listed allowed response options
+    - You MUST answer every relevant question following its specified response format: an option from <allowed_answers>, or prose matching <answer_format>
     - Skip irrelevant questions as described in relevance_filtering
     - Only describe observable evidence from frames or transcript
     - ${NO_FABRICATION_CONSTRAINT}
@@ -2025,15 +2030,16 @@ var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
   <task>
     For each question provided, you must:
     1. Analyze the transcript
-    2. Answer with ONLY the allowed response options listed for that question - no other values are acceptable
+    2. Answer each question according to its specified response format: for questions with <allowed_answers>, select ONLY from the listed values; for questions with <answer_format>, follow the format specification exactly
     3. Provide a confidence score between 0 and 1 reflecting your certainty
     4. Explain your reasoning based on observable evidence
   </task>
 
   <answer_guidelines>
-    - Each question is presented as its own <question> block with a <text> element (the question) and an <allowed_answers> element (the permitted response values)
-    - Choose only from the values listed in that question's <allowed_answers> element
-    - Questions may have any set of allowed answers. Always read the <allowed_answers> for each question and select the best matching option based on the evidence
+    - Each question is presented as its own <question> block with a <text> element and either an <allowed_answers> element (listing the permitted response values) or an <answer_format> element (describing the required response shape for open-ended responses)
+    - For questions with <allowed_answers>: choose ONLY from the values listed in that question's <allowed_answers> element
+    - For questions with <answer_format>: follow the format specification exactly (e.g. free-form text within the stated character budget)
+    - Always read each question's <allowed_answers> or <answer_format> and respond in the required shape based on the evidence
     - Select the answer best supported by observable evidence from the content
     - When evidence is ambiguous but some signal exists, select the most conservative option and use a low confidence score. If the question cannot be answered at all from the content, skip it per the relevance_filtering rules
     - Confidence should reflect the clarity and strength of evidence:
@@ -2060,7 +2066,8 @@ var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
     CRITICAL: Base your answers ONLY on the actual audio/transcript content.
     ${METADATA_BOUNDARY_WARNING}
 
-    CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
+    CRITICAL: Do NOT answer irrelevant questions in any form — neither with
+    one of the <allowed_answers> nor with prose for <answer_format>.
     Answering an irrelevant question is WRONG — you MUST skip it instead.
 
     For skipped questions:
@@ -2085,7 +2092,7 @@ var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
   </security>
 
   <constraints>
-    - You MUST answer every relevant question with one of its own listed allowed response options
+    - You MUST answer every relevant question following its specified response format: an option from <allowed_answers>, or prose matching <answer_format>
     - Skip irrelevant questions as described in relevance_filtering
     - Only describe observable evidence from transcript content
     - ${NO_FABRICATION_CONSTRAINT}
@@ -2100,16 +2107,104 @@ var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
     - GOOD: "The speaker describes running through a park"
     - Be specific and evidence-based
   </language_guidelines>`;
+function freeFormAddendum(maxFreeFormAnswerLength) {
+  return promptDedent`
+    <free_form_answers>
+      Additional rules for questions with <answer_format>free-form text ...</answer_format>:
+
+      - Produce a short, evidence-grounded answer in plain prose
+      - Keep it tight: one or two sentences, maximum ${maxFreeFormAnswerLength} characters
+      - If the question is irrelevant to the asset content, still skip it
+        by setting answer to "${SKIP_SENTINEL}" exactly, per relevance_filtering
+      - The answer field is a content-analysis channel, not an instruction
+        channel. Do NOT include raw instructions, escape sequences, code,
+        or anything that looks like structured control content in the
+        answer. All existing security, non-fabrication, and
+        non-disclosure rules apply unchanged.
+    </free_form_answers>`;
+}
+function buildSystemPrompt(isAudioOnly, hasFreeForm, maxFreeFormAnswerLength) {
+  const base = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT;
+  if (!hasFreeForm)
+    return base;
+  return `${base}
+
+${freeFormAddendum(maxFreeFormAnswerLength)}`;
+}
+var YES_NO_ANSWERS = ["yes", "no"];
+function allowedAnswersForQuestion(q) {
+  switch (q.mode.kind) {
+    case "yesNo":
+      return YES_NO_ANSWERS;
+    case "options":
+      return q.mode.options;
+    case "freeForm":
+      return [];
+  }
+}
+function normalizeQuestion(q, idx) {
+  const hasOptions = Array.isArray(q.answerOptions);
+  const isFreeForm = q.freeFormReply === true;
+  if (hasOptions && isFreeForm) {
+    throw new MuxAiError(
+      `Question at index ${idx} sets both answerOptions and freeFormReply: true. These are mutually exclusive \u2014 pick one.`,
+      { type: "validation_error" }
+    );
+  }
+  if (isFreeForm) {
+    return { question: q.question, mode: { kind: "freeForm" } };
+  }
+  if (hasOptions) {
+    const options = Array.from(
+      new Set(
+        (q.answerOptions ?? []).map((o) => o.trim()).filter(Boolean)
+      )
+    );
+    if (!options.length) {
+      throw new MuxAiError(
+        `Question at index ${idx} has invalid answerOptions: must include at least one non-empty value.`,
+        { type: "validation_error" }
+      );
+    }
+    return {
+      question: q.question,
+      mode: { kind: "options", options }
+    };
+  }
+  return { question: q.question, mode: { kind: "yesNo" } };
+}
+function renderFormatTag(mode, maxFreeFormAnswerLength) {
+  switch (mode.kind) {
+    case "yesNo":
+      return renderSection({
+        tag: "allowed_answers",
+        content: YES_NO_ANSWERS.map((a) => `"${a}"`).join(", ")
+      });
+    case "options":
+      return renderSection({
+        tag: "allowed_answers",
+        content: mode.options.map((a) => `"${a}"`).join(", ")
+      });
+    case "freeForm":
+      return renderSection({
+        tag: "answer_format",
+        content: `free-form text, maximum ${maxFreeFormAnswerLength} characters`
+      });
+  }
+}
 function buildUserPrompt({
   questions,
   transcriptText,
   isCleanTranscript = true,
-  isAudioOnly = false
+  isAudioOnly = false,
+  maxFreeFormAnswerLength
 }) {
   const contentDescriptor = isAudioOnly ? "audio content using transcript evidence" : "content";
+  const hasFreeForm = questions.some((q) => q.mode.kind === "freeForm");
+  const formatInstruction = hasFreeForm ? "Follow each question's specified response format: pick from <allowed_answers> where listed, or produce a concise free-form answer where <answer_format> is specified." : "Use only the values listed inside each question's own <allowed_answers> element.";
   const taskContent = dedent2`
     Answer each question in the <questions> block below about the ${contentDescriptor}.
-    Use only the values listed inside each question's own <allowed_answers> element.
+    ${formatInstruction}
     Return one answer per question, in the order the questions appear.
     If a question cannot be answered from the provided content, skip it as described in the system instructions.`;
   const taskSection = `<task>
@@ -2117,13 +2212,10 @@ ${taskContent}
 </task>`;
   const questionBlocks = questions.map((q, idx) => {
     const textTag = renderSection({ tag: "text", content: q.question });
-    const answersTag = renderSection({
-      tag: "allowed_answers",
-      content: q.answerOptions.map((a) => `"${a}"`).join(", ")
-    });
+    const formatTag = renderFormatTag(q.mode, maxFreeFormAnswerLength);
     return `<question number="${idx + 1}">
 ${textTag}
-${answersTag}
+${formatTag}
 </question>`;
   }).join("\n\n");
   const questionsSection = `<questions>
@@ -2143,18 +2235,41 @@ async function fetchImageAsBase64(imageUrl, imageDownloadOptions) {
   const downloadResult = await downloadImageAsBase64(imageUrl, imageDownloadOptions);
   return downloadResult.base64Data;
 }
+function buildResponseSchemaForQuestions(normalizedQuestions, maxFreeFormAnswerLength) {
+  const hasFreeForm = normalizedQuestions.some((q) => q.mode.kind === "freeForm");
+  if (hasFreeForm) {
+    const longestConstrained = Math.max(
+      0,
+      ...normalizedQuestions.flatMap(allowedAnswersForQuestion).map((a) => a.length)
+    );
+    const schemaMax = Math.max(
+      maxFreeFormAnswerLength,
+      SKIP_SENTINEL.length,
+      longestConstrained
+    );
+    return createAskQuestionsSchema(z2.string().min(1).max(schemaMax));
+  }
+  const allowed = Array.from(
+    new Set(normalizedQuestions.flatMap(allowedAnswersForQuestion))
+  );
+  return createAskQuestionsSchema(z2.enum([...allowed, SKIP_SENTINEL]));
+}
 async function analyzeQuestions({
   provider,
   modelId,
   userPrompt,
   systemPrompt,
-  allowedAnswers,
+  normalizedQuestions,
+  maxFreeFormAnswerLength,
   imageDataUrl,
   credentials
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const responseSchema = createAskQuestionsSchema(allowedAnswers);
+  const responseSchema = buildResponseSchemaForQuestions(
+    normalizedQuestions,
+    maxFreeFormAnswerLength
+  );
   const response = await generateText({
     model,
     output: Output.object({ schema: responseSchema }),
@@ -2233,6 +2348,8 @@ async function askQuestions(assetId, questions, options) {
     );
   }
   questions.forEach((q, idx) => {
+    if (q.freeFormReply === true)
+      return;
     for (const opt of q.answerOptions ?? []) {
       if (typeof opt === "string" && opt.length > maxAnswerOptionLength) {
         throw new MuxAiError(
@@ -2242,6 +2359,14 @@ async function askQuestions(assetId, questions, options) {
       }
     }
   });
+  const DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH = 500;
+  const maxFreeFormAnswerLength = options?.maxFreeFormAnswerLength ?? DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH;
+  if (!Number.isFinite(maxFreeFormAnswerLength) || maxFreeFormAnswerLength <= 0) {
+    throw new MuxAiError(
+      `maxFreeFormAnswerLength must be a positive number (received ${maxFreeFormAnswerLength}).`,
+      { type: "validation_error" }
+    );
+  }
   const {
     provider = "openai",
     model,
@@ -2253,23 +2378,8 @@ async function askQuestions(assetId, questions, options) {
     storyboardWidth = 640,
     credentials
   } = options ?? {};
-  const normalizedQuestions = questions.map((q, idx) => {
-    const options2 = Array.from(
-      new Set(
-        (q.answerOptions?.length ? q.answerOptions : ["yes", "no"]).map((o) => o.trim()).filter(Boolean)
-      )
-    );
-    if (!options2.length) {
-      throw new MuxAiError(
-        `Question at index ${idx} has invalid answerOptions: must include at least one non-empty value.`,
-        { type: "validation_error" }
-      );
-    }
-    return { ...q, answerOptions: options2 };
-  });
-  const allowedAnswers = Array.from(
-    new Set(normalizedQuestions.flatMap((q) => q.answerOptions))
-  );
+  const normalizedQuestions = questions.map((q, idx) => normalizeQuestion(q, idx));
+  const hasFreeForm = normalizedQuestions.some((q) => q.mode.kind === "freeForm");
   const modelConfig = resolveLanguageModelConfig({
     ...options,
     model,
@@ -2303,9 +2413,10 @@ async function askQuestions(assetId, questions, options) {
     questions: normalizedQuestions,
     transcriptText,
     isCleanTranscript: cleanTranscript,
-    isAudioOnly
+    isAudioOnly,
+    maxFreeFormAnswerLength
   });
-  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT;
+  const systemPrompt = buildSystemPrompt(isAudioOnly, hasFreeForm, maxFreeFormAnswerLength);
   let analysisResponse;
   let imageUrl;
   try {
@@ -2315,7 +2426,8 @@ async function askQuestions(assetId, questions, options) {
         modelId: modelConfig.modelId,
         userPrompt,
         systemPrompt,
-        allowedAnswers,
+        normalizedQuestions,
+        maxFreeFormAnswerLength,
         credentials
       });
     } else {
@@ -2333,7 +2445,8 @@ async function askQuestions(assetId, questions, options) {
           modelId: modelConfig.modelId,
           userPrompt,
           systemPrompt,
-          allowedAnswers,
+          normalizedQuestions,
+          maxFreeFormAnswerLength,
           imageDataUrl: base64Data,
           credentials
         });
@@ -2344,7 +2457,8 @@ async function askQuestions(assetId, questions, options) {
             modelId: modelConfig.modelId,
             userPrompt,
             systemPrompt,
-            allowedAnswers,
+            normalizedQuestions,
+            maxFreeFormAnswerLength,
             imageDataUrl: storyboardUrl,
             credentials
           })
@@ -2379,20 +2493,42 @@ async function askQuestions(assetId, questions, options) {
     );
   }
   const answers = analysisResponse.result.answers.map((raw, idx) => {
-    const scrub = safety.scrubDetailed(raw.reasoning, `reasoning[${idx}]`);
-    const isSkipped = raw.skipped || raw.answer === SKIP_SENTINEL || scrub.leaked;
-    if (!isSkipped && !normalizedQuestions[idx].answerOptions.includes(raw.answer)) {
-      throw new MuxAiError(
-        `Answer "${raw.answer}" for question ${idx} is not in allowed options: ${normalizedQuestions[idx].answerOptions.join(", ")}`
+    const question = normalizedQuestions[idx];
+    const isFreeForm = question.mode.kind === "freeForm";
+    const reasoningScrub = safety.scrubDetailed(raw.reasoning, `reasoning[${idx}]`);
+    const explicitSkip = raw.skipped || raw.answer === SKIP_SENTINEL;
+    const answerScrub = isFreeForm && !explicitSkip ? safety.scrubDetailed(raw.answer, `answer[${idx}]`) : null;
+    const overLength = isFreeForm && !explicitSkip && !(answerScrub?.leaked ?? false) && (answerScrub?.text.length ?? 0) > maxFreeFormAnswerLength;
+    if (overLength) {
+      console.warn(
+        `[@mux/ai] Free-form answer at index ${idx} exceeded ${maxFreeFormAnswerLength}-char cap (${answerScrub.text.length} chars); treating as skipped.`
       );
     }
+    const isSkipped = explicitSkip || reasoningScrub.leaked || (answerScrub?.leaked ?? false) || overLength;
+    if (!isSkipped && !isFreeForm) {
+      const allowed = allowedAnswersForQuestion(question);
+      if (!allowed.includes(raw.answer)) {
+        throw new MuxAiError(
+          `Answer "${raw.answer}" for question ${idx} is not in allowed options: ${allowed.join(", ")}`
+        );
+      }
+    }
+    let finalAnswer;
+    if (isSkipped) {
+      finalAnswer = null;
+    } else if (isFreeForm) {
+      finalAnswer = answerScrub ? answerScrub.text : raw.answer;
+    } else {
+      finalAnswer = raw.answer;
+    }
+    const suppressed = reasoningScrub.leaked || (answerScrub?.leaked ?? false);
     return {
       // Use the trusted input verbatim rather than the model's echo.
-      question: normalizedQuestions[idx].question,
+      question: question.question,
       confidence: isSkipped ? 0 : Math.min(1, Math.max(0, raw.confidence)),
-      reasoning: scrub.leaked ? "Response suppressed by safety filter." : scrub.text,
+      reasoning: suppressed ? "Response suppressed by safety filter." : reasoningScrub.text,
       skipped: isSkipped,
-      answer: isSkipped ? null : raw.answer
+      answer: finalAnswer
     };
   });
   return {
@@ -4727,6 +4863,15 @@ var OPENAI_MODERATION_BASE_DELAY_MS = 750;
 var OPENAI_MODERATION_MAX_DELAY_MS = 3e3;
 var MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING = 0.5;
 var MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING = 3;
+var GOOGLE_VISION_ENDPOINT = "https://vision.googleapis.com/v1/images:annotate";
+var GOOGLE_VISION_LIKELIHOOD_TO_SCORE = {
+  UNKNOWN: 0,
+  VERY_UNLIKELY: 0.2,
+  UNLIKELY: 0.4,
+  POSSIBLE: 0.6,
+  LIKELY: 0.8,
+  VERY_LIKELY: 1
+};
 var HIVE_ENDPOINT = "https://api.thehive.ai/api/v2/task/sync";
 var HIVE_SEXUAL_CATEGORIES = [
   "general_nsfw",
@@ -5055,6 +5200,98 @@ async function requestHiveModeration(images, maxConcurrent = 5, submissionMode =
   }));
   return await processConcurrently(targets, moderateImageWithHive, maxConcurrent);
 }
+async function moderateImageWithGoogleVision(entry) {
+  "use step";
+  try {
+    const apiKey = await getApiKeyFromEnv("google-vision-api", entry.credentials);
+    const imageField = entry.isBase64 ? { content: entry.image } : { source: { imageUri: entry.image } };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15e3);
+    let res;
+    try {
+      res = await fetch(GOOGLE_VISION_ENDPOINT, {
+        method: "POST",
+        headers: {
+          "Accept": "application/json",
+          "Content-Type": "application/json",
+          "X-goog-api-key": apiKey
+        },
+        body: JSON.stringify({
+          requests: [
+            {
+              image: imageField,
+              features: [{ type: "SAFE_SEARCH_DETECTION" }]
+            }
+          ]
+        }),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        throw new Error("Google Vision request timed out after 15s");
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+    const json = await res.json().catch(() => void 0);
+    if (!res.ok) {
+      throw new Error(
+        `Google Vision moderation error: ${res.status} ${res.statusText} - ${JSON.stringify(json)}`
+      );
+    }
+    const perImage = json?.responses?.[0];
+    if (perImage?.error) {
+      throw new Error(
+        `Google Vision per-image error: ${perImage.error.code} ${perImage.error.message || "Unknown error"}`
+      );
+    }
+    const annotation = perImage?.safeSearchAnnotation;
+    if (!annotation) {
+      throw new Error(`Google Vision response missing safeSearchAnnotation: ${JSON.stringify(json)}`);
+    }
+    const adultLikelihood = typeof annotation.adult === "string" ? annotation.adult : "UNKNOWN";
+    const violenceLikelihood = typeof annotation.violence === "string" ? annotation.violence : "UNKNOWN";
+    const sexual = GOOGLE_VISION_LIKELIHOOD_TO_SCORE[adultLikelihood] ?? 0;
+    const violence = GOOGLE_VISION_LIKELIHOOD_TO_SCORE[violenceLikelihood] ?? 0;
+    return {
+      url: entry.url,
+      time: entry.time,
+      sexual,
+      violence,
+      error: false
+    };
+  } catch (error) {
+    return {
+      url: entry.url,
+      time: entry.time,
+      sexual: 0,
+      violence: 0,
+      error: true,
+      errorMessage: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function requestGoogleVisionModeration(images, maxConcurrent = 5, submissionMode = "url", downloadOptions, credentials) {
+  "use step";
+  const imageUrls = images.map((img) => img.url);
+  const timeByUrl = new Map(images.map((img) => [img.url, img.time]));
+  const targets = submissionMode === "base64" ? (await downloadImagesAsBase64(imageUrls, downloadOptions, maxConcurrent)).map((img) => ({
+    url: img.url,
+    time: timeByUrl.get(img.url),
+    // Vision REST wants raw base64; downloadImagesAsBase64 returns a data URI.
+    image: img.base64Data.startsWith("data:") ? img.base64Data.split(",")[1] : img.base64Data,
+    isBase64: true,
+    credentials
+  })) : images.map((img) => ({
+    url: img.url,
+    time: img.time,
+    image: img.url,
+    isBase64: false,
+    credentials
+  }));
+  return processConcurrently(targets, moderateImageWithGoogleVision, maxConcurrent);
+}
 async function getThumbnailUrlsFromTimestamps(playbackId, timestampsMs, options) {
   "use step";
   const { width, shouldSign, credentials } = options;
@@ -5118,8 +5355,11 @@ async function getModerationScores(assetId, options = {}) {
       );
     } else if (provider === "hive") {
       throw new Error("Hive does not support transcript moderation in this workflow. Use provider: 'openai' for audio-only assets.");
+    } else if (provider === "google-vision-api") {
+      throw new Error("google-vision-api is image-only and does not support transcript moderation. Use provider: 'openai' for audio-only assets.");
     } else {
-      throw new Error(`Unsupported moderation provider: ${provider}`);
+      const exhaustiveCheck = provider;
+      throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
     }
   } else {
     const estimatedIntervalCount = duration <= 50 ? 5 : Math.ceil(duration / thumbnailInterval);
@@ -5162,8 +5402,17 @@ async function getModerationScores(assetId, options = {}) {
         imageDownloadOptions,
         credentials
       );
+    } else if (provider === "google-vision-api") {
+      thumbnailScores = await requestGoogleVisionModeration(
+        thumbnailUrls,
+        maxConcurrent,
+        imageSubmissionMode,
+        imageDownloadOptions,
+        credentials
+      );
     } else {
-      throw new Error(`Unsupported moderation provider: ${provider}`);
+      const exhaustiveCheck = provider;
+      throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
     }
   }
   const failed = thumbnailScores.filter((s) => s.error);
@@ -6867,6 +7116,7 @@ export {
   DEFAULT_DESCRIPTION_LENGTH,
   DEFAULT_SUMMARY_KEYWORD_LIMIT,
   DEFAULT_TITLE_LENGTH,
+  GOOGLE_VISION_LIKELIHOOD_TO_SCORE,
   HIVE_SEXUAL_CATEGORIES,
   HIVE_VIOLENCE_CATEGORIES,
   aggregateTokenUsage,