@transloadit/zod 4.5.0 → 5.0.0

package/dist/v4/robots/video-subtitle.js

@@ -1,10 +1,10 @@
+import { optionalWithV3Semantics } from "../lib/sdkZodOptional.js";
 import { z } from 'zod/v4';
+import { zodInputPreservingTransform } from "../lib/zodInputSemantics.js";
 import { stackVersions } from "../stackVersions.js";
-import { color_with_alpha, color_without_alpha, interpolateRobot, positionSchema, robotBase, robotFFmpegVideo, robotUse, } from "./_instructions-primitives.js";
+import { color_with_alpha, color_without_alpha, defineRobot, positionSchema, robotBase, robotFFmpegVideo, robotUse, robotVideoEncodingMeta, } from "./_instructions-primitives.js";
 export const meta = {
-    bytescount: 1,
-    discount_factor: 1,
-    discount_pct: 0,
+    ...robotVideoEncodingMeta,
     example_code: {
         steps: {
             add_english_subtitles: {
@@ -49,29 +49,14 @@ export const meta = {
             },
         },
     },
-    example_code_description: 'If you have file input fields in a form — one for a video and one for each subtitle language (named `input_video`, `input_srt_en`, and `input_srt_de` via the HTML `name` attribute) — hereʼs how to add multiple subtitle streams with language tags to the video. Chain multiple `/video/subtitle` Steps with `keep_subtitles` set to `true` so each new stream is added alongside existing ones:',
-    minimum_charge: 0,
-    output_factor: 0.6,
-    override_lvl1: 'Video Encoding',
+    example_code_description: 'If you have file input fields in a form — one for a video and one for each subtitle language (named `input_video`, `input_srt_en`, and `input_srt_de` via the HTML `name` attribute) — here’s how to add multiple subtitle streams with language tags to the video. Chain multiple `/video/subtitle` Steps with `keep_subtitles` set to `true` so each new stream is added alongside existing ones:',
     purpose_sentence: 'adds subtitles and closed captions to videos',
     purpose_verb: 'subtitle',
     purpose_word: 'subtitle',
     purpose_words: 'Add subtitles to videos',
-    service_slug: 'video-encoding',
-    slot_count: 60,
     title: 'Add subtitles to videos',
-    typical_file_size_mb: 80,
-    typical_file_type: 'video',
     uses_tools: ['ffmpeg'],
     name: 'VideoSubtitleRobot',
-    priceFactor: 1,
-    queueSlotCount: 60,
-    isAllowedForUrlTransform: false,
-    trackOutputFileSize: true,
-    applyCommunityPlanMediaTrim: true,
-    isInternal: false,
-    removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
-    stage: 'ga',
 };
 export const robotVideoSubtitleInstructionsSchema = robotBase
     .merge(robotUse)
@@ -80,9 +65,7 @@ export const robotVideoSubtitleInstructionsSchema = robotBase
     robot: z.literal('/video/subtitle').describe(`
 This <dfn>Robot</dfn> supports both SRT and VTT subtitle files.
 `),
-    subtitles_type: z
-        .enum(['burned', 'external', 'burn'])
-        .transform((val) => (val === 'burn' ? 'burned' : val))
+    subtitles_type: zodInputPreservingTransform(z.enum(['burned', 'external', 'burn']), (val) => val === 'burn' ? 'burned' : val)
         .default('external')
         .describe(`
 Determines if subtitles are added as a separate stream to the video (value \`"external"\`) that then can be switched on and off in your video player, or if they should be burned directly into the video (value \`"burned"\` or \`"burn"\`) so that they become part of the video stream.
@@ -131,12 +114,11 @@ Specifies whether the subtitle text should be bold. Only applies to burned subti
         .describe(`
 Specifies whether the subtitle text should be italic. Only applies to burned subtitles.
 `),
-    outline_width: z
+    outline_width: optionalWithV3Semantics(z
         .number()
         .int()
         .min(0)
-        .max(10)
-        .optional()
+        .max(10))
         .nullable()
         .describe(`
 Specifies the width of the text outline in pixels. Only applies to burned subtitles with \`"outline"\` or \`"box"\` border styles. If not specified, the default width is used.
@@ -144,16 +126,14 @@ Specifies the width of the text outline in pixels. Only applies to burned subtit
     position: positionSchema.default('bottom').describe(`
 Specifies the position of the subtitles.
 `),
-    language: z
-        .string()
-        .optional()
+    language: optionalWithV3Semantics(z
+        .string())
         .nullable()
         .describe(`
 Specifies the language of the subtitle stream using a three-letter language code (e.g. \`"eng"\`, \`"deu"\`, \`"spa"\`). Only used if the subtitles are external. When adding multiple subtitle streams, set a different language for each stream so that video players can offer language selection.
 `),
-    name: z
-        .string()
-        .optional()
+    name: optionalWithV3Semantics(z
+        .string())
         .nullable()
         .describe(`
 Specifies a human-readable name for the subtitle track (e.g. \`"English"\`, \`"Deutsch"\`, \`"Español"\`). Only used if the subtitles are external. This name is displayed in video player subtitle menus alongside the language.
@@ -166,10 +146,5 @@ Specifies if existing subtitles in the input file should be kept or be replaced
 `),
 })
     .strict();
