@transloadit/node 4.10.8 → 4.11.1

package/src/alphalib/types/robots/video-generate.ts

@@ -2,7 +2,12 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 
 import { z } from 'zod'
 
-import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
+import {
+  autoProviderDescription,
+  interpolateRobot,
+  robotBase,
+  robotUse,
+} from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
   bytescount: 1,
@@ -37,6 +42,7 @@ export const meta: RobotMetaInput = {
   minimumChargeUsd: 0.06,
   isAllowedForUrlTransform: true,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'ga',
@@ -89,7 +95,7 @@ export const robotVideoGenerateInstructionsSchema = robotBase
 
 export const robotVideoGenerateInstructionsWithHiddenFieldsSchema =
   robotVideoGenerateInstructionsSchema.extend({
-    provider: z.string().optional().describe('Provider for generating the video.'),
+    provider: z.string().default('auto').describe(autoProviderDescription),
     result: z
       .union([z.literal('debug'), robotVideoGenerateInstructionsSchema.shape.result])
       .optional(),

package/src/alphalib/types/robots/video-merge.ts

@@ -4,6 +4,8 @@ import { z } from 'zod'
 
 import {
   color_with_alpha,
+  httpUrlSchema,
+  inputSortBySchema,
   interpolateRobot,
   resize_strategy,
   robotBase,
@@ -51,6 +53,7 @@ export const meta: RobotMetaInput = {
   queueSlotCount: 60,
   isAllowedForUrlTransform: false,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'ga',
@@ -112,13 +115,10 @@ Determines whether the audio of the video should be replaced with a provided aud
       .describe(`
 Stacks the input media vertically. All streams need to have the same pixel format and width - so consider using a [/video/encode](/docs/robots/video-encode/) <dfn>Step</dfn> before using this parameter to enforce this.
 `),
-    image_url: z
-      .string()
-      .url()
-      .optional()
-      .describe(`
+    image_url: httpUrlSchema.optional().describe(`
 The URL of an image to be merged with the audio or video. When this parameter is provided, the robot will download the image from the URL and merge it with the other media.
 `),
+    sort_by: inputSortBySchema,
     transition: z
       .enum(['none', 'crossfade', 'fade_to_black'])
       .default('none')

package/src/alphalib/types/robots/video-ondemand.ts

@@ -66,6 +66,7 @@ export const meta: RobotMetaInput = {
   downloadInputFiles: false,
   isAllowedForUrlTransform: true,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'beta',

package/src/alphalib/types/robots/video-split.ts

@@ -47,6 +47,7 @@ export const meta: RobotMetaInput = {
   queueSlotCount: 60,
   isAllowedForUrlTransform: false,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'ga',

package/src/alphalib/types/robots/video-subtitle.ts

@@ -81,6 +81,7 @@ export const meta: RobotMetaInput = {
   queueSlotCount: 60,
   isAllowedForUrlTransform: false,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'ga',

package/src/alphalib/types/robots/video-thumbs.ts

@@ -46,6 +46,7 @@ export const meta: RobotMetaInput = {
   queueSlotCount: 15,
   isAllowedForUrlTransform: false,
   trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
   isInternal: false,
   removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
   stage: 'ga',
@@ -121,6 +122,34 @@ Forces the video to be rotated by the specified degree integer. Currently, only
       .optional()
       .describe(`
 Specifies the input codec to use when decoding the video. This is useful for videos with special codecs that require specific decoders.
+`),
+    smart: z
+      .boolean()
+      .default(false)
+      .describe(`
+When set to \`true\`, enables AI-powered smart thumbnail selection. Instead of returning thumbnails at regular intervals, the Robot will analyze candidate frames and select the most visually appealing ones.
+
+The AI evaluates frames based on:
+- Visual clarity (avoiding blurry or dark frames)
+- Composition quality
+- Face presence and expressions
+- Action and motion (avoiding transition frames)
+- Overall visual interest
+
+Smart thumbnail analysis is billed with a 50% margin over the underlying AI provider cost.
+`),
+    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\`.
+
+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.
+
+This parameter is only used when \`smart\` is \`true\`.
 `),
   })
   .strict()

package/src/cli/commands/assemblies.ts

@@ -3,7 +3,11 @@ import type { Readable } from 'node:stream'
 import type { StepsInput } from '../../alphalib/types/template.ts'
 import type { CreateAssemblyParams, ReplayAssemblyParams } from '../../apiTypes.ts'
 import type { LintFatalLevel } from '../../lintAssemblyInstructions.ts'
-import type { CreateAssemblyOptions, Transloadit } from '../../Transloadit.ts'
+import type {
+  CompileAssemblyInstructionsFromPromptOptions,
+  CreateAssemblyOptions,
+  Transloadit,
+} from '../../Transloadit.ts'
 import type { IOutputCtl } from '../OutputCtl.ts'
 import type { NormalizedAssemblyResultFile, NormalizedAssemblyResults } from '../resultFiles.ts'
 import type { ResultUrlRow } from '../resultUrls.ts'
@@ -44,7 +48,7 @@ import {
 import { formatAPIError, readCliInput } from '../helpers.ts'
 import { normalizeAssemblyResults } from '../resultFiles.ts'
 import { collectNormalizedResultUrlRows, printResultUrls } from '../resultUrls.ts'
-import { readStepsInputFile } from '../stepsInput.ts'
+import { parseStepsInputJson, readStepsInputFile } from '../stepsInput.ts'
 import { ensureError, isErrnoException } from '../types.ts'
 import { AuthenticatedCommand, UnauthenticatedCommand } from './BaseCommand.ts'
 
@@ -82,6 +86,14 @@ export interface AssemblyLintOptions {
   json?: boolean
 }
 
+export interface AssemblyInstructionsCompileOptions {
+  maxAttempts?: number
+  mcpServerUrl?: string
+  model?: string
+  prompt: string
+  timeout?: number
+}
+
 function formatAssemblyReference({
   assemblyId,
   assemblyUrl,
@@ -325,6 +337,49 @@ export async function lint(
   return result.success ? 0 : 1
 }
 
+function toPositiveInteger(value: number | undefined, optionName: string): number | undefined {
+  if (value == null) {
+    return undefined
+  }
+
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${optionName} must be a positive integer`)
+  }
+
+  return value
+}
+
+function createCompileOptions({
+  maxAttempts,
+  mcpServerUrl,
+  model,
+  prompt,
+  timeout,
+}: AssemblyInstructionsCompileOptions): CompileAssemblyInstructionsFromPromptOptions {
+  return {
+    maxAttempts,
+    mcpServerUrl,
+    model,
+    prompt,
+    timeout,
+  }
+}
+
+async function compileAssemblyInstructions(
+  output: IOutputCtl,
+  client: Transloadit,
+  options: AssemblyInstructionsCompileOptions,
+): Promise<number> {
+  try {
+    const result = await client.compileAssemblyInstructionsFromPrompt(createCompileOptions(options))
+    output.print(result.instructionsJson, result)
+    return 0
+  } catch (error) {
+    output.error(formatAPIError(error))
+    return 1
+  }
+}
+
 // --- From assemblies-create.ts: Helper classes and functions ---
 interface NodeWatcher {
   on(event: 'error', listener: (err: Error) => void): void
@@ -1658,6 +1713,64 @@ export async function create(
 }
 
 // --- Command classes ---
+export class AssemblyInstructionsCompileCommand extends AuthenticatedCommand {
+  static override paths = [
+    ['assembly-instructions', 'compile'],
+    ['assembly-instruction', 'compile'],
+    ['instructions', 'compile'],
+  ]
+
+  static override usage = Command.Usage({
+    category: 'Assembly Instructions',
+    description: 'Compile a prompt into Assembly Instructions',
+    details: `
+      Compile a natural-language prompt into validated Transloadit Assembly Instructions JSON.
+    `,
+    examples: [
+      [
+        'Compile instructions',
+        'transloadit assembly-instructions compile "resize uploaded images to 400px wide"',
+      ],
+    ],
+  })
+
+  prompt = Option.String({ required: true })
+
+  model = Option.String('--model', {
+    description: 'AI model to use for instruction compilation',
+  })
+
+  mcpServerUrl = Option.String('--mcp-server', {
+    description: 'MCP server URL used for Robot docs and instruction linting',
+  })
+
+  maxAttempts = Option.String('--max-attempts', {
+    description: 'Maximum validation attempts',
+    validator: t.applyCascade(t.isNumber(), [t.isAtLeast(1)]),
+  })
+
+  timeout = Option.String('--timeout', {
+    description: 'Compiler Assembly timeout in milliseconds',
+    validator: t.applyCascade(t.isNumber(), [t.isAtLeast(1)]),
+  })
+
+  protected async run(): Promise<number | undefined> {
+    return await compileAssemblyInstructions(this.output, this.client, {
+      maxAttempts: toPositiveInteger(
+        this.maxAttempts == null ? undefined : Number(this.maxAttempts),
+        '--max-attempts',
+      ),
+      mcpServerUrl: this.mcpServerUrl,
+      model: this.model,
+      prompt: this.prompt,
+      timeout: toPositiveInteger(
+        this.timeout == null ? undefined : Number(this.timeout),
+        '--timeout',
+      ),
+    })
+  }
+}
+
 export class AssembliesCreateCommand extends AuthenticatedCommand {
   static override paths = [
     ['assemblies', 'create'],
@@ -1775,6 +1888,135 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
   }
 }
 
+export class RunCommand extends AuthenticatedCommand {
+  static override paths = [['run']]
+
+  static override usage = Command.Usage({
+    category: 'Assemblies',
+    description: 'Compile Assembly Instructions and run them as an Assembly',
+    details: `
+      Compile a natural-language prompt into Assembly Instructions, then run those instructions directly.
+    `,
+    examples: [
+      [
+        'Compile and run',
+        'transloadit run "resize uploaded images to 400px wide" -i input.jpg -o output.jpg',
+      ],
+      [
+        'Print result URLs',
+        'transloadit run "extract a waveform image from this audio" -i input.mp3 --print-urls',
+      ],
+    ],
+  })
+
+  prompt = Option.String({ required: true })
+
+  model = Option.String('--model', {
+    description: 'AI model to use for instruction compilation',
+  })
+
+  mcpServerUrl = Option.String('--mcp-server', {
+    description: 'MCP server URL used for Robot docs and instruction linting',
+  })
+
+  maxAttempts = Option.String('--max-attempts', {
+    description: 'Maximum validation attempts',
+    validator: t.applyCascade(t.isNumber(), [t.isAtLeast(1)]),
+  })
+
+  timeout = Option.String('--timeout', {
+    description: 'Compiler Assembly timeout in milliseconds',
+    validator: t.applyCascade(t.isNumber(), [t.isAtLeast(1)]),
+  })
+
+  inputs = inputPathsOption()
+
+  outputPath = Option.String('--output,-o', {
+    description: 'Specify an output file or directory',
+  })
+
+  fields = Option.Array('--field,-f', {
+    description: 'Set an Assembly field (KEY=VAL)',
+  })
+
+  watch = watchOption()
+
+  recursive = recursiveOption()
+
+  deleteAfterProcessing = deleteAfterProcessingOption()
+
+  reprocessStale = reprocessStaleOption()
+
+  singleAssembly = singleAssemblyOption()
+
+  concurrency = concurrencyOption()
+
+  printUrls = printUrlsOption()
+
+  protected async run(): Promise<number | undefined> {
+    const inputList = this.inputs ?? []
+
+    if (inputList.length === 0 && !process.stdin.isTTY) {
+      inputList.push('-')
+    }
+
+    const fieldsMap = parseTemplateFieldAssignments(this.output, this.fields)
+    if (this.fields != null && fieldsMap == null) {
+      return 1
+    }
+
+    const sharedValidationError = validateSharedFileProcessingOptions({
+      explicitInputCount: this.inputs?.length ?? 0,
+      singleAssembly: this.singleAssembly,
+      watch: this.watch,
+      watchRequiresInputsMessage: 'run --watch requires at least one input',
+    })
+    if (sharedValidationError != null) {
+      this.output.error(sharedValidationError)
+      return 1
+    }
+
+    let compiled: Awaited<ReturnType<Transloadit['compileAssemblyInstructionsFromPrompt']>>
+    try {
+      compiled = await this.client.compileAssemblyInstructionsFromPrompt(
+        createCompileOptions({
+          maxAttempts: toPositiveInteger(
+            this.maxAttempts == null ? undefined : Number(this.maxAttempts),
+            '--max-attempts',
+          ),
+          mcpServerUrl: this.mcpServerUrl,
+          model: this.model,
+          prompt: this.prompt,
+          timeout: toPositiveInteger(
+            this.timeout == null ? undefined : Number(this.timeout),
+            '--timeout',
+          ),
+        }),
+      )
+    } catch (error) {
+      this.output.error(formatAPIError(error))
+      return 1
+    }
+
+    const { hasFailures, resultUrls } = await create(this.output, this.client, {
+      stepsData: parseStepsInputJson(JSON.stringify(compiled.instructions.steps)),
+      fields: fieldsMap ?? {},
+      watch: this.watch,
+      recursive: this.recursive,
+      inputs: inputList,
+      output: this.outputPath ?? null,
+      del: this.deleteAfterProcessing,
+      reprocessStale: this.reprocessStale,
+      singleAssembly: this.singleAssembly,
+      concurrency: this.concurrency == null ? undefined : Number(this.concurrency),
+    })
+    if (this.printUrls) {
+      printResultUrls(this.output, resultUrls)
+    }
+    return hasFailures ? 1 : undefined
+  }
+}
+
 export class AssembliesListCommand extends AuthenticatedCommand {
   static override paths = [
     ['assemblies', 'list'],

package/src/cli/commands/index.ts

@@ -9,6 +9,8 @@ import {
   AssembliesLintCommand,
   AssembliesListCommand,
   AssembliesReplayCommand,
+  AssemblyInstructionsCompileCommand,
+  RunCommand,
 } from './assemblies.ts'
 import { SignatureCommand, SmartCdnSignatureCommand, TokenCommand } from './auth.ts'
 import { BillsGetCommand } from './bills.ts'
@@ -65,6 +67,10 @@ export function createCli(): Cli {
   // Uploads commands
   cli.register(UploadCommand)
 
+  // Prompt-to-Assembly-Instructions commands
+  cli.register(AssemblyInstructionsCompileCommand)
+  cli.register(RunCommand)
+
   // Documentation commands (offline metadata)
   cli.register(DocsRobotsListCommand)
   cli.register(DocsRobotsGetCommand)

package/src/cli/semanticIntents/imageDescribe.ts

@@ -18,7 +18,7 @@ const wordpressDescribeFields = [
   'description',
 ] as const satisfies readonly ImageDescribeField[]
 
-const defaultDescribeModel = 'anthropic/claude-4-sonnet-20250514'
+const defaultDescribeModel = 'anthropic/claude-sonnet-5'
 const describeFieldDescriptions = {
   altText: 'A concise accessibility-focused alt text that objectively describes the image',
   title: 'A concise publishable title for the image',
@@ -53,8 +53,7 @@ const imageDescribeExecutionDefinition = {
       kind: 'string',
       propertyName: 'model',
       optionFlags: '--model',
-      description:
-        'Model to use for generated text fields (default: anthropic/claude-4-sonnet-20250514)',
+      description: 'Model to use for generated text fields (default: anthropic/claude-sonnet-5)',
       required: false,
     },
   ] as const satisfies readonly IntentOptionDefinition[],