transloadit 5.2.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transloadit",
-  "version": "5.2.0",
+  "version": "6.0.0",
   "description": "Node.js SDK for Transloadit",
   "homepage": "https://github.com/transloadit/node-sdk/tree/main/packages/node",
   "bugs": {

package/src/alphalib/aiMessages.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod'
+import { z } from 'zod/v3'
 
 import { isRecord } from './object.ts'
 

package/src/alphalib/types/assemblyStatus.ts

@@ -130,6 +130,7 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'CLOUDFLARE_STORE_VALIDATION',
   'CLOUDFLARE_STORE_WRONG_REGION',
   'CLOUD_AI_IMAGE_VALIDATION',
+  'DAM_STORAGE_UNAVAILABLE',
   'DIGITALOCEAN_IMPORT_ACCESS_DENIED',
   'DIGITALOCEAN_IMPORT_FAILURE',
   'DIGITALOCEAN_IMPORT_NOT_FOUND',
@@ -190,6 +191,7 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'GOOGLE_IMPORT_FAILURE',
   'GOOGLE_IMPORT_NOT_FOUND',
   'GOOGLE_IMPORT_VALIDATION',
+  'GOOGLE_STORE_ACCESS_DENIED',
   'GOOGLE_STORE_INVALID_INPUT',
   'GOOGLE_STORE_VALIDATION',
   'HTML_CONVERT_VALIDATION',
@@ -399,6 +401,9 @@ export const assemblyStatusErrCodeSchema = z.enum([
 export type AssemblyStatusErrCode = z.infer<typeof assemblyStatusErrCodeSchema>
 
 const metadataTextSchema = z.union([z.string(), z.number().finite()])
+const metadataDateSchema = z.union([metadataTextSchema, z.array(metadataTextSchema)])
+// Readers must survive new server errors; the exported known-code enum remains closed.
+const publicAssemblyErrorCodeSchema = z.string().min(1)
 
 const assemblyStatusMetaSchema = z
   .object({
@@ -406,7 +411,7 @@ const assemblyStatusMetaSchema = z
     has_alpha: storedAssetSchema.shape.has_alpha,
     width: z.union([z.number(), z.null()]).optional(),
     height: z.union([z.number(), z.null()]).optional(),
-    date_file_modified: z.string().nullable().optional(),
+    date_file_modified: metadataDateSchema.nullable().optional(),
     aspect_ratio: z.union([z.number(), z.string(), z.null()]).optional(),
     has_clipping_path: z.boolean().optional(),
     frame_count: z.union([z.number(), z.null()]).optional(),
@@ -415,14 +420,14 @@ const assemblyStatusMetaSchema = z
     average_color: z.string().nullable().optional(),
     svgViewBoxWidth: z.union([z.number(), z.null()]).optional(),
     svgViewBoxHeight: z.union([z.number(), z.null()]).optional(),
-    date_recorded: z.union([z.string(), z.number()]).nullable().optional(),
-    date_file_created: metadataTextSchema.nullable().optional(),
+    date_recorded: metadataDateSchema.nullable().optional(),
+    date_file_created: metadataDateSchema.nullable().optional(),
     title: z.union([z.string(), z.number()]).nullable().optional(),
     description: metadataTextSchema.nullable().optional(),
     duration: z.union([z.number(), z.null()]).optional(),
     location: z.string().nullable().optional(),
     city: z.string().nullable().optional(),
-    state: z.string().nullable().optional(),
+    state: metadataTextSchema.nullable().optional(),
     rights: z.union([z.string(), z.number()]).nullable().optional(),
     country: z.string().nullable().optional(),
     country_code: z.string().nullable().optional(),
@@ -469,7 +474,7 @@ const assemblyStatusMetaSchema = z
     xp_title: metadataTextSchema.nullable().optional(),
     xp_comment: z.string().nullable().optional(),
     xp_keywords: metadataTextSchema.nullable().optional(),
-    xp_subject: z.string().nullable().optional(),
+    xp_subject: metadataTextSchema.nullable().optional(),
     recognized_text: z
       .union([
         z.array(z.string()),
@@ -560,8 +565,8 @@ const assemblyStatusMetaSchema = z
     page_count: z.union([z.number(), z.null()]).optional(),
     page_size: z.string().nullable().optional(),
     producer: z.string().nullable().optional(),
-    create_date: metadataTextSchema.nullable().optional(),
-    modify_date: z.union([z.string(), z.number()]).nullable().optional(),
+    create_date: metadataDateSchema.nullable().optional(),
+    modify_date: metadataDateSchema.nullable().optional(),
     colortransfer: z.string().nullable().optional(),
     colorprimaries: z.string().nullable().optional(),
     archive_directory: z.string().nullable().optional(),
@@ -655,7 +660,7 @@ export const assemblyStatusUploadSchema = z
     has_alpha: storedAssetSchema.shape.has_alpha,
     name: z.string().nullable(),
     basename: z.string().nullable(),
-    ext: z.string(),
+    ext: z.string().nullable(),
     size: z.number(),
     mime: z.string().nullable(),
     type: z.string().nullable(),
@@ -918,7 +923,7 @@ export const assemblyStatusOkSchema: AssemblyStatusVariant<{
   .passthrough()
 
 const assemblyStatusErrorFields = z.object({
-  error: assemblyStatusErrCodeSchema,
+  error: publicAssemblyErrorCodeSchema,
   ok: z.null().optional(),
   retries: z.number().optional(),
   numRetries: z.number().optional(),
@@ -996,12 +1001,13 @@ export type AssemblyStatus = z.infer<typeof assemblyStatusSchema>
  */
 export function hasError(
   assembly: AssemblyStatus | undefined | null,
-  particularErrorCode?: z.infer<typeof assemblyStatusErrCodeSchema>,
+  // Keep known-code suggestions while matching future public response codes too.
+  particularErrorCode?: AssemblyStatusErrCode | (string & {}),
 ): assembly is AssemblyStatusError {
   const errorExists =
     Boolean(assembly) && assembly != null && typeof assembly === 'object' && 'error' in assembly
 
-  if (particularErrorCode) {
+  if (particularErrorCode !== undefined) {
     return errorExists && assembly.error === particularErrorCode
   }
 
@@ -1079,7 +1085,7 @@ export function isAssemblyOkStatus(
 }
 
 /**
- * Type guard to check if a status string is an error state.
+ * Type guard to check if a status string is a known error code.
  */
 export function isAssemblyErrorStatus(
   status: string | undefined | null,
@@ -1123,7 +1129,11 @@ export function isAssemblyTerminalOk(assembly: AssemblyStatus | undefined | null
  * Returns true if the assembly has a terminal error state.
  */
 export function isAssemblyTerminalError(assembly: AssemblyStatus | undefined | null): boolean {
-  return isAssemblyErrorStatus(getError(assembly)) || isAssemblySysError(assembly)
+  // getError() historically stringifies explicit undefined; classification needs the raw value.
+  return (
+    (hasError(assembly) && publicAssemblyErrorCodeSchema.safeParse(assembly.error).success) ||
+    isAssemblySysError(assembly)
+  )
 }
 
 /**
@@ -1185,7 +1195,7 @@ export const assemblyIndexItemSchema = z
     bytes_received: assemblyStatusBaseSchema.shape.bytes_received.optional(),
     upload_duration: assemblyStatusBaseSchema.shape.upload_duration.optional(),
     ok: assemblyStatusOkCodeSchema.nullable().optional(),
-    error: assemblyStatusErrCodeSchema.nullable().optional(),
+    error: publicAssemblyErrorCodeSchema.nullable().optional(),
     created: z.string(),
     created_ts: z.number().optional(),
     template_name: z.string().nullable().optional(),

package/src/alphalib/types/robots/_ai-models.ts

@@ -20,6 +20,7 @@ export const MODEL_CAPABILITIES: Readonly<Record<string, { pdf: boolean; image:
     'anthropic/claude-fable-5': { pdf: true, image: true },
     'anthropic/claude-fable-5-1': { pdf: true, image: true },
     'anthropic/claude-sonnet-5': { pdf: true, image: true },
+    'anthropic/claude-sonnet-5-5': { pdf: true, image: true },
     'openai/gpt-4.1-2025-04-14': { pdf: false, image: true },
     'openai/chatgpt-4o-latest': { pdf: false, image: true },
     'openai/o3-2025-04-16': { pdf: false, image: true },
@@ -33,6 +34,7 @@ export const MODEL_CAPABILITIES: Readonly<Record<string, { pdf: boolean; image:
     'openai/gpt-5.5': { pdf: false, image: true },
     'openai/gpt-5.6-sol': { pdf: false, image: true },
     'openai/gpt-6-astra': { pdf: false, image: true },
+    'openai/gpt-6.1-sol': { pdf: false, image: true },
     'openai/gpt-5.4': { pdf: false, image: true },
     'openai/gpt-5.4-mini': { pdf: false, image: true },
     'openai/gpt-5.4-nano': { pdf: false, image: true },

package/src/alphalib/types/robots/_google-image-seed.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+/** Google’s signed 32-bit seed ceiling, shared by provider and Robot validation. */
+export const googleImageSeedMaximum = 2_147_483_647
+
+/** Validation message for the seed range supported by Google and the cloudai CLI. */
+export const googleImageSeedValidationMessage = `seed must be an integer from 0 to ${googleImageSeedMaximum}`
+
+/** Google image seeds must fit int32 and preserve the CLI’s nonnegative seed contract. */
+export const googleImageSeedSchema = z
+  .number()
+  .int(googleImageSeedValidationMessage)
+  .min(0, googleImageSeedValidationMessage)
+  .max(googleImageSeedMaximum, googleImageSeedValidationMessage)

package/src/alphalib/types/robots/_instructions-primitives.ts

@@ -2048,25 +2048,23 @@ While we recommend to use <dfn>Template Credentials</dfn> at all times, some use
   })
   .strict()
 
-export type GoogleBase = z.infer<typeof googleBase>
-export const googleBase = z
-  .object({
-    credentials: z
-      .string()
-      .optional()
-      .describe(`
-Create a new [Google service account](https://cloud.google.com/storage/docs/authentication). Set its role to "Storage Object Creator". Choose "JSON" for the key file format and download it to your computer. You will need to upload this file when creating your <dfn>Template Credentials</dfn>.
+/** Shared Google credential setup with permissions supplied by the importing or storing Robot. */
+export function getGoogleCredentialsDescription(permissions: string): string {
+  return `
+Create a new [Google service account](https://cloud.google.com/storage/docs/authentication). Choose “JSON” for the key file format and download it to your computer. You will need to upload this file when creating your <dfn>Template Credentials</dfn>.
 
 Go back to your Google credentials project and enable the "Google Cloud Storage JSON API" for it. Wait around ten minutes for the action to propagate through the Google network. Grab the project ID from the dropdown menu in the header bar on the Google site. You will also need it later on.
 
-Now you can set up the \`storage.objects.create\` and \`storage.objects.delete\` permissions. The latter is optional and only required if you intend to overwrite existing paths.
-
-To do this from the Google Cloud console, navigate to "IAM &amp; Admin" and select "Roles". From here, click "Create Role", enter a name, set the role launch stage to _General availability,_ and set the permissions stated above.
-
-Next, go to Storage browser and select the ellipsis on your bucket to edit bucket permissions. From here, select "Add Member", enter your service account as a new member, and select your newly created role.
+${permissions.trim()}
 
 Then, create your associated [Template Credentials](/c/template-credentials/) in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value.
-`),
+`
+}
+
+export type GoogleBase = z.infer<typeof googleBase>
+export const googleBase = z
+  .object({
+    credentials: z.string().optional(),
   })
   .strict()
 
@@ -2314,7 +2312,7 @@ For example:
 }
 \`\`\`
 
-This will crop the area from \`(80, 100)\` to \`(600, 800)\` from a 1000×1000 pixels video, which is a square whose width is 520px and height is 700px. If \`crop\` is set, the width and height parameters are ignored, and the \`resize_strategy\` is set to \`crop\` automatically.
+This will crop the area from \`(80, 100)\` to \`(600, 800)\` from a 1000×1000 pixels video, which is a rectangle whose width is 520px and height is 700px. If \`crop\` is set, the width and height parameters are ignored, and the \`resize_strategy\` is set to \`crop\` automatically.
 
 You can also use a JSON string of such an object with coordinates in similar fashion:
 

package/src/alphalib/types/robots/ai-chat.ts

@@ -51,13 +51,12 @@ type Part<Type extends MessagePart['type']> = Extract<MessagePart, { type: Type
 type ToolOutput = Part<'tool-result'>['output']
 
 type ProviderMetadata = NonNullable<z.output<typeof providerMetadataSchema>>
-type CompatibleProviderOptions<Part extends { providerOptions?: ProviderMetadata }> = Omit<
-  Part,
-  'providerOptions'
-> & {
-  providerOptions?: ProviderMetadata
-  experimental_providerMetadata?: ProviderMetadata
-}
+// Zod output retains explicit undefined even when the consumer enables exact optional properties.
+type CompatibleProviderOptions<Part extends { providerOptions?: ProviderMetadata | undefined }> =
+  Omit<Part, 'providerOptions'> & {
+    providerOptions?: ProviderMetadata
+    experimental_providerMetadata?: ProviderMetadata
+  }
 type MessageProviderOptions = {
   providerOptions?: ProviderMetadata
   experimental_providerMetadata?: ProviderMetadata

package/src/alphalib/types/robots/google-import.ts

@@ -9,6 +9,7 @@ import { z } from 'zod'
 import {
   createStorageImportExample,
   defineRobot,
+  getGoogleCredentialsDescription,
   googleBase,
   next_page_token,
   path,
@@ -37,6 +38,11 @@ export const robotGoogleImportInstructionsSchema = robotBase
   .merge(googleBase)
   .extend({
     robot: z.literal('/google/import'),
+    credentials: googleBase.shape.credentials.describe(
+      getGoogleCredentialsDescription(`
+Grant the service account the “Storage Object Viewer” role on the bucket you want to import from. This provides \`storage.objects.get\` to download objects and \`storage.objects.list\` to list them. Imports do not need permission to create or delete objects. See [Google’s IAM roles for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-roles).
+`),
+    ),
     path: path.describe(`
 The path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example: \`images/avatar.jpg\`.
 
@@ -51,7 +57,7 @@ You can also use an array of path strings here to import multiple paths in the s
     recursive: recursive.describe(`
 Setting this to \`true\` will enable importing files from subdirectories and sub-subdirectories (etc.) of the given path.
 
-Please use the pagination parameters \`start_file_name\` and \`files_per_page\` wisely here.
+Please use the pagination parameters \`next_page_token\` and \`files_per_page\` wisely here.
 `),
     next_page_token: next_page_token.describe(`
 A string token used for pagination. The returned files of one paginated call have the next page token inside of their meta data, which needs to be used for the subsequent paging call.

package/src/alphalib/types/robots/google-store.ts

@@ -9,6 +9,7 @@ import { z } from 'zod'
 import {
   createStorageStoreExample,
   defineRobot,
+  getGoogleCredentialsDescription,
   googleBase,
   robotBase,
   robotStoreMeta,
@@ -39,19 +40,13 @@ The URL to the exported file in your Google bucket will be presented in the Tran
       .boolean()
       .optional()
       .describe('Whether the results of this Step should be present in the Assembly Status JSON'),
-    credentials: z.string().describe(`
-Create a new [Google service account](https://cloud.google.com/storage/docs/authentication). Set its role to "Storage Object Creator". Choose "JSON" for the key file format and download it to your computer. You will need to upload this file when creating your <dfn>Template Credentials</dfn>.
+    credentials: z.string().describe(
+      getGoogleCredentialsDescription(`
+Grant the service account \`storage.objects.create\` on the bucket you want to export to. The “Storage Object Creator” role provides this permission for new objects, but does not allow overwriting existing objects. Add \`storage.objects.delete\` only if you need to overwrite existing objects. See [Google’s IAM roles for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-roles).
 
-Go back to your Google credentials project and enable the "Google Cloud Storage JSON API" for it. Wait around ten minutes for the action to propagate through the Google network. Grab the project ID from the dropdown menu in the header bar on the Google site. You will also need it later on.
-
-Now you can set up the \`storage.objects.create\` and \`storage.objects.delete\` permissions. The latter is optional and only required if you intend to overwrite existing paths.
-
-To do this from the Google Cloud console, navigate to "IAM &amp; Admin" and select "Roles". From here, click "Create Role", enter a name, set the role launch stage to _General availability,_ and set the permissions stated above.
-
-Next, go to Storage browser and select the ellipsis on your bucket to edit bucket permissions. From here, select "Add Member", enter your service account as a new member, and select your newly created role.
-
-Then, create your associated [Template Credentials](/c/template-credentials/) in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value.
+For overwrites, create a custom role in “IAM &amp; Admin” → “Roles” with \`storage.objects.create\` and \`storage.objects.delete\`, then grant it to the service account on your bucket.
 `),
+    ),
     path: z
       .string()
       .default('${unique_prefix}/${file.url_name}')

package/src/alphalib/types/robots/http-import.ts

@@ -55,12 +55,16 @@ The URL from which the file to be imported can be retrieved.
 HTTPS URLs must present a valid certificate trusted by Transloadit and matching the requested hostname. Self-signed, expired, or hostname-mismatched certificates cause \`${httpImportRobotErrors.HTTP_IMPORT_FAILURE.error}\`.
 
 You can also specify an array of URLs or a string of \`|\` delimited URLs to import several files at once. Please also check the \`url_delimiter\` parameter for that.
+
+Delimited URL lists are split before variables are interpolated. A delimiter introduced by a variable remains part of that URL. To supply several URLs through a variable, have the entire \`url\` value interpolate to an array of URLs.
 `),
     url_delimiter: z
       .string()
       .default('|')
       .describe(`
 Provides the delimiter that is used to split the URLs in your \`url\` parameter value.
+
+The delimiter must be literal. Only delimiters outside interpolation expressions in the original \`url\` value separate imports; variable values are never split.
 `),
     headers: z
       .union([

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

@@ -7,6 +7,7 @@ import {
   imageGenerateLegacyModelAlias,
   imageGenerateModelIdentifiers,
 } from './_ai-models.ts'
+import { googleImageSeedMaximum } from './_google-image-seed.ts'
 import {
   autoProviderDescription,
   interpolateRobot,
@@ -101,7 +102,13 @@ Best practice:
       .describe(
         'Output format. Defaults depend on model: png for Google and OpenAI models, svg for recraft-v3, jpeg for others. Google models currently return PNG only.',
       ),
-    seed: z.number().optional().describe(robotParameterDocs.seed.description),
+    // Provider-specific limits are checked by the Robot so other models retain their seed range.
+    seed: z
+      .number()
+      .optional()
+      .describe(
+        `${robotParameterDocs.seed.description} For Google models, use an integer from 0 to ${googleImageSeedMaximum}. Each output increments the seed by 1, so the final output’s seed must also fit this range. A seed does not guarantee identical images.`,
+      ),
     aspect_ratio: z
       .string()
       .optional()

package/src/alphalib/types/robots/image-resize.ts

@@ -29,6 +29,34 @@ import {
 
 const imageResizeGravitySchema = z.union([positionSchema, z.enum(['attention', 'entropy'])])
 
+/** Input MIME types eligible for automatic libvips processing in /image/resize. */
+export const imageResizeDaemonInputMimes: readonly string[] = [
+  'image/jpg',
+  'image/jpeg',
+  'image/jxl',
+  'image/png',
+  'image/tiff',
+  'image/tiff-fx',
+  'image/gif',
+  'image/webp',
+  'image/svg',
+  'image/svg+xml',
+]
+
+/** Output formats eligible for automatic libvips processing in /image/resize. */
+export const imageResizeDaemonOutputFormats: readonly string[] = [
+  'heic',
+  'heif',
+  'jpeg',
+  'jpg',
+  'jxl',
+  'png',
+  'raw',
+  'tiff',
+  'webp',
+  'avif',
+]
+
 export const meta: RobotMetaInput = {
   ...robotImageProcessingMeta,
   example_code: createProcessingExample('resized', '/image/resize', {
@@ -171,14 +199,14 @@ Height of the new image, in pixels. If not specified, will default to the height
       .union([
         z
           .literal('crop')
-          .describe(`Cuts an area out of an image, discarding any overlapping parts. If the source image is smaller than the crop frame, it will be zoomed. This strategy is implied when you specify coordinates in the \`crop\` parameter, and cannot be used without it.
+          .describe(`Cuts an area out of an image. Coordinates in the \`crop\` parameter imply this strategy. With coordinates, ImageMagick crops without resizing; libvips enlarges the image if \`x2\` or \`y2\` exceeds its dimensions, even with \`zoom: false\`. Without coordinates, set both \`width\` and \`height\`; this uses \`fillcrop\`, with \`gravity\` selecting which part is kept. With the default \`zoom\` setting, this coordinate-free path scales the image to cover that rectangle before trimming.
 
 To crop around human faces, see [🤖/image/facedetect](https://transloadit.com/docs/robots/image-facedetect/) instead.`),
         z
           .literal('fillcrop')
           .describe(`Scales the image to fit into our 100×100 target while preserving aspect ratio, while trimming away any excess surface. This means both sides will become exactly 100 pixels, at the tradeoff of destroying parts of the image.
 
-By default the resulting image is horizontally/vertically centered to fill the target rectangle. Use the \`gravity\` parameter to change where to crop the image, such as \`"bottom\`" or \`"left\`".`),
+By default the resulting image is horizontally/vertically centered to fill the target rectangle. Use the \`gravity\` parameter to change where to crop the image, such as \`"bottom"\` or \`"left"\`.`),
         z
           .literal('fit')
           .describe(`Uses the larger side of the original image as a base for the resize. Aspect ratio is preserved. Either side will become at most 100 pixels.
@@ -224,7 +252,7 @@ For example:
 }
 \`\`\`
 
-This will crop the area from \`(80, 100)\` to \`(600, 800)\` from a 1000×1000 pixels image, which is a square whose width is 520px and height is 700px. If \`crop\` is set, the width and height parameters are ignored, and the \`resize_strategy\` is set to \`crop\` automatically.
+This will crop the area from \`(80, 100)\` to \`(600, 800)\` from a 1000×1000 pixels image, which is a rectangle whose width is 520px and height is 700px. If \`crop\` is set, the width and height parameters are ignored, and the \`resize_strategy\` is set to \`crop\` automatically.
 
 You can also use a JSON string of such an object with coordinates in similar fashion:
 
@@ -235,9 +263,11 @@ You can also use a JSON string of such an object with coordinates in similar fas
 To crop around human faces, see [🤖/image/facedetect](/docs/robots/image-facedetect/).
 `),
     gravity: imageResizeGravitySchema.default('center').describe(`
-The direction from which the image is to be cropped when \`"resize_strategy"\` is set to \`"crop"\` or \`"fillcrop"\`, but no crop coordinates are defined.
-
-You can also use \`"entropy"\` or \`"attention"\` for automatic point-of-interest cropping. \`"entropy"\` keeps the region with the highest Shannon entropy, while \`"attention"\` favors areas with luminance frequency, saturation, and skin-tone cues.
+Sets crop direction for \`crop\` or \`fillcrop\` without explicit coordinates.
+Content-aware \`attention\` and \`entropy\` need libvips, \`fillcrop\`, \`width\` and \`height\`.
+Effects such as \`sepia\` or \`text\`, and inputs such as HEIC, can use ImageMagick.
+It centers these crops and the Assembly reports a warning.
+Crop in a separate /image/resize Step before effects, or convert unsupported inputs to PNG first.
 `),
     strip: z
       .boolean()

package/src/alphalib/types/robots/s3-store.ts

@@ -38,48 +38,54 @@ export const robotS3StoreInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(s3Base)
   .extend({
+    // URL rewriting does not fix bucket addressing, and custom paths need not use file.url_name.
+    // Keep the bucket warning separate from the old blanket filename-sanitization claim.
     robot: z.literal('/s3/store').describe(`
 If you are new to Amazon S3, see our tutorial on [using your own S3 bucket](/docs/faq/how-to-set-up-an-amazon-s3-bucket/).
 
-The URL to the result file in your S3 bucket will be returned in the <dfn>Assembly Status JSON</dfn>. If your S3 bucket has versioning enabled, the version ID of the file will be returned within \`meta.version_id\`
+The URL to the result file in your S3 bucket will be returned in the <dfn>Assembly Status JSON</dfn>. A returned URL does not make a private object public or grant read access. If your S3 bucket has versioning enabled, the version ID of the file will be returned within \`meta.version_id\`.
 
 > [!Warning]
-> **Avoid permission errors.** By default, \`acl\` is set to \`"${s3StoreAclSchema.parse(undefined)}"\`. AWS S3 has a bucket setting called \`Block new public ACLs and uploading public objects\`. Set this to <strong>False</strong> in your bucket if you intend to leave \`acl\` as \`"${s3StoreAclSchema.parse(undefined)}"\`. Otherwise, you’ll receive permission errors in your Assemblies despite your S3 credentials being configured correctly.
+> **Configure private buckets explicitly.** The Robot’s default \`acl\` is still \`"${s3StoreAclSchema.parse(undefined)}"\`. For a private bucket, set \`acl: "bucket-default"\` and do not supply ACL or grant headers. This omits the generated ACL header and works with [Bucket owner enforced Object Ownership](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html), where ACLs are disabled. Keep S3 Block Public Access enabled. Setting \`acl: "private"\` still sends an ACL and is not equivalent to omitting it.
 
 > [!Warning]
-> **Use DNS-compliant bucket names.** Your bucket name [must be DNS-compliant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) and must not contain uppercase letters. Any non-alphanumeric characters in the file names will be replaced with an underscore, and spaces will be replaced with dashes. If your existing S3 bucket contains uppercase letters or is otherwise not DNS-compliant, rewrite the result URLs using the <dfn>Robot</dfn>’s \`url_prefix\` parameter.
+> **Use DNS-compliant bucket names.** Follow AWS’s [bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html). The \`url_prefix\` parameter changes returned URLs; it does not change the bucket or its access permissions.
 
 <span id="minimum-s3-iam-permissions" aria-hidden="true"></span>
 
 ## Limit access
 
-You will also need to add permissions to your bucket so that Transloadit can access it properly. Here is an example IAM policy that you can use. Following the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), it contains the **minimum required permissions** to export a file to your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.
+Use a dedicated AWS identity with access limited to the destination bucket and object prefix. Do not use [AWS root access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/root-user-best-practices.html). Store its access key ID, secret access key, bucket name and region as \`key\`, \`secret\`, \`bucket\` and \`bucket_region\` in <dfn>Template Credentials</dfn>, then reference their name with \`credentials\`. Trusted backend integrations can instead supply those parameters directly; do not expose AWS secrets in browser instructions.
 
-Please change \`{BUCKET_NAME}\` in the values for \`Sid\` and \`Resource\` accordingly. Also, this policy will grant the minimum required permissions to all your users. We advise you to create a separate Amazon IAM user, and use its User ARN (can be found in the "Summary" tab of a user [here](https://console.aws.amazon.com/iam/home#users)) for the \`Principal\` value. More information about this can be found [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/AccessPolicyLanguage_UseCases_s3_a.html).
+The following is an [identity-based IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html), attached to that dedicated identity, not a bucket policy. It intentionally has no \`Principal\`. Replace \`{BUCKET_NAME}\` and use a Robot \`path\` beginning with \`uploads/\`, or adapt both the policy prefix and the path together.
+
+This example covers uploads and failed multipart-upload cleanup with an explicit \`bucket_region\`, \`acl: "bucket-default"\`, no ACL/grant headers, no tags and S3-managed encryption (SSE-S3). Existing bucket policies, organization controls or endpoint policies can still deny access.
 
 \`\`\`json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
-      "Sid": "AllowTransloaditToStoreFilesIn{BUCKET_NAME}Bucket",
+      "Sid": "UploadAndAbortWithinPrefix",
       "Effect": "Allow",
-      "Action": ["s3:GetBucketLocation", "s3:ListBucket", "s3:PutObject", "s3:PutObjectAcl"],
-      "Resource": ["arn:aws:s3:::{BUCKET_NAME}", "arn:aws:s3:::{BUCKET_NAME}/*"]
+      "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
+      "Resource": "arn:aws:s3:::{BUCKET_NAME}/uploads/*"
     }
   ]
 }
 \`\`\`
 
-The \`Sid\` value is just an identifier for you to recognize the rule later. You can name it anything you like.
+The uploader uses either \`PutObject\` or \`CreateMultipartUpload\`, \`UploadPart\` and \`CompleteMultipartUpload\`; failed multipart uploads can trigger \`AbortMultipartUpload\`. AWS maps the successful upload operations to \`s3:PutObject\`. Write access can **overwrite an existing object key**; it is not add-only. Choose unique object paths and consider versioning for recovery.
 
-The policy needs to be separated into two parts, because the \`ListBucket\` action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. When targeting the objects there's a trailing slash and an asterisk in the \`Resource\` parameter, whereas when the policy targets the bucket, the slash and the asterisk are omitted.
+Add permissions only for features you use, following AWS’s [operation permission reference](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html):
 
-Please note that if you give the <dfn>Robot</dfn>'s \`acl\` parameter a value of \`"bucket-default"\`, then you do not need the \`"s3:PutObjectAcl"\` permission in your bucket policy.
+- Without an explicit \`bucket_region\`, region discovery can require \`s3:GetBucketLocation\` and fallback \`s3:ListBucket\` on the bucket ARN, \`arn:aws:s3:::{BUCKET_NAME}\`, without an object suffix. Supplying the correct region avoids these discovery requests.
+- ACL or grant headers require \`s3:PutObjectAcl\`; tags require \`s3:PutObjectTagging\` on the allowed object prefix. \`bucket-default\` does not remove ACL/grant headers you supply in \`headers\`.
+- Downloading private results requires separate read authorization. Even a URL generated with \`sign_urls_for\` needs the signing identity to have the appropriate read permissions.
 
-In order to build proper result URLs we need to know the region in which your S3 bucket resides. For this we require the \`GetBucketLocation\` permission. Figuring out your bucket's region this way will also slow down your Assemblies. To make this much faster and to also not require the \`GetBucketLocation\` permission, we have added the \`bucket_region\` parameter to the /s3/store and /s3/import Robots. We recommend using them at all times.
+S3 applies its [bucket encryption configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html) when no encryption override is sent. You can request SSE-KMS through \`headers\`, using \`x-amz-server-side-encryption: aws:kms\` and \`x-amz-server-side-encryption-aws-kms-key-id\`. When either bucket default encryption or request headers select [SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html), the uploading identity needs \`kms:GenerateDataKey\` on the relevant key, plus \`kms:Decrypt\` for multipart uploads. For a customer-managed key, grant these permissions with a compatible KMS key policy; the base S3 policy above does not include them. Do not add blanket \`kms:*\` or \`sts:*\` grants.
 
-Please keep in mind that if you use bucket encryption you may also need to add \`"sts:*"\` and \`"kms:*"\` to the bucket policy. Please read [here](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) and [here](https://aws.amazon.com/blogs/security/how-to-restrict-amazon-s3-bucket-access-to-a-specific-iam-role/) in case you run into trouble with our example bucket policy.
+Short-lived AWS credentials are a matching set of \`key\`, \`secret\` and \`session_token\`. Have a trusted backend obtain and refresh all three, then supply them together when it creates the Assembly. It can pass them directly in Robot instructions or save and update them together through the [Template Credentials API](/docs/api/template-credentials-post/). Keep all three out of browser instructions; replacing only the session token does not refresh expired access keys. This Robot passes the supplied credentials to S3; it does not assume a role or refresh expired credentials. Keep temporary credentials valid for the upload.
 `),
     path: storeFilePath,
     url_prefix: z
@@ -89,9 +95,7 @@ Please keep in mind that if you use bucket encryption you may also need to add \
 The URL prefix used for the returned URL, such as \`"http://my.cdn.com/some/path/"\`.
 `),
     acl: s3StoreAclSchema.describe(`
-The permissions used for this file.
-
-Please keep in mind that the default value \`"${s3StoreAclSchema.parse(undefined)}"\` can lead to permission errors due to the \`"Block all public access"\` checkbox that is checked by default when creating a new Amazon S3 Bucket in the AWS console.
+The ACL used for this file. The default remains \`"${s3StoreAclSchema.parse(undefined)}"\`, which can conflict with S3 Block Public Access and disabled ACLs. For modern private buckets, explicitly set \`"bucket-default"\` to omit the generated ACL header, and do not supply ACL/grant headers in \`headers\`. \`"private"\` still sends an ACL.
 `),
     check_integrity: z
       .boolean()
@@ -139,7 +143,7 @@ This parameter provides signed URLs in the result JSON (in the \`signed_url\` an
       .string()
       .optional()
       .describe(`
-The session token to use for the S3 store. This is only used if the credentials are from an IAM user with the \`sts:AssumeRole\` permission.
+The session token belonging to the temporary AWS access key ID and secret access key supplied for this upload. The Robot does not assume a role or refresh these credentials; they must remain valid for the upload.
 `),
   })
   .strict()

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

@@ -1,3 +1,4 @@
+import type { MODEL_CAPABILITIES } from './_ai-models.ts'
 import type {
   RobotDefinition,
   RobotMetaInput,
@@ -22,6 +23,15 @@ import {
 /** Markup over the AI provider cost for smart thumbnail selection. */
 export const smartThumbnailMarkupPercent = 50
 
+/** Dedicated vision model so /ai/chat default upgrades do not change thumbnail analysis costs. */
+export const smartThumbnailModel = 'openai/gpt-5.4-mini' satisfies keyof typeof MODEL_CAPABILITIES
+
+/** Maximum long-side dimension of scoring previews; returned thumbnails keep their output size. */
+export const smartThumbnailAnalysisMaxSize = 512
+
+/** Frame ranking needs little reasoning compared with general-purpose chat. */
+export const smartThumbnailReasoningEffort = 'low'
+
 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)
@@ -58,13 +68,15 @@ export const robotVideoThumbsInstructionsSchema = robotBase
   .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.
+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 and includes a warning. 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.
+Regular \`/video/thumbs\` processing charges still apply. AI frame analysis is billed separately at the underlying provider cost plus a ${smartThumbnailMarkupPercent}% Transloadit markup. Smart selection uses the dedicated \`${smartThumbnailModel}\` vision model with \`${smartThumbnailReasoningEffort}\` reasoning, independently of the \`/ai/chat\` default. The exact AI charge varies with the number of candidate frames and provider pricing.
 
-\`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.
+The AI scores preview copies capped at ${smartThumbnailAnalysisMaxSize} pixels on the long side, preserving aspect ratio and without enlarging smaller images. Returned thumbnails keep the requested output dimensions and format; larger outputs do not increase the scoring preview beyond this limit.
+
+\`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. Raising it can enlarge the pool up to three times \`count\`; higher limits have no effect.
 
 > [!Note]
 > Use \`count\` with smart selection. To consistently extract exact timestamps with \`offsets\`, set \`smart: false\`.
@@ -146,17 +158,19 @@ The AI evaluates frames based on:
 - Action and motion (avoiding transition frames)
 - Overall visual interest
 
-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.
+Regular \`/video/thumbs\` processing charges still apply. AI frame analysis uses a dedicated low-cost vision model with \`${smartThumbnailReasoningEffort}\` reasoning and preview copies capped at ${smartThumbnailAnalysisMaxSize} pixels on the long side. Returned thumbnails retain their requested dimensions and format. 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.
+If AI scoring fails, the Robot selects extracted candidates in chronological order and records a fallback reason. With no candidates, it attempts standard extraction. Both fallbacks add an Assembly warning. 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: 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 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.
 
+Raising this limit above three times \`count\` does not enlarge the pool. For example, \`count: 1\` analyzes at most three candidates.
+
 This parameter is only used when \`smart\` is \`true\`.
 `),
   })

package/src/alphalib/zodParseWithContext.ts

@@ -1,4 +1,4 @@
-import type { z } from 'zod'
+import type { z } from 'zod/v3'
 
 export type ZodIssueWithContext = z.ZodIssue & {
   parentObj: unknown