-export const robotVideoSubtitleInstructionsWithHiddenFieldsSchema = robotVideoSubtitleInstructionsSchema.extend({
-    result: z
-        .union([z.literal('debug'), robotVideoSubtitleInstructionsSchema.shape.result])
-        .optional(),
-});
-export const interpolatableRobotVideoSubtitleInstructionsSchema = interpolateRobot(robotVideoSubtitleInstructionsSchema);
-export const interpolatableRobotVideoSubtitleInstructionsWithHiddenFieldsSchema = interpolateRobot(robotVideoSubtitleInstructionsWithHiddenFieldsSchema);
+export const robotDefinition = defineRobot(meta, robotVideoSubtitleInstructionsSchema);
+export const { withHiddenFields: robotVideoSubtitleInstructionsWithHiddenFieldsSchema, interpolatable: interpolatableRobotVideoSubtitleInstructionsSchema, interpolatableWithHiddenFields: interpolatableRobotVideoSubtitleInstructionsWithHiddenFieldsSchema, } = robotDefinition;

package/dist/v4/robots/video-thumbs.d.ts

@@ -1,15 +1,20 @@
-import type { RobotMetaInput } from './_instructions-primitives.ts';
+import type { RobotDefinition, RobotMetaInput, RobotSchemaVariantTypes } from './_instructions-primitives.ts';
 import { z } from 'zod/v4';
+/** Markup over the AI provider cost for smart thumbnail selection. */
+export declare const smartThumbnailMarkupPercent = 50;
+/** Candidate-pool size shared by smart thumbnail execution and its documented default example. */
+export declare function getSmartThumbnailCandidateCount(count: number, maximumCandidates: number): number;
 export declare const meta: RobotMetaInput;
 export declare const robotVideoThumbsInstructionsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        false: "false";
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>>]>>;
+        false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    user_meta: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     result: z.ZodDefault<z.ZodBoolean>;
     queue: z.ZodOptional<z.ZodEnum<{
         batch: "batch";
@@ -52,8 +57,8 @@ export declare const robotVideoThumbsInstructionsSchema: z.ZodObject<{
         filter_complex: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
         'level:v': z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         'profile:v': z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
-            main: "main";
             baseline: "baseline";
+            main: "main";
             high: "high";
             main10: "main10";
         }>]>>;
@@ -156,15 +161,17 @@ export declare const robotVideoThumbsInstructionsSchema: z.ZodObject<{
     smart: z.ZodDefault<z.ZodBoolean>;
     smart_max_candidates: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
+export declare const robotDefinition: RobotDefinition<typeof robotVideoThumbsInstructionsSchema.shape>;
 export declare const robotVideoThumbsInstructionsWithHiddenFieldsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        false: "false";
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>>]>>;
+        false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    user_meta: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     queue: z.ZodOptional<z.ZodEnum<{
         batch: "batch";
     }>>;
@@ -206,8 +213,8 @@ export declare const robotVideoThumbsInstructionsWithHiddenFieldsSchema: z.ZodOb
         filter_complex: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
         'level:v': z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         'profile:v': z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
-            main: "main";
             baseline: "baseline";
+            main: "main";
             high: "high";
             main10: "main10";
         }>]>>;
@@ -310,24 +317,22 @@ export declare const robotVideoThumbsInstructionsWithHiddenFieldsSchema: z.ZodOb
     smart: z.ZodDefault<z.ZodBoolean>;
     smart_max_candidates: z.ZodDefault<z.ZodNumber>;
     result: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"debug">, z.ZodDefault<z.ZodBoolean>]>>;
-}, z.core.$strict>;
-export type RobotVideoThumbsInstructions = z.infer<typeof robotVideoThumbsInstructionsSchema>;
-export type RobotVideoThumbsInstructionsWithHiddenFields = z.infer<typeof robotVideoThumbsInstructionsWithHiddenFieldsSchema>;
-export declare const interpolatableRobotVideoThumbsInstructionsSchema: z.ZodObject<{
+}, z.core.$strict>, interpolatableRobotVideoThumbsInstructionsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        false: "false";
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>>]>>;
+        false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
-    result: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+    user_meta: z.ZodPrefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    result: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         batch: "batch";
     }>]>>;
-    force_accept: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
-    ignore_errors: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
+    force_accept: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+    ignore_errors: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
         meta: "meta";
         execute: "execute";
     }>>]>, z.ZodTransform<string[], boolean | ("meta" | "execute")[]>>]>>;
@@ -364,8 +369,8 @@ export declare const interpolatableRobotVideoThumbsInstructionsSchema: z.ZodObje
         filter_complex: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
         'level:v': z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>]>>;
         'profile:v': z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>, z.ZodUnion<[z.ZodString, z.ZodEnum<{
-            main: "main";
             baseline: "baseline";
+            main: "main";
             high: "high";
             main10: "main10";
         }>]>]>>;
@@ -439,22 +444,22 @@ export declare const interpolatableRobotVideoThumbsInstructionsSchema: z.ZodObje
         x264opts: z.ZodOptional<z.ZodString>;
         vbr: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>]>>;
     }, z.core.$catchall<z.ZodUnknown>>]>>;
-    ffmpeg_stack: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    ffmpeg_stack: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodEnum<{
         v6: "v6";
         v7: "v7";
         v8: "v8";
     }>]>, z.ZodString]>>;
     robot: z.ZodLiteral<"/video/thumbs">;
-    count: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    offsets: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>>]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
-    format: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    count: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    offsets: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>>]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
+    format: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         jpeg: "jpeg";
         jpg: "jpg";
         png: "png";
     }>]>>;
     width: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
     height: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    resize_strategy: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    resize_strategy: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         crop: "crop";
         fit: "fit";
         fillcrop: "fillcrop";
@@ -462,28 +467,26 @@ export declare const interpolatableRobotVideoThumbsInstructionsSchema: z.ZodObje
         pad: "pad";
         stretch: "stretch";
     }>]>>;
-    background: z.ZodDefault<z.ZodString>;
-    rotate: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<0>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<90>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<180>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<270>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<360>]>]>>;
+    background: z.ZodPrefault<z.ZodString>;
+    rotate: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<0>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<90>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<180>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<270>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<360>]>]>>;
     input_codec: z.ZodOptional<z.ZodString>;
-    smart: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
-    smart_max_candidates: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-}, z.core.$strict>;
-export type InterpolatableRobotVideoThumbsInstructions = InterpolatableRobotVideoThumbsInstructionsInput;
-export type InterpolatableRobotVideoThumbsInstructionsInput = z.input<typeof interpolatableRobotVideoThumbsInstructionsSchema>;
-export declare const interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema: z.ZodObject<{
+    smart: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+    smart_max_candidates: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, z.core.$strict>, interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        false: "false";
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>, z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
         true: "true";
-    }>]>, z.ZodTransform<boolean, boolean | "false" | "true">>>]>>;
+        false: "false";
+    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
+    user_meta: z.ZodPrefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         batch: "batch";
     }>]>>;
-    force_accept: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
-    ignore_errors: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
+    force_accept: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+    ignore_errors: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
         meta: "meta";
         execute: "execute";
     }>>]>, z.ZodTransform<string[], boolean | ("meta" | "execute")[]>>]>>;
@@ -520,8 +523,8 @@ export declare const interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsS
         filter_complex: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
         'level:v': z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>]>>;
         'profile:v': z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>, z.ZodUnion<[z.ZodString, z.ZodEnum<{
-            main: "main";
             baseline: "baseline";
+            main: "main";
             high: "high";
             main10: "main10";
         }>]>]>>;
@@ -595,22 +598,22 @@ export declare const interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsS
         x264opts: z.ZodOptional<z.ZodString>;
         vbr: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>]>>;
     }, z.core.$catchall<z.ZodUnknown>>]>>;
-    ffmpeg_stack: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    ffmpeg_stack: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodEnum<{
         v6: "v6";
         v7: "v7";
         v8: "v8";
     }>]>, z.ZodString]>>;
     robot: z.ZodLiteral<"/video/thumbs">;
-    count: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    offsets: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>>]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
-    format: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    count: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    offsets: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>>]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>]>>;
+    format: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         jpeg: "jpeg";
         jpg: "jpg";
         png: "png";
     }>]>>;
     width: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
     height: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    resize_strategy: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
+    resize_strategy: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodEnum<{
         crop: "crop";
         fit: "fit";
         fillcrop: "fillcrop";
@@ -618,13 +621,19 @@ export declare const interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsS
         pad: "pad";
         stretch: "stretch";
     }>]>>;
-    background: z.ZodDefault<z.ZodString>;
-    rotate: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<0>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<90>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<180>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<270>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<360>]>]>>;
+    background: z.ZodPrefault<z.ZodString>;
+    rotate: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<0>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<90>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<180>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<270>]>, z.ZodUnion<[z.ZodString, z.ZodLiteral<360>]>]>>;
     input_codec: z.ZodOptional<z.ZodString>;
-    smart: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
-    smart_max_candidates: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    result: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<"debug">]>, z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>]>>;
+    smart: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+    smart_max_candidates: z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    result: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodString, z.ZodLiteral<"debug">]>, z.ZodPrefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>]>>;
 }, z.core.$strict>;
-export type InterpolatableRobotVideoThumbsInstructionsWithHiddenFields = z.infer<typeof interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema>;
-export type InterpolatableRobotVideoThumbsInstructionsWithHiddenFieldsInput = z.input<typeof interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema>;
+type Instructions = RobotSchemaVariantTypes<typeof robotDefinition>;
+export type RobotVideoThumbsInstructions = Instructions['output'];
+export type RobotVideoThumbsInstructionsWithHiddenFields = Instructions['hiddenOutput'];
+export type InterpolatableRobotVideoThumbsInstructions = Instructions['interpolatableInput'];
+export type InterpolatableRobotVideoThumbsInstructionsInput = Instructions['interpolatableInput'];
+export type InterpolatableRobotVideoThumbsInstructionsWithHiddenFields = Instructions['interpolatableHiddenOutput'];
+export type InterpolatableRobotVideoThumbsInstructionsWithHiddenFieldsInput = Instructions['interpolatableHiddenInput'];
+export {};
 //# sourceMappingURL=video-thumbs.d.ts.map

package/dist/v4/robots/video-thumbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"video-thumbs.d.ts","sourceRoot":"","sources":["../../../src/v4/robots/video-thumbs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEnE,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAa1B,eAAO,MAAM,IAAI,EAAE,cAqClB,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoGpC,CAAA;AAEX,eAAO,MAAM,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAK3D,CAAA;AAEJ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAA;AAC7F,MAAM,MAAM,4CAA4C,GAAG,CAAC,CAAC,KAAK,CAChE,OAAO,kDAAkD,CAC1D,CAAA;AAED,eAAO,MAAM,gDAAgD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAE5D,CAAA;AACD,MAAM,MAAM,0CAA0C,GACpD,+CAA+C,CAAA;AAEjD,MAAM,MAAM,+CAA+C,GAAG,CAAC,CAAC,KAAK,CACnE,OAAO,gDAAgD,CACxD,CAAA;AAED,eAAO,MAAM,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAE5E,CAAA;AACD,MAAM,MAAM,0DAA0D,GAAG,CAAC,CAAC,KAAK,CAC9E,OAAO,gEAAgE,CACxE,CAAA;AACD,MAAM,MAAM,+DAA+D,GAAG,CAAC,CAAC,KAAK,CACnF,OAAO,gEAAgE,CACxE,CAAA"}
+{"version":3,"file":"video-thumbs.d.ts","sourceRoot":"","sources":["../../../src/v4/robots/video-thumbs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAe1B,sEAAsE;AACtE,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAO7C,kGAAkG;AAClG,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,eAAO,MAAM,IAAI,EAAE,cAmBlB,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwGpC,CAAA;AAEX,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,OAAO,kCAAkC,CAAC,KAAK,CACtC,CAAA;AAEvD,eAAO,MACa,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBACpD,gDAAgD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAChC,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAC/E,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,4BAA4B,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACjE,MAAM,MAAM,4CAA4C,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AACvF,MAAM,MAAM,0CAA0C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAC5F,MAAM,MAAM,+CAA+C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACjG,MAAM,MAAM,0DAA0D,GACpE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,+DAA+D,GACzE,YAAY,CAAC,2BAA2B,CAAC,CAAA"}

package/dist/v4/robots/video-thumbs.js

@@ -1,59 +1,58 @@
+import { optionalWithV3Semantics } from "../lib/sdkZodOptional.js";
 import { z } from 'zod/v4';
 import { stackVersions } from "../stackVersions.js";
-import { color_with_alpha, interpolateRobot, percentageSchema, resize_strategy, robotBase, robotFFmpeg, robotUse, } from "./_instructions-primitives.js";
+import { color_with_alpha, createProcessingExample, defineRobot, percentageSchema, resize_strategy, robotBase, robotFFmpeg, robotUse, robotVideoEncodingMeta, } from "./_instructions-primitives.js";
+/** Markup over the AI provider cost for smart thumbnail selection. */
+export const smartThumbnailMarkupPercent = 50;
+const thumbnailCountSchema = z.number().int().min(1).max(999).default(8);
+const smartMaximumCandidatesSchema = z.number().int().min(2).max(100).default(20);
+const defaultThumbnailCount = thumbnailCountSchema.parse(undefined);
+const defaultSmartMaximumCandidates = smartMaximumCandidatesSchema.parse(undefined);
+/** Candidate-pool size shared by smart thumbnail execution and its documented default example. */
+export function getSmartThumbnailCandidateCount(count, maximumCandidates) {
+    return Math.max(count, Math.min(maximumCandidates, count * 3));
+}
 export const meta = {
-    bytescount: 10,
-    discount_factor: 0.1,
-    discount_pct: 90,
-    example_code: {
-        steps: {
-            thumbnailed: {
-                robot: '/video/thumbs',
-                use: ':original',
-                count: 10,
-                ffmpeg_stack: stackVersions.ffmpeg.recommendedVersion,
-            },
-        },
-    },
-    example_code_description: 'Extract 10 thumbnails from each uploaded video:',
-    minimum_charge: 0,
-    output_factor: 0.05,
-    override_lvl1: 'Video Encoding',
+    ...robotVideoEncodingMeta,
+    example_code: createProcessingExample('thumbnailed', '/video/thumbs', {
+        count: 3,
+        ffmpeg_stack: stackVersions.ffmpeg.recommendedVersion,
+        smart: true,
+        smart_max_candidates: 12,
+    }),
+    example_code_description: 'Select three visually appealing thumbnails from each uploaded video with AI:',
     purpose_sentence: 'extracts any number of images from videos for use as previews',
     purpose_verb: 'extract',
     purpose_word: 'thumbnail',
     purpose_words: 'Extract thumbnails from videos',
-    service_slug: 'video-encoding',
-    slot_count: 15,
     title: 'Extract thumbnails from videos',
-    typical_file_size_mb: 80,
-    typical_file_type: 'video',
     uses_tools: ['ffmpeg'],
     name: 'VideoThumbsRobot',
     priceFactor: 10,
     queueSlotCount: 15,
-    isAllowedForUrlTransform: false,
-    trackOutputFileSize: true,
-    applyCommunityPlanMediaTrim: true,
-    isInternal: false,
-    removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
-    stage: 'ga',
 };
 export const robotVideoThumbsInstructionsSchema = robotBase
     .merge(robotUse)
     .merge(robotFFmpeg)
     .extend({
     robot: z.literal('/video/thumbs').describe(`
+Set \`smart: true\` to select strong preview images with AI instead of taking frames only at regular intervals. The Robot scores candidate frames for clarity, brightness, composition, faces, expressions, action, and visual interest, then returns the best \`count\` frames in chronological order. Smart results include \`file.meta.smart_score\` and \`file.meta.smart_reasons\`. If AI scoring is unavailable, the Assembly continues with the candidate frames in fallback order. No AI credentials are required.
+
+## AI pricing
+
+Regular \`/video/thumbs\` processing charges still apply. AI frame analysis is billed separately at the underlying provider cost plus a ${smartThumbnailMarkupPercent}% Transloadit markup. The exact AI charge varies with the number of candidate frames, the internally selected model and provider pricing, and the image payload size.
+
+\`smart_max_candidates\` is the main cost and latency control. The Robot analyzes up to three candidates per requested thumbnail, capped by \`smart_max_candidates\`, but never fewer than \`count\`. With the defaults of \`count: ${defaultThumbnailCount}\` and \`smart_max_candidates: ${defaultSmartMaximumCandidates}\`, it analyzes ${getSmartThumbnailCandidateCount(defaultThumbnailCount, defaultSmartMaximumCandidates)} frames and returns the best ${defaultThumbnailCount}. Lower the candidate limit to reduce AI cost and latency; raise it to give the AI more frames to choose from.
+
 > [!Note]
-> Even though thumbnails are extracted from videos in parallel, we sort the thumbnails before adding them to the Assembly results. So the order in which they appear there reflects the order in which they appear in the video. You can also make sure by checking the <code>thumb_index</code> meta key.
+> Use \`count\` with smart selection. To consistently extract exact timestamps with \`offsets\`, set \`smart: false\`.
+
+> [!Note]
+> Even though thumbnails are extracted from videos in parallel, we sort the thumbnails before adding them to the Assembly results. So the order in which they appear there reflects the order in which they appear in the video. You can also make sure by checking the \`thumb_index\` meta key.
+
+For an upload-to-poster Template, SDK usage, and publication checks, see the [HTML video workflow guide](/guides/html-video-production-checklist/#html-video-production-checklist-section-6). The [video and S3 demo](/demos/file-exporting/store-encoding-and-thumbnails-on-s3/) includes a recorded input and extracted frames.
 `),
-    count: z
-        .number()
-        .int()
-        .min(1)
-        .max(999)
-        .default(8)
-        .describe(`
+    count: thumbnailCountSchema.describe(`
 The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of thumbnails we currently allow is 999.
 
 The thumbnails are taken at regular intervals, determined by dividing the video duration by the count. For example, a count of 3 will produce thumbnails at 25%, 50% and 75% through the video.
@@ -67,6 +66,8 @@ To extract thumbnails for specific timestamps, use the \`offsets\` parameter.
 An array of offsets representing seconds of the file duration, such as \`[ 2, 45, 120 ]\`. Millisecond durations of a file can also be used by using decimal place values. For example, an offset from 1250 milliseconds would be represented with \`1.25\`. Offsets can also be percentage values such as \`[ "2%", "50%", "75%" ]\`.
 
 This option cannot be used with the \`count\` parameter, and takes precedence if both are specified. Out-of-range offsets are silently ignored.
+
+When \`smart\` is \`true\`, smart selection ignores \`offsets\` and uses \`count\` to select from its own candidate timestamps. If no smart candidates can be extracted, the Robot falls back to standard extraction, where \`offsets\` takes precedence. Use \`smart: false\` to consistently extract the specified timestamps.
 `),
     format: z
         .enum(['jpeg', 'jpg', 'png'])
@@ -74,21 +75,19 @@ This option cannot be used with the \`count\` parameter, and takes precedence if
         .describe(`
 The format of the extracted thumbnail. Supported values are \`"jpg"\`, \`"jpeg"\` and \`"png"\`. Even if you specify the format to be \`"jpeg"\` the resulting thumbnails will have a \`"jpg"\` file extension.
 `),
-    width: z
+    width: optionalWithV3Semantics(z
         .number()
         .int()
         .min(1)
-        .max(1920)
-        .optional()
+        .max(1920))
         .describe(`
 The width of the thumbnail, in pixels. Defaults to the original width of the video.
 `),
-    height: z
+    height: optionalWithV3Semantics(z
         .number()
         .int()
         .min(1)
-        .max(1080)
-        .optional()
+        .max(1080))
         .describe(`
 The height of the thumbnail, in pixels. Defaults to the original height of the video.
 `),
@@ -104,9 +103,8 @@ The background color of the resulting thumbnails in the \`"rrggbbaa"\` format (r
         .describe(`
 Forces the video to be rotated by the specified degree integer. Currently, only multiples of 90 are supported. We automatically correct the orientation of many videos when the orientation is provided by the camera. This option is only useful for videos requiring rotation because it was not detected by the camera.
 `),
-    input_codec: z
-        .string()
-        .optional()
+    input_codec: optionalWithV3Semantics(z
+        .string())
         .describe(`
 Specifies the input codec to use when decoding the video. This is useful for videos with special codecs that require specific decoders.
 `),
@@ -123,27 +121,20 @@ The AI evaluates frames based on:
 - Action and motion (avoiding transition frames)
 - Overall visual interest
 
-Smart thumbnail analysis is billed with a 50% margin over the underlying AI provider cost.
+Regular \`/video/thumbs\` processing charges still apply. AI frame analysis is billed separately at the underlying provider cost plus a ${smartThumbnailMarkupPercent}% Transloadit markup. You do not need to provide AI credentials.
+
+Smart mode generates its own regularly spaced candidate timestamps; use \`smart: false\` with \`offsets\` when you need specified timestamps. Selected smart thumbnails are returned in chronological order, not score order. Inspect \`meta.thumb_offset\`, \`meta.smart_score\`, and \`meta.smart_reasons\` when evaluating the selection.
+
+If AI scoring fails, the Robot selects from the extracted candidates in chronological order and records a fallback reason. If no candidates can be extracted, it attempts standard thumbnail extraction. A completed Assembly does not guarantee a representative or publication-safe poster; check that outputs exist and apply your application’s review policy.
 `),
-    smart_max_candidates: z
-        .number()
-        .int()
-        .min(2)
-        .max(100)
-        .default(20)
-        .describe(`
-The maximum number of candidate frames to extract and analyze when \`smart\` is \`true\`.
+    smart_max_candidates: smartMaximumCandidatesSchema.describe(`
+The maximum size of the candidate pool when \`smart\` is \`true\`. The Robot analyzes up to three candidates per requested thumbnail, capped by this value, but it will never analyze fewer candidates than the requested \`count\`.
 
-A higher number may yield better results but increases processing time and cost. The Robot will extract this many frames evenly distributed across the video, analyze them with AI, and return only the top \`count\` results.
+A higher number may yield better results but increases processing time and AI cost. With the defaults of \`count: ${defaultThumbnailCount}\` and \`smart_max_candidates: ${defaultSmartMaximumCandidates}\`, the Robot analyzes ${getSmartThumbnailCandidateCount(defaultThumbnailCount, defaultSmartMaximumCandidates)} frames and returns the best ${defaultThumbnailCount} in chronological order.
 
 This parameter is only used when \`smart\` is \`true\`.
 `),
 })
     .strict();
-export const robotVideoThumbsInstructionsWithHiddenFieldsSchema = robotVideoThumbsInstructionsSchema.extend({
-    result: z
-        .union([z.literal('debug'), robotVideoThumbsInstructionsSchema.shape.result])
-        .optional(),
-});
-export const interpolatableRobotVideoThumbsInstructionsSchema = interpolateRobot(robotVideoThumbsInstructionsSchema);
-export const interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema = interpolateRobot(robotVideoThumbsInstructionsWithHiddenFieldsSchema);
+export const robotDefinition = defineRobot(meta, robotVideoThumbsInstructionsSchema);
+export const { withHiddenFields: robotVideoThumbsInstructionsWithHiddenFieldsSchema, interpolatable: interpolatableRobotVideoThumbsInstructionsSchema, interpolatableWithHiddenFields: interpolatableRobotVideoThumbsInstructionsWithHiddenFieldsSchema, } = robotDefinition